This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
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/{collectionId} for full field definitionsGET /collections?fields=id to see what collections exist (see Schema Management)Endpoint: POST /wix-data/v2/items
Request Body:
Response:
Endpoint: POST /wix-data/v2/bulk/items/insert
Request Body:
Endpoint: POST /wix-data/v2/items/query
Basic Query:
Advanced Query with Multiple Conditions:
Text Search:
Endpoint: GET /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}
Endpoint: PUT /wix-data/v2/items/{itemId}
Request Body:
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.
Endpoint: POST /wix-data/v2/bulk/items/update
Important: Use id (not _id) at the element level. The data object should NOT contain _id.
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 patches array with fieldModifications, NOT dataItems. Do not confuse with bulk update.
Setting a reference field (single REFERENCE only):
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 sent dataItems instead of patches. Use the format above.
Recommended: Use bulk patch instead of bulk update when you only need to change specific fields.
Reference Fields:
"venue": "venue-item-id")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 WDE0303 occurs when attempting to set multi-reference fields via data operations.
Endpoint: DELETE /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}
Endpoint: POST /wix-data/v2/bulk/items/remove
| 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": [{...}, {...}] } |
| 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 |