/wix-manage

CMS Data Items CRUD

Standard call shape (every curl below). The <AUTH> placeholder is shorthand for Authorization: Bearer <TOKEN> only. Body-bearing requests also need Content-Type: application/json.

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:

{
  "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" }
    }
  }
}

Bulk Insert Items

Endpoint: POST https://www.wixapis.com/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
}

Query Data Items

Endpoint: POST https://www.wixapis.com/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"
      }
    }
  }
}

Get Single Item

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

curl -X GET \
'https://www.wixapis.com/wix-data/v2/items/abc123?dataCollectionId=Products' \
-H 'Authorization: <AUTH>'

Update Data Item

Endpoint: PUT https://www.wixapis.com/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
    }
  }
}

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.

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
        }
      }
    ]
  }
}

Bulk Update Items

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

There is no update-by-filter endpoint. To update the items matching a filter, query them first (see Query Data Items), then send their ids to bulk update or bulk patch.

Important: Use id (not _id) at the element level. The data object 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.

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.

Important: This endpoint uses patches array with fieldModifications, NOT dataItems. 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 single REFERENCE field (the value is one item ID; for MULTI_REFERENCE the value shape differs, see the next example):

{
  "dataCollectionId": "events",
  "patches": [
    {
      "dataItemId": "event-id",
      "fieldModifications": [
        {
          "fieldPath": "venue",
          "action": "SET_FIELD",
          "setFieldOptions": {
            "value": "venue-item-id"
          }
        }
      ]
    }
  ]
}

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.

{
  "dataCollectionId": "Projects",
  "patches": [
    {
      "dataItemId": "project-item-id",
      "fieldModifications": [
        {
          "fieldPath": "team",
          "action": "SET_FIELD",
          "setFieldOptions": {
            "value": ["alice-item-id", "bob-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 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: a single REFERENCE field is set like any other value ("venue": "venue-item-id", as above). MULTI_REFERENCE links are written only by a SET_FIELD patch (single or bulk) or by the reference endpoints in Reference Fields below; insert, bulk insert, bulk save, PUT and bulk update all return 200 but silently drop multi-reference values (verified live) — read the item back after any of them.

Delete Data Item

Deletes are irreversible. Confirm with the user before calling either delete endpoint unless the request already names the items to remove.

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

curl -X DELETE \
'https://www.wixapis.com/wix-data/v2/items/abc123?dataCollectionId=Products' \
-H 'Authorization: <AUTH>'

Bulk Delete Items

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

{
  "dataCollectionId": "Products",
  "dataItemIds": ["item-id-1", "item-id-2", "item-id-3"]
}

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:

{
  "dataCollectionId": "Products"
}

Response:

{
  "totalCount": 42
}

Count with Filter:

{
  "dataCollectionId": "Products",
  "filter": {
    "$and": [
      { "inStock": true },
      { "price": { "$gte": 50 } }
    ]
  }
}

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

{
  "dataCollectionId": "Products",
  "dataItems": [
    {
      "id": "existing-item-id",
      "data": {
        "title": "Updated Product",
        "price": 199.99,
        "inStock": true
      }
    },
    {
      "data": {
        "title": "New Product",
        "price": 79.99,
        "inStock": true
      }
    }
  ],
  "returnEntity": true
}

Warning: When updating, the entire item is replaced. Include all fields you want to keep. Confirm with the user before saving over existing items.

Truncate Collection

Remove all items from a collection.

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

{
  "dataCollectionId": "TestCollection"
}

Warning: This permanently deletes ALL items in the collection and cannot be undone. Ask the user to confirm before calling it.

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:

{
  "dataCollectionId": "Products",
  "pipeline": {
    "stages": [
      {
        "group": {
          "groupIds": [
            {"key": "category", "expression": {"fieldPath": "category"}}
          ],
          "accumulators": [
            {
              "resultFieldName": "count",
              "sum": {"expression": {"numeric": 1}}
            }
          ]
        }
      }
    ]
  }
}

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.

Warning (verified live): writing IDs into a MULTI_REFERENCE field through insert, bulk insert, bulk save, or PUT update returns 200 and silently drops that field's value — no error is raised. Bulk update is a full-item replace like PUT and does the same: success: true, value dropped (verified live, bulk save on both its insert and update paths). Never trust the write response for reference links: read the item back with includeReferencedItems and confirm the linked items are there.

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

{
  "dataCollectionId": "Products",
  "dataItemReferences": [
    {
      "referringItemId": "product-item-id",
      "referringItemFieldName": "tags",
      "referencedItemId": "tag-1-item-id"
    },
    {
      "referringItemId": "product-item-id",
      "referringItemFieldName": "tags",
      "referencedItemId": "tag-2-item-id"
    }
  ],
  "returnEntity": true
}

Replace All References

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

{
  "dataCollectionId": "Products",
  "referringItemId": "product-item-id",
  "referringItemFieldName": "tags",
  "newReferencedItemIds": ["new-tag-1-id", "new-tag-2-id", "new-tag-3-id"]
}

Note: To remove all references, pass an empty array for newReferencedItemIds.

Remove References (Bulk)

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

{
  "dataCollectionId": "Products",
  "dataItemReferences": [
    {
      "referringItemId": "product-id-1",
      "referringItemFieldName": "tags",
      "referencedItemId": "tag-to-remove-id"
    }
  ]
}

Query with Referenced Items Expanded

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

{
  "dataCollectionId": "Products",
  "query": {
    "filter": {
      "inStock": true
    }
  },
  "includeReferencedItems": ["category", "tags"]
}

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)

{
  "query": {
    "paging": {
      "limit": 50,
      "offset": 100
    }
  }
}

Cursor-Based (Large Datasets)

{
  "query": {
    "cursorPaging": {
      "limit": 50,
      "cursor": "cursor-from-previous-response"
    }
  }
}

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:

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 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