> 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 # PatchDataItem # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md ## Permission Scopes: Write Data Items: SCOPE.DC-DATA.WRITE ## Introduction Patches an item in a collection. This method modifies the specified item's existing data. Unlike [`Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch an item, specify its ID, the ID of the collection that contains it, and the modifications you want to apply. If an item is found in the specified collection with the specified ID, that item is patched. If the collection doesn't contain an item with that ID, the request fails. > **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. --- ## REST API ### Schema ``` Method: patchDataItem Description: Patches an item in a collection. This method modifies the specified item's existing data. Unlike [`Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch an item, specify its GUID, the GUID of the collection that contains it, and the modifications you want to apply. If an item is found in the specified collection with the specified GUID, that item is patched. If the collection doesn't contain an item with that GUID, the request fails. > **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. URL: https://www.wixapis.com/wix-data/v2/items/{patch.dataItemId} Method: PATCH # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId, patch, patch.dataItemId, patch.fieldModifications, patch.fieldModifications.fieldPath, patch.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 item to patch. | required: true param name: patch | type: Patch | 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`. Return type: PatchDataItemResponse - name: dataItem | type: DataItem | description: Patched 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 ### Patch single item conditionally: Only activate accounts that are currently deactivated. ```curl curl -X PATCH \ 'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "accounts", "patch": { "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228", "fieldModifications": [ { "action": "SET_FIELD", "setFieldOptions": { "value": true } } ] }, "condition": { "filter": { "active": false } } }' ``` ### Patch an item ```curl curl -X PATCH \ 'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "patch": { "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228", "fieldModifications": [ { "fieldPath": "state", "action": "SET_FIELD", "setFieldOptions": { "value": "California" } }, { "action": "REMOVE_FIELD", "fieldPath": "unusedField" }, { "fieldPath": "population", "action": "INCREMENT_FIELD", "incrementFieldOptions": { "value": 100000 } }, { "fieldPath": "tags", "action": "APPEND_TO_ARRAY", "appendToArrayOptions": { "value": "sunny" } }, { "fieldPath": "tags", "action": "REMOVE_FROM_ARRAY", "removeFromArrayOptions": { "value": "cold" } } ] } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.cms.DataItemService.patchDataItem(dataCollectionId, itemId, item, options) Description: Patches an item in a collection. This method modifies the specified item's existing data. Unlike [`Update Data Item`](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item.md), only the fields specified in the request are modified. Data that isn't explicitly modified remains unchanged. To patch an item, specify its GUID, the GUID of the collection that contains it, and the modifications you want to apply. If an item is found in the specified collection with the specified GUID, that item is patched. If the collection doesn't contain an item with that GUID, the request fails. > **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. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId, itemId, item Method parameters: param name: dataCollectionId | type: string | description: GUID of the collection that contains the item to patch. | 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: itemId | type: itemId none | required: true param name: options | type: WixDataPatchOptions none - name: patch | type: Patch | description: Patch to apply to the item. - 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). - name: suppressHooks | type: boolean | description: Whether to suppress data hooks. When `true`, data hooks typically triggered by this method don't run. > **Note:** This can only be used in code that runs in a [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 item. When a condition is provided, the item is 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: _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 ### patch ```javascript import { items } from '@wix/data'; async function patch(dataCollectionId,itemId,item,options) { const response = await items.patch(dataCollectionId,itemId,item,options); }; ``` ### patch (with elevated permissions) ```javascript import { items } from '@wix/data'; import { auth } from '@wix/essentials'; async function myPatchMethod(dataCollectionId,itemId,item,options) { const elevatedPatch = auth.elevate(items.patch); const response = await elevatedPatch(dataCollectionId,itemId,item,options); } ``` ### patch (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 patch(dataCollectionId,itemId,item,options) { const response = await myWixClient.items.patch(dataCollectionId,itemId,item,options); }; ``` ---