Setting the file. One moment.
Subchapter 8.23
references/cms/cms-data-items-crud.mdMarkdown14 KBView on GitHub
Standard call shape (every curl below). The
<AUTH>placeholder is shorthand forAuthorization: Bearer <TOKEN>only. Body-bearing requests also needContent-Type: application/json.
This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
e593b0bd-b783-45b8-97c2-873d42aacaf4)Before inserting or updating items, you need to know the collection’s field names and types. If you don’t already know the schema:
GET /collections/{dataCollectionId} for full field definitions, including plugins — don’t omit the plugins field when fetching or listing schemasGET /collections?fields=displayName,plugins to see what collections exist (see Schema Management)It may be, that user refers to schema by its displayName rather than id, if collection is not found list all collections to find the right id (dataCollectionId) to use.
Check for the Draft Items plugin. If the collection’s plugins include the Draft Items plugin, this collection gates items behind a draft/publish workflow. Stop and load CMS Draft & Publish Workflow before making any data changes, and follow its instructions instead of the plain CRUD flow below for that collection.
Endpoint: POST /wix-data/v2/items
Request Body:
{
"dataCollectionId": "Products",
"dataItem": {
"data": {
"title": "Wireless Headphones",
"price": 149.99,
"description": "Premium wireless headphones with noise cancellation",
"inStock": true,
"tags": ["wireless", "audio", "premium"]
}
}
}Response:
{
"dataItem": {
"id": "generated-item-id",
"dataCollectionId": "Products",
"data": {
"_id": "generated-item-id",
"title": "Wireless Headphones",
"price": 149.99,
"_createdDate": { "$date": "2024-01-15T10:00:00.000Z" },
"_updatedDate": { "$date": "2024-01-15T10:00:00.000Z" }
}
}
}Endpoint: POST /wix-data/v2/bulk/items/insert
Request Body:
{
"dataCollectionId": "Products",
"dataItems": [
{
"data": {
"title": "Bluetooth Speaker",
"price": 79.99,
"inStock": true
}
},
{
"data": {
"title": "USB-C Cable",
"price": 12.99,
"inStock": true
}
},
{
"data": {
"title": "Laptop Stand",
"price": 49.99,
"inStock": false
}
}
],
"returnEntity": true
}Endpoint: POST /wix-data/v2/items/query
Basic Query:
{
"dataCollectionId": "Products",
"query": {
"filter": {
"inStock": true
},
"sort": [
{
"fieldName": "price",
"order": "ASC"
}
],
"paging": {
"limit": 50,
"offset": 0
}
}
}Advanced Query with Multiple Conditions:
{
"dataCollectionId": "Products",
"query": {
"filter": {
"$and": [
{ "inStock": true },
{ "price": { "$gte": 50, "$lte": 200 } }
]
}
}
}Text Search:
{
"dataCollectionId": "Products",
"query": {
"filter": {
"title": {
"$contains": "wireless"
}
}
}
}Endpoint: GET /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}
curl -X GET \
'https://www.wixapis.com/wix-data/v2/items/abc123?dataCollectionId=Products' \
-H 'Authorization: <AUTH>'Endpoint: PUT /wix-data/v2/items/{itemId}
Request Body:
{
"dataCollectionId": "Products",
"dataItem": {
"data": {
"title": "Wireless Headphones Pro",
"price": 199.99,
"description": "Updated premium wireless headphones",
"inStock": true
}
}
}Endpoint: PATCH /wix-data/v2/items/{dataItemId}
Unlike Update, this only modifies the specified fields — all other fields remain unchanged.
Note: Only works on user-created collections. Wix app collections (e.g. Wix Stores Products) cannot be patched.
{
"dataCollectionId": "Products",
"patch": {
"dataItemId": "item-guid",
"fieldModifications": [
{
"fieldPath": "price",
"action": "SET_FIELD",
"setFieldOptions": {
"value": 159.99
}
},
{
"fieldPath": "description",
"action": "REMOVE_FIELD"
},
{
"fieldPath": "viewCount",
"action": "INCREMENT_FIELD",
"incrementFieldOptions": {
"value": 1
}
}
]
}
}Endpoint: POST /wix-data/v2/bulk/items/update
Important: Use
id(not_id) at the element level. Thedataobject should NOT contain_id.
{
"dataCollectionId": "Products",
"dataItems": [
{
"id": "item-guid-1",
"data": {
"price": 159.99,
"inStock": true
}
},
{
"id": "item-guid-2",
"data": {
"price": 89.99,
"inStock": false
}
}
]
}Note: This replaces the entire item. Include all fields you want to keep, not just the ones you’re changing.
Endpoint: POST /wix-data/v2/bulk/items/patch
Unlike bulk update, this only modifies the specified fields - other fields remain unchanged. Use this for partial updates.
Important: This endpoint uses
patchesarray withfieldModifications, NOTdataItems. Do not confuse with bulk update.
{
"dataCollectionId": "Products",
"patches": [
{
"dataItemId": "item-guid-1",
"fieldModifications": [
{
"fieldPath": "price",
"action": "SET_FIELD",
"setFieldOptions": {
"value": 159.99
}
}
]
},
{
"dataItemId": "item-guid-2",
"fieldModifications": [
{
"fieldPath": "price",
"action": "SET_FIELD",
"setFieldOptions": {
"value": 89.99
}
}
]
}
]
}Setting a reference field (single REFERENCE only):
{
"dataCollectionId": "events",
"patches": [
{
"dataItemId": "event-id",
"fieldModifications": [
{
"fieldPath": "venue",
"action": "SET_FIELD",
"setFieldOptions": {
"value": "venue-item-id"
}
}
]
}
]
}Available actions: SET_FIELD, REMOVE_FIELD, INCREMENT_FIELD, APPEND_TO_ARRAY, REMOVE_FROM_ARRAY
Common error: If you get
WDE0080: patches must not be empty, you sentdataItemsinstead ofpatches. Use the format above.
Recommended: Use bulk patch instead of bulk update when you only need to change specific fields.
Reference Fields:
- Single REFERENCE: CAN be set during insert/update by providing the referenced item’s ID as the field value (e.g.,
"venue": "venue-item-id")- MULTI_REFERENCE: STOP - You cannot use this recipe for multi-reference fields. They cannot be set via insert/update/patch.
For MULTI_REFERENCE operations (add speakers, assign tags, link categories, etc.): READ CMS References & Relationships for the exact endpoints and request bodies:
POST /wix-data/v2/bulk/items/insert-references- add referencesPOST /wix-data/v2/items/replace-references- replace all referencesPOST /wix-data/v2/bulk/items/remove-references- remove referencesError
WDE0303occurs when attempting to set multi-reference fields via data operations.
Endpoint: DELETE /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}
curl -X DELETE \
'https://www.wixapis.com/wix-data/v2/items/abc123?dataCollectionId=Products' \
-H 'Authorization: <AUTH>'Endpoint: POST /wix-data/v2/bulk/items/remove
{
"dataCollectionId": "Products",
"dataItemIds": ["item-id-1", "item-id-2", "item-id-3"]
}| Type | Description | Example Value |
|---|---|---|
TEXT | String | "Hello World" |
NUMBER | Numeric | 99.99 |
BOOLEAN | True/false | true |
DATE | Date only | "2024-01-15" |
DATETIME | Date and time | { "$date": "2024-01-15T10:00:00.000Z" } |
IMAGE | Image reference (HTTP url or wix:image://v1/{mediaId}/{friendlyName}) | "wix:image://v1/3f72369f2219e2ee853e9e3df0217ce1.jpg/Colorful%20Business%20Cards.jpg" |
VIDEO | Video reference (HTTP url or wix:video://v1/{mediaId}/{friendlyName}) | "wix:video://v1/11062b_484182533ede4b9a81329daf20238867/Sketching%20Design%20Concepts#posterUri=11062b_484182533ede4b9a81329daf20238867f000.jpg&posterWidth=1920&posterHeight=1080" |
DOCUMENT | Document reference (HTTP url or wix:document://v1/{mediaId}) | "wix:document://v1/..." |
MEDIA_IMAGE | Wix Media Image | { "id": "<mediaId>", "url": "http://...", "height": 640, "width": 480, "altText": "Picture" } |
MEDIA_VECTOR_ART | Wix Media Vector Art | { "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" } |
URL | Web URL | "https://example.com" |
RICH_TEXT | HTML content | "<p>Rich text</p>" |
EMAIL | "example@wix.com" | |
RICH_CONTENT | Structured content | Complex object |
ADDRESS | Address object | Address fields |
ARRAY_STRING | Array of strings | ["tag1", "tag2"] |
OBJECT | JSON object | {"key": "value"} |
REFERENCE | Single reference | Item ID string |
MULTI_REFERENCE | Multiple references, use separate reference endpoints to manipulate, include to include in queries | Array of IDs |
| Operator | Description | Example |
|---|---|---|
$eq | Equal | { "status": { "$eq": "active" } } |
$ne | Not equal | { "status": { "$ne": "archived" } } |
$gt | Greater than | { "price": { "$gt": 100 } } |
$gte | Greater or equal | { "price": { "$gte": 100 } } |
$lt | Less than | { "price": { "$lt": 50 } } |
$lte | Less or equal | { "price": { "$lte": 50 } } |
$in | In array | { "status": { "$in": ["active", "pending"] } } |
$contains | Contains string | { "title": { "$contains": "pro" } } |
$startsWith | Starts with | { "title": { "$startsWith": "Wireless" } } |
$and | All conditions | { "$and": [{...}, {...}] } |
$or | Any condition | { "$or": [{...}, {...}] } |
{
"query": {
"paging": {
"limit": 50,
"offset": 100
}
}
}{
"query": {
"cursorPaging": {
"limit": 50,
"cursor": "cursor-from-previous-response"
}
}
}WDE0110 means the Wix CMS (Wix Data) app is not installed on the site. If the user has
explicitly asked to install it, install the app before retrying the data-item request:
POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install{
"tenant": {
"tenantType": "SITE",
"id": "<SITE_ID>"
},
"appInstance": {
"appDefId": "e593b0bd-b783-45b8-97c2-873d42aacaf4"
}
}After the installation succeeds, retry the original POST /wix-data/v2/items request. If the
user only asks what the error means or how to fix it, explain this installation step and ask for
confirmation before performing the install.
| Error | Cause | Solution |
|---|---|---|
COLLECTION_NOT_FOUND | Invalid collection ID | Check collection exists |
ITEM_NOT_FOUND | Invalid item ID | Verify item exists |
VALIDATION_ERROR | Invalid field value | Check field types |
DUPLICATE_KEY | Duplicate unique field | Use unique values |
PERMISSION_DENIED | Insufficient access | Check API permissions |
WDE0007 | Bulk update: wrong ID field name | Use id not _id at element level |
WDE0080 | Validation failed (multiple causes) | Bulk update: don’t include _id in data; Bulk patch: use patches array not dataItems |
WDE0303 | Can’t set multi-reference field via data operations | Use reference endpoints: insert-references, replace-references |
WDE0110 | Wix CMS (Wix Data) application is not installed | Install application with appDefId: e593b0bd-b783-45b8-97c2-873d42aacaf4 |