CMS Data Items CRUD

This recipe covers Create, Read, Update, Delete (CRUD) operations for Wix CMS data items, plus count, upsert, truncate, aggregate, and reference-field links.

Prerequisites

1. Wix CMS enabled on the site (appDefId: e593b0bd-b783-45b8-97c2-873d42aacaf4)
2. Collections already created (see CMS Schema Management)
3. API access with CMS permissions

Required APIs

• Data Items API: REST

Know the Schema First

Before inserting or updating items, you need to know the collection's field names and types. If you don't already know the schema:

1. Query existing items - Fetch a few items to infer field names from the data
2. Get collection schema - Use GET https://www.wixapis.com/wix-data/v2/collections/{dataCollectionId} for full field definitions, including plugins — don't omit the plugins field when fetching or listing schemas
3. List collections - Use GET https://www.wixapis.com/wix-data/v2/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.

Insert Data Item

Endpoint: POST https://www.wixapis.com/wix-data/v2/items

Request Body:

Response:

Bulk Insert Items

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/insert

Request Body:

Query Data Items

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/query

Basic Query:

Advanced Query with Multiple Conditions:

Text Search:

Get Single Item

Endpoint: GET https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}

Update Data Item

Endpoint: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}

Request Body:

Patch Data Item (Partial Update - Single Item)

Endpoint: PATCH https://www.wixapis.com/wix-data/v2/items/{dataItemId}

Unlike Update, this only modifies the specified fields — all other fields remain unchanged.

Bulk Update Items

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/update

Bulk Patch Items (Partial Update)

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/patch

Unlike bulk update, this only modifies the specified fields - other fields remain unchanged. Use this for partial updates.

Setting a single REFERENCE field (the value is one item ID; for MULTI_REFERENCE the value shape differs, see the next example):

Setting a MULTI_REFERENCE field (verified live): the value is an array of item IDs, and SET_FIELD replaces the whole link set. To add links without dropping the existing ones, use Insert Multi-Reference Links instead. A plain string, or APPEND_TO_ARRAY, fails per item with WDE0303 inside a 200 bulk response — check results[].itemMetadata.

Available actions: SET_FIELD, REMOVE_FIELD, INCREMENT_FIELD, APPEND_TO_ARRAY, REMOVE_FROM_ARRAY

Delete Data Item

Endpoint: DELETE https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}

Bulk Delete Items

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/remove

Count Data Items

Count items in a collection, optionally with filters.

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/count

Count All Items:

Response:

Count with Filter:

Count returns only totalCount. When the user needs to know which items match, run Query Data Items with the same filter instead of, or after, counting.

Bulk Save (Upsert)

Insert new items or update existing items in a single operation. This is useful for syncing data.

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/save

Truncate Collection

Remove all items from a collection.

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/truncate

Aggregate Data

Perform calculations on collection data using a pipeline of sequential stages. The example shows one group stage; the full set of stages (filter, group, sort, projection, unwindArray, skip, limit) and accumulators is in the Aggregate Pipeline Data Items reference.

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/aggregate-pipeline

Count by Category:

Operation Comparison

Reference Fields

Reference fields link items across collections. A single REFERENCE field holds one item ID and is set like any other value in insert, update, or patch. A MULTI_REFERENCE field holds many links, and only two kinds of write create them: a SET_FIELD patch on the field (single or bulk), or the reference endpoints below, which add, replace, or remove links without touching the rest of the item. To add a reference field to a collection, see Add a Reference Field.

Linking flow, every time:

1. Resolve the referring item ID and the referenced item IDs (query by a field value; never guess IDs).
2. Write the links with the reference endpoints below, or with a SET_FIELD patch on the reference field. If the field already has links, insert-references adds without dropping them; replace-references and SET_FIELD discard the rest — confirm with the user before replacing unless the request says to.
3. Read the referring item back with Query Data Items and includeReferencedItems: ["<field>"] (or includeReferences: [{ "field": "<field>" }]), and confirm the linked items are present. The write's 200 is not proof; only the read-back is.

Insert Multi-Reference Links

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references

Replace All References

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/replace-references

Remove References (Bulk)

Endpoint: POST https://www.wixapis.com/wix-data/v2/bulk/items/remove-references

Query with Referenced Items Expanded

Endpoint: POST https://www.wixapis.com/wix-data/v2/items/query

The method article documents the same expansion as "includeReferences": [{ "field": "category" }, { "field": "tags", "limit": 50 }]; both forms work (verified live). Either way the expanded value is an array of item objects (with _id, name, …), not an array of IDs. Without one of these properties a MULTI_REFERENCE field is absent from the returned item, and a single REFERENCE field is returned as the item ID string (it is stored on the item; verified live).

Reference Query Operators

Field Types Reference

Query Operators

Pagination

Offset-Based (Simple)

Cursor-Based (Large Datasets)

Error Handling

Recovering from WDE0110

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:

After the installation succeeds, retry the original POST https://www.wixapis.com/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.

Related Documentation

• Data Items API Reference
• CMS Schema Management - Creating and modifying collections
• CMS Draft & Publish Workflow - Collections gated behind a draft/publish (Draft Items plugin) workflow