> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# SaveDataItem

# Package: cms

# Namespace: DataItemService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item.md

## Permission Scopes:
Write Data Items: SCOPE.DC-DATA.WRITE

## Introduction

Inserts or updates an item in a collection.


The Save Data Item method inserts or updates the specified item, depending on whether it already exists in the collection.

+ If you don't provide an ID, a new item is created.

+ If you provide an ID that does not exist in the collection, a new item is created with that ID.

+ If an item with the ID you provide already exists in the collection, that item is updated. When an item is updated, its `data._updatedDate` field is changed to the current date and time.

> **Note:** When you provide an item with an ID that already exists in the collection, the payload you provide in `dataItem.data` replaces the existing item with that ID.
> This means that the item's previous fields and values are lost.

---

## REST API

### Schema

```
 Method: saveDataItem
 Description: Inserts or updates an item in a collection.   The Save Data Item method inserts or updates the specified item, depending on whether it already exists in the collection.  + If you don't provide an GUID, a new item is created.  + If you provide an GUID that does not exist in the collection, a new item is created with that GUID.  + If an item with the GUID you provide already exists in the collection, that item is updated. When an item is updated, its `data._updatedDate` field is changed to the current date and time.  > **Note:** When you provide an item with an GUID that already exists in the collection, the payload you provide in `dataItem.data` replaces the existing item with that GUID. > This means that the item's previous fields and values are lost.
 URL: https://www.wixapis.com/wix-data/v2/items/save
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, dataItem
 Method parameters: 
   param name: appOptions | type: appOptions | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying.  When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. 
   param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection in which to insert or update the item. | required: true
   param name: dataItem | type: DataItem   | required: true
        - name: id | type: string | description: Data item GUID. 
        - name: data | type: object | description: Data item contents.  Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:  + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. 
   param name: publishPluginOptions | type: PublishPluginOptions   
        - name: includeDraftItems | type: boolean | description: Whether to include draft items.  When `true`, both published and draft items are affected. Default: `false`. 
 Return type: SaveDataItemResponse
  - name: action | type: Action | description: The action carried out for the item. 
     - enum:
     -     INSERTED: A new item was added to the collection.
     -     UPDATED: An existing item in the collection was updated.
  - name: dataItem | type: DataItem | description: Inserted or updated data item. 
     - name: id | type: string | description: Data item GUID. 
     - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to 
     - name: data | type: object | description: Data item contents.  Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:  + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. 


```

### Examples

### Save item
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/save' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "dataItem": {
        "data": {
            "state": "California",
            "year": 2022,
            "city": "Los Angeles",
            "population": 3800000
        }
    }
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.cms.DataItemService.saveDataItem(dataCollectionId, item, options)
 Description: Inserts or updates an item in a collection.   The Save Data Item method inserts or updates the specified item, depending on whether it already exists in the collection.  + If you don't provide an GUID, a new item is created.  + If you provide an GUID that does not exist in the collection, a new item is created with that GUID.  + If an item with the GUID you provide already exists in the collection, that item is updated. When an item is updated, its `data._updatedDate` field is changed to the current date and time.  > **Note:** When you provide an item with an GUID that already exists in the collection, the payload you provide in `dataItem.data` replaces the existing item with that GUID. > This means that the item's previous fields and values are lost.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, item
 Method parameters: 
   param name: dataCollectionId | type: string | description: GUID of the collection in which to insert or update the item. | required: true
   param name: item | type: WixDataItem | description: Data item contents. Property-value pairs representing the data item's payload | required: true
        - name: _id | type: string | description: Data item GUID. 
        - name: _createdDate | type: Date | description: Date and time the item was added to the collection. 
        - name: _updatedDate | type: Date | description: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. 
        - name: _owner | type: string | description: GUID of the user who created the item. Can be modified with site owner permissions. 
   param name: options | type: WixDataSaveOptions  none 
        - name: suppressHooks | type: boolean | description: Whether to suppress data hooks. When `true`, data hooks typically triggered by this endpoint don't run.  **Note:** This option can only be used in code that runs in [the Wix site backend](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/about-the-site-backend.md).  Default: `false` 
        - name: appOptions | type: object | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying.  When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. 
        - name: saveReferences | type: boolean | description: Whether to create or replace references from multi-reference fields. When `true`, array values in multi-reference fields are stored as references. For new items, references are created. For existing items, existing references are replaced with the provided values. Multi-reference field values must be arrays of referenced item GUIDs (strings) or referenced items containing an `_id` field.  Default: `false` 
        - name: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. 
        - name: includeReferences | type: boolean | description: If true, referenced items are included. 
 Return type: PROMISE<WixDataItem>
  - name: _id | type: string | description: Data item GUID. 
  - name: _createdDate | type: Date | description: Date and time the item was added to the collection. 
  - name: _updatedDate | type: Date | description: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. 
  - name: _owner | type: string | description: GUID of the user who created the item. Can be modified with site owner permissions. 


```

### Examples

### save
```javascript
import { items } from '@wix/data';

async function save(dataCollectionId,item,options) {
  const response = await items.save(dataCollectionId,item,options);
};
```

### save (with elevated permissions)
```javascript
import { items } from '@wix/data';
import { auth } from '@wix/essentials';

async function mySaveMethod(dataCollectionId,item,options) {
  const elevatedSave = auth.elevate(items.save);
  const response = await elevatedSave(dataCollectionId,item,options);
}
```

### save (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { items } from '@wix/data';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { items },
  // Include the auth strategy and host as relevant
});


async function save(dataCollectionId,item,options) {
  const response = await myWixClient.items.save(dataCollectionId,item,options);
};
```

---