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.

Writing Image Fields

Read the collection schema before setting an image: IMAGE takes an HTTP URL or wix:image:// string; MEDIA_IMAGE takes a structured object. Never put a bare media ID, a URL string, or an editor media-search result directly into a MEDIA_IMAGE field. The API can return 200 and store an invalid string unchanged; an identical read-back is not proof that the image can render.

1. Reuse the selected image if it is already in the site's Media Manager. For a new external image, follow Upload Media to Wix. If the user requested a generated image, first follow Generate an Image with AI, then import it. Confirm before importing or changing site data unless the user already authorized it.
2. Build the field value from the Media Manager file descriptor: use file.media.image.image for image metadata, with file.id, file.url, and file.displayName as fallbacks for the ID, URL, and filename. Import can return PENDING without image metadata; fetch the ready descriptor using the upload recipe before using dimensions. Do not invent IDs or dimensions.
3. For a Wix-hosted image, preserve id, url, width, height, filename, and altText when available, and include a full uri: wix:image://v1/{id}/{encodedFilename}#originWidth={width}&originHeight={height}. An editor search result's uri may be only a media ID; resolve its file descriptor and build the CMS value rather than copying that result. An external image may instead use { "url": "https://example.com/photo.jpg", "altText": "Photo" }; not every supported object requires all the Wix-hosted metadata.
4. Insert the object under dataItem.data.<fieldKey>, or patch an existing item with SET_FIELD as below. For IMAGE, use the image URL or full Wix URI string instead of the object. Leave the collection's existing field type unchanged.
5. Read the item back and check the field against its declared type: for MEDIA_IMAGE, require an object with a usable image source and the intended image identity, not a string echoed by the API. Preserve unrelated item fields. When browser access is available, check the image in the CMS or bound view. Otherwise report that the structured value was saved and that rendering was not visually verified. If generation or import fails, report the missing image; do not write a placeholder or claim it was added.

Example — replace only the image field on an existing item:

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

The values below stand for metadata from the selected file, not values to fabricate.

Verify with GET https://www.wixapis.com/wix-data/v2/items/{dataItemId}?dataCollectionId=Milkshakes and inspect dataItem.data.image.

References: Patch Data Item, Import File, and Importing Files.

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