> 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 # BulkPatchDataItems # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-patch-data-items.md ## Permission Scopes: Write Data Items: SCOPE.DC-DATA.WRITE ## Introduction Patches one or more items in a collection. This method modifies the existing data of one or more items. Unlike [`Bulk Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-update-data-items.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch items, specify the ID of the collection that contains them. For each item, specify its ID and the modifications you want to apply. If the item is found in the specified collection with the specified ID, that item is patched. If no such item is found, the response's `results` array contains a corresponding item whose `itemMetadata.error` property contains details about the error. Learn more about [Wix Data error codes](https://dev.wix.com/docs/rest/business-solutions/cms/wix-data-error-codes.md). > **Notes**: > - When an item is patched, its `data._updatedDate` property is updated to the current date and time. > - You can only patch items in [collections created by Wix users](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection). Items in [Wix app collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code.md) cannot be patched. > - Calling the `Bulk Patch Data Items` method triggers the [`Data Item Updated`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated.md) event for each patched item. --- ## REST API ### Schema ``` Method: bulkPatchDataItems Description: Patches one or more items in a collection. This method modifies the existing data of one or more items. Unlike [`Bulk Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-update-data-items.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch items, specify the GUID of the collection that contains them. For each item, specify its GUID and the modifications you want to apply. If the item is found in the specified collection with the specified GUID, that item is patched. If no such item is found, the response's `results` array contains a corresponding item whose `itemMetadata.error` property contains details about the error. Learn more about [Wix Data error codes](https://dev.wix.com/docs/rest/business-solutions/cms/wix-data-error-codes.md). > **Notes**: > - When an item is patched, its `data._updatedDate` property is updated to the current date and time. > - You can only patch items in [collections created by Wix users](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection). Items in [Wix app collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code.md) cannot be patched. > - Calling the `Bulk Patch Data Items` method triggers the [`Data Item Updated`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated.md) event for each patched item. URL: https://www.wixapis.com/wix-data/v2/bulk/items/patch 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, patches, patches.dataItemId, patches.fieldModifications, patches.fieldModifications.fieldPath, patches.fieldModifications.action Method parameters: param name: condition | type: Condition - name: filter | type: object | description: Filter, changes to item(s) will only apply if they satisfy this filter. Learn more about filters in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#filters). param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection that contains the items to patch. | required: true param name: patches | type: array | description: Patches to apply to the items. | required: true - name: dataItemId | type: string | description: GUID of the item to patch. | required: true - name: fieldModifications | type: array | description: Modifications to apply. | required: true - ONE-OF: - name: setFieldOptions | type: SetFieldOptions | description: Options for setting the value of the specified field. Required when `action` is `SET_FIELD`. - name: value | type: Value | description: Value to set for the specified field. This replaces the existing value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: incrementFieldOptions | type: IncrementFieldOptions | description: Options for incrementing the value of the specified field. Required when `action` is `INCREMENT_FIELD`. - name: value | type: number | description: Numerical value by which to increment the field value. To decrement, specify a negative value. - name: appendToArrayOptions | type: AppendToArrayOptions | description: Options for appending a value to the specified array. Required when `action` is `APPEND_TO_ARRAY`. - name: value | type: Value | description: Value to append to the specified array. - name: removeFromArrayOptions | type: RemoveFromArrayOptions | description: Options for removing a value from the specified array. Required when `action` is `REMOVE_FROM_ARRAY`. - name: value | type: Value | description: Value whose first instance is removed from the specified array. - name: fieldPath | type: string | description: Path of the field to be modified. For example: `title`. Nested fields can be specified using dot notation. For example: `address.street`. - name: action | type: ACTION | description: Patch action to apply to the specified field. - enum: - SET_FIELD: Sets the specified field to the specified value. - REMOVE_FIELD: Clears the specified field. - INCREMENT_FIELD: Increments the specified field by the specified value. To decrement, specify a negative value. - APPEND_TO_ARRAY: Appends the specified value to the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). - REMOVE_FROM_ARRAY: Removes the first instance of the specified value from the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). 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 patched data items. When `true`, each item in the `results` array contains a `dataItem` field with the full patched data item. Default: `false` Return type: BulkPatchDataItemsResponse - name: results | type: array | description: Patched 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 ### Patch multiple items conditionally: Decrement count only when the specified value is positive. ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/bulk/items/patch' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "MyCollection", "patches": [ { "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228", "fieldModifications": [ { "fieldPath": "availableSeats", "action": "INCREMENT_FIELD", "incrementFieldOptions": { "value": -1 } } ] }, { "dataItemId": "01b60c9f-d793-4d21-a8d2-320c2099e56f", "fieldModifications": [ { "fieldPath": "availableSeats", "action": "INCREMENT_FIELD", "incrementFieldOptions": { "value": -1 } } ] } ], "condition": { "filter": { "count": { "$gt": 0 } } } }' ``` ### Bulk patch items ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/bulk/items/patch' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "test", "patches": [ { "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228", "fieldModifications": [ { "fieldPath": "state", "action": "SET_FIELD", "setFieldOptions": { "value": "California" } } ] }, { "dataItemId": "01b60c9f-d793-4d21-a8d2-320c2099e56f", "fieldModifications": [ { "fieldPath": "state", "action": "SET_FIELD", "setFieldOptions": { "value": "California" } } ] } ] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.cms.DataItemService.bulkPatchDataItems(dataCollectionId, items, options) Description: Patches one or more items in a collection. This method modifies the existing data of one or more items. Unlike [`Bulk Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-update-data-items.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch items, specify the GUID of the collection that contains them. For each item, specify its GUID and the modifications you want to apply. If the item is found in the specified collection with the specified GUID, that item is patched. If no such item is found, the response's `results` array contains a corresponding item whose `itemMetadata.error` property contains details about the error. Learn more about [Wix Data error codes](https://dev.wix.com/docs/rest/business-solutions/cms/wix-data-error-codes.md). > **Notes**: > - When an item is patched, its `data._updatedDate` property is updated to the current date and time. > - You can only patch items in [collections created by Wix users](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection). Items in [Wix app collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code.md) cannot be patched. > - Calling the `Bulk Patch Data Items` method triggers the [`Data Item Updated`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated.md) event for each patched item. # 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 that contains the items to patch. | required: true param name: items | type: array | description: Patches to apply to the items. | required: true - name: dataItemId | type: string | description: GUID of the item to patch. - name: fieldModifications | type: array | description: Modifications to apply. - ONE-OF: - name: setFieldOptions | type: SetFieldOptions | description: Options for setting the value of the specified field. Required when `action` is `SET_FIELD`. - name: value | type: Value | description: Value to set for the specified field. This replaces the existing value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: incrementFieldOptions | type: IncrementFieldOptions | description: Options for incrementing the value of the specified field. Required when `action` is `INCREMENT_FIELD`. - name: value | type: number | description: Numerical value by which to increment the field value. To decrement, specify a negative value. - name: appendToArrayOptions | type: AppendToArrayOptions | description: Options for appending a value to the specified array. Required when `action` is `APPEND_TO_ARRAY`. - name: value | type: Value | description: Value to append to the specified array. - name: removeFromArrayOptions | type: RemoveFromArrayOptions | description: Options for removing a value from the specified array. Required when `action` is `REMOVE_FROM_ARRAY`. - name: value | type: Value | description: Value whose first instance is removed from the specified array. - name: fieldPath | type: string | description: Path of the field to be modified. For example: `title`. Nested fields can be specified using dot notation. For example: `address.street`. - name: action | type: ACTION | description: Patch action to apply to the specified field. - enum: - SET_FIELD: Sets the specified field to the specified value. - REMOVE_FIELD: Clears the specified field. - INCREMENT_FIELD: Increments the specified field by the specified value. To decrement, specify a negative value. - APPEND_TO_ARRAY: Appends the specified value to the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). - REMOVE_FROM_ARRAY: Removes the first instance of the specified value from the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). param name: options | type: WixDataBulkPatchOptions 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: condition | type: Condition | description: Condition for patching the items. When a condition is provided, the items are only patched if the condition is met. - name: filter | type: object | description: Filter, changes to item(s) will only apply if they satisfy this filter. Learn more about filters in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#filters). - 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: results | type: array | description: Patched 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 ### bulkPatch ```javascript import { items } from '@wix/data'; async function bulkPatch(dataCollectionId,items,options) { const response = await items.bulkPatch(dataCollectionId,items,options); }; ``` ### bulkPatch (with elevated permissions) ```javascript import { items } from '@wix/data'; import { auth } from '@wix/essentials'; async function myBulkPatchMethod(dataCollectionId,items,options) { const elevatedBulkPatch = auth.elevate(items.bulkPatch); const response = await elevatedBulkPatch(dataCollectionId,items,options); } ``` ### bulkPatch (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 bulkPatch(dataCollectionId,items,options) { const response = await myWixClient.items.bulkPatch(dataCollectionId,items,options); }; ``` ---