> 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 # BulkSaveDataItems # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-save-data-items.md ## Permission Scopes: Write Data Items: SCOPE.DC-DATA.WRITE ## Introduction Inserts or updates multiple items in a collection. The Bulk Save Data Items method inserts or updates each item provided, depending on whether it already exists in the collection. For each item: + If you don't provide an ID, a new item is created. + If you provide an ID that doesn't 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 item you provide completely replaces the existing item with that ID. > This means that all of the item's previous fields and values are lost. --- ## REST API ### Schema ``` Method: bulkSaveDataItems Description: Inserts or updates multiple items in a collection. The Bulk Save Data Items method inserts or updates each item provided, depending on whether it already exists in the collection. For each item: + If you don't provide an GUID, a new item is created. + If you provide an GUID that doesn't 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 item you provide completely replaces the existing item with that GUID. > This means that all of the item's previous fields and values are lost. URL: https://www.wixapis.com/wix-data/v2/bulk/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, dataItems 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 items. | required: true param name: dataItems | type: array | description: Data items to insert or update. | 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`. param name: returnEntity | type: returnEntity | description: Whether to return the saved data items. When `true`, the `results` objects contain a `dataItem` field. Default: `false` Return type: BulkSaveDataItemsResponse - name: results | type: array | description: Information about the saved items. - name: action | type: BulkActionType | description: Action attempted for the data item. - enum: UNKNOWN_ACTION_TYPE, INSERT, UPDATE, DELETE, PATCH - name: itemMetadata | type: ItemMetadata | description: Item metadata. - name: id | type: string | description: Item GUID. Does not appear if the item GUID is missing. For example, when item creation fails. - name: originalIndex | type: integer | description: Original index of the item in the array specified in the request. Use this to match items in the request with those in the response. - name: success | type: boolean | description: Whether the requested action was successful. When `false`, the `error` field is populated. - name: error | type: ApplicationError | description: In case of failure, the error details. - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. - name: dataItem | type: DataItem | description: Updated data item. Returned if `returnEntity` is set to `true` and the action is successful. - 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. - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata. - name: totalSuccesses | type: integer | description: Number of items successfully processed. - name: totalFailures | type: integer | description: Number of items that couldn't be processed. ``` ### Examples ### Bulk save new items by inserting first one and updating another ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/bulk/items/save' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "dataItems": [ { "data": { "state": "California", "year": 2022, "city": "Los Angeles", "population": 3800000 } }, { "id": "6c38b4f7-7b8d-4702-9283-66a5889f8e17", "data": { "state": "California", "year": 2022, "city": "San Francisco", "population": 840000 } } ], "returnEntity": true }' ``` ### Bulk save new items ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/bulk/items/save' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "dataItems": [ { "data": { "state": "California", "year": 2022, "city": "Los Angeles", "population": 3800000 } }, { "data": { "state": "California", "year": 2022, "city": "San Francisco", "population": 840000 } } ] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.cms.DataItemService.bulkSaveDataItems(dataCollectionId, items, options) Description: Inserts or updates multiple items in a collection. The Bulk Save Data Items method inserts or updates each item provided, depending on whether it already exists in the collection. For each item: + If you don't provide an GUID, a new item is created. + If you provide an GUID that doesn't 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 item you provide completely replaces the existing item with that GUID. > This means that all of 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, items Method parameters: param name: dataCollectionId | type: string | description: GUID of the collection in which to insert or update the items. | required: true param name: items | type: array | description: Data items to insert or update. | 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: options | type: WixDataBulkSaveOptions 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. Return type: PROMISE - name: inserted | type: integer | description: Number of inserted items. - name: updated | type: integer | description: Number of updated items. - name: removed | type: integer | description: Number of removed items. - name: skipped | type: integer | description: Number of skipped items. - name: errors | type: array | description: List of errors. - name: message | type: string | description: Description of the error. - name: code | type: string | description: Error code. - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items. - name: item | type: string | description: Failed item (or GUID in case of `bulkRemove()`). - name: insertedItemIds | type: array | description: List of GUIDs of inserted items. - name: updatedItemIds | type: array | description: List of GUIDs of updated items. - name: removedItemIds | type: array | description: List of GUIDs of removed items. ``` ### Examples ### bulkSave ```javascript import { items } from '@wix/data'; async function bulkSave(dataCollectionId,items,options) { const response = await items.bulkSave(dataCollectionId,items,options); }; ``` ### bulkSave (with elevated permissions) ```javascript import { items } from '@wix/data'; import { auth } from '@wix/essentials'; async function myBulkSaveMethod(dataCollectionId,items,options) { const elevatedBulkSave = auth.elevate(items.bulkSave); const response = await elevatedBulkSave(dataCollectionId,items,options); } ``` ### bulkSave (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 bulkSave(dataCollectionId,items,options) { const response = await myWixClient.items.bulkSave(dataCollectionId,items,options); }; ``` ---