# About the Data Items API

> **Note for app developers:** Wix Data APIs require the site's [code editor](portalId::bcc88c7b-94f5-4c35-b1cb-d7a20f2669b0resourceId::fd577f1d-9c28-4aba-acc2-d08943df22e2#code-editor*fallback::https://dev.wix.com/docs/develop-websites/articles/getting-started/development-environments#code-editor) to be enabled. If you are building a Wix app, add a [data collections extension](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/data-collections/about-data-collections-extensions) to automatically enable the code editor and create data collections when your app is installed on a site.


The Data Items API allows you to access and manage items in a Wix site's data collections.

With the Data Items API, you can:

- Create and manage data items in a site's collections.
- Publish and unpublish data items through an editorial draft lifecycle.
- Retrieve data items from a collection individually or with filtering and sorting queries.
- Create and manage reference fields.
- Update or remove many items asynchronously by filter.
- Perform aggregations and calculations on data in collections.
- Run advanced aggregation pipelines for complex data transformations.
- Truncate a data collection, removing all its contents.

The Data Items API only works with existing collections. To create and manage data collections, use the [Data Collections API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::c54f4e4c-34cf-4541-9844-04cd84f5662e*fallback::https://dev.wix.com/api/rest/wix-data/wix-data/data-collections).

## Before you begin

It's important to note the following points before starting to code:

- The maximum size of an item you can save to a collection is 500 kb.
- We don't recommend updating a data item more than once per second.
- When using data retrieval endpoints such as [Query Data Items](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::66a530fa-224c-48ee-841f-99a87365c6c3slug::query-data-items*fallback::https://dev.wix.com/api/rest/wix-data/wix-data/data-items/query-data-items) or [Get Data Item](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::66a530fa-224c-48ee-841f-99a87365c6c3slug::get-data-item*fallback::https://dev.wix.com/api/rest/wix-data/wix-data/data-items/get-data-item) following an update to a collection's data, the data retrieved may not yet contain the most recent changes. See [Wix Data and Eventual Consistency](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::673a16ab-f6a0-46ea-9e86-13da980a92ff*fallback::https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency) for more information and instructions for overriding this.
- When querying [Wix app collections](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/wix-app-collections/introduction), check which fields can be filtered in the relevant collection field article.
- Updating a data item replaces the existing item entirely. If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost.
- Aggregations can't be performed on [Wix app collections](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/wix-app-collections/introduction).
- After connecting external database collections to a Wix site using the [External Database Connections API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::ae9cab4a-b40b-48f1-b1b3-e659595e3440*fallback::https://dev.wix.com/api/rest/wix-data/wix-data/external-database-connections), you can use the Data Items API to manage and retrieve data from those collections as if they were Wix Data collections.

## Choose the right write method

Choose the write method that matches the change you want to make:

- Call [Save Data Item](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item) for rerunnable imports or sync jobs that should create a new item when it doesn't exist and update it when it does.
- Call [Patch Data Item](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item) or [Bulk Patch Data Items](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-patch-data-items) when you want to change only specific fields, keep the rest of the payload unchanged, or apply arithmetic actions such as incrementing a numeric field.
- Call [Update Data Item](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/update-data-item) or [Bulk Update Data Items](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-update-data-items) only when you intend to replace the existing payload with the values you send.

## Drafts and the publish lifecycle

Collections with the draft-items plugin enabled support an editorial workflow: each published item can have at most one pending draft revision. Drafts live in a **drafts shadow collection** whose ID is the published collection ID with a `__drafts` suffix. For example, when the published collection ID is `tutorials`, the drafts shadow collection ID is `tutorials__drafts`.

Use the drafts shadow collection ID when you create, query, update, or patch draft items directly. Use the **published** collection ID when you call lifecycle methods:

- [Create Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/create-data-item-draft) — creates a draft copy of a published item in the drafts shadow collection while the published item stays live. Returns `ALREADY_EXISTS` if a draft already exists for that item.
- [Publish Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/publish-data-item-draft) — replaces the published item with a pending draft and deletes the draft.
- [Unpublish Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/unpublish-data-item) — removes the published item and creates (or overwrites) a draft seeded with the previously-published data.

To process multiple items, use [Bulk Publish Data Item Drafts](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-publish-data-item-drafts) or [Bulk Unpublish Data Items](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-unpublish-data-items). Each item is processed independently, so a request can partly succeed. Check each result's `itemMetadata` for its outcome and use `originalIndex` to match it to the requested item ID.

By default, unpublishing copies the published item to the drafts shadow collection. Set `copyToDraft` to `false` to remove the published item without creating a draft. In that case, the unpublish response doesn't include a `dataItem`.

To list pending drafts, call [Query Data Items](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/query-data-items) with `dataCollectionId` set to the drafts shadow collection ID.

[Publish Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/publish-data-item-draft) always triggers domain events on both collections: a [Data Item Created](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-created) or [Data Item Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated) event on the published collection, and a [Data Item Deleted](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-deleted) event on the drafts shadow collection.

[Unpublish Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/unpublish-data-item) always triggers a [Data Item Deleted](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-deleted) event on the published collection. When `copyToDraft` is `true` (the default), it also triggers a [Data Item Created](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-created) or [Data Item Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated) event on the drafts shadow collection. When `copyToDraft` is `false`, no draft is created and no events fire on the drafts shadow collection.

## Collection IDs and field IDs

You need collection IDs and field IDs when working with the Data Items API to interact with a site's data. Collection IDs identify which specific collection your API calls should target. Field IDs specify which fields to include in queries or which fields to update when modifying collection items.

A collection ID is the user-defined identifier set when the collection is created, not a GUID. For example, a Wix user may set a collection ID to `EvalCustomers` or `EvalSystemLogs`. Item IDs (`dataItem.id`) are auto-assigned if you don't pass one, though you can also supply your own stable string when inserting an item.



## Use cases
+ [Populate a collection with content.](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows)
+ [Publish content through the editorial draft lifecycle.](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows)
+ [Publish a batch of reviewed drafts.](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows)
+ [Query data items by category.](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows)
+ [Get statistics for data item by category.](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows)

# Data Items API: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Populate a tutorials collection with content

You can use the Data Items API to programmatically add content to an existing collection.

This flow uses bulk operations to efficiently add multiple tutorials into [an existing tutorials collection](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/sample-flows).

To populate the tutorials collection:

1. Call [Bulk Insert Data Items](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-insert-data-items) with `dataCollectionId` set to `tutorials`. For each `dataItem`, include `fields` as structured in the data collection to be inserted. For reference fields like `category` and `author`, provide the ID of the referenced item from their respective collections.
1. Check the `results` array in the response to confirm each item inserted successfully. If any items fail, the `itemMetadata.error` property of the corresponding entry contains details about the error.

## Query tutorials by category

You can retrieve tutorials from [an existing tutorials collection](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/sample-flows) filtered by category and sorted by publish date. This is useful for displaying a list of tutorials in a specific topic area.

To query tutorials by category:

1. Call [Query Data Items](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/query-data-items) with `dataCollectionId` set to `tutorials` and filter by `category` sorted by `publishDate`.

## Get tutorial statistics by category

You can calculate aggregate statistics across tutorials in [an existing tutorials collection](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/sample-flows), such as the total number of tutorials and average reading time per category. This is useful for analytics dashboards or category overview pages.

To aggregate tutorial data:

1. Call [Aggregate Data Items](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/aggregate-data-items) with `dataCollectionId` set to `tutorials`.
1. In the `aggregation` object, set `groupingFields` to `["category"]` to group results by category.
1. In the `operations` array, add aggregation operations:
    - Add an operation with `resultFieldName` set to `totalTutorials` and `itemCount` set to an empty object to count tutorials per category.
    - Add an operation with `resultFieldName` set to `avgReadingTime`, `average.itemFieldName` set to `estimatedTime` to calculate the average reading time.
1. The response contains 1 result per category with the calculated `totalTutorials` and `avgReadingTime` values.

## Archive outdated tutorials asynchronously

You can patch a large set of items in the background when the target items are defined by a filter instead of a fixed list of IDs.

For example, you can mark all tutorials published before a cutoff date as archived without sending individual item IDs in the request.

To archive outdated tutorials:

1. Call [Async Patch Data Items By Filter](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/async-patch-data-items-by-filter) with `dataCollectionId` set to `tutorials`.
1. In `filter`, target the items you want to archive, such as tutorials published before a given date.
1. In `fieldModifications`, set `archived` to `true`.
1. Store the `jobId` returned in the response.
1. Poll [Get Async Job Status](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/get-async-job-status) until the job reaches `SUCCEEDED` or `FAILED`.

## Publish content through the editorial draft lifecycle

You can use the Data Items API to author content as drafts, publish drafts to the live collection, and retract published items back to draft when revisions are needed. This flow uses [an existing tutorials collection](fallback::https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/sample-flows) with the draft-items plugin enabled.

To publish a new tutorial through the draft lifecycle:

1. Call [Insert Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/insert-data-item) with `dataCollectionId` set to `tutorials__drafts` to create a draft. Include the tutorial fields in `dataItem.data`.
1. Edit the draft as needed via [Update Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item) or [Patch Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/patch-data-item), again with `dataCollectionId` set to `tutorials__drafts`.
1. Call [Publish Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/publish-data-item-draft) with `dataCollectionId` set to `tutorials` (the published collection ID) and `dataItemId` set to the draft's ID. The draft is deleted and the published collection now contains the live tutorial.

To revise a published tutorial while keeping it live on the site:

1. Call [Create Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/create-data-item-draft) with `dataCollectionId` set to `tutorials` and `dataItemId` set to the published tutorial's ID. A draft seeded with the current published data is created in `tutorials__drafts`. The published tutorial remains unchanged.
1. Edit the draft via [Update Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item) or [Patch Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/patch-data-item) with `dataCollectionId` set to `tutorials__drafts`.
1. Call [Publish Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/publish-data-item-draft) with `dataCollectionId` set to `tutorials` and `dataItemId` set to item to be published to put the revised tutorial live.

To revise a published tutorial by taking it offline first:

1. Call [Unpublish Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/unpublish-data-item) with `dataCollectionId` set to `tutorials` and `dataItemId` set to the published tutorial's ID. The published copy is removed and a draft is created in `tutorials__drafts`.
1. Edit the draft via [Update Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/update-data-item) or [Patch Data Item](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/patch-data-item) with `dataCollectionId` set to `tutorials__drafts`.
1. Call [Publish Data Item Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/publish-data-item-draft) with `dataCollectionId` set to `tutorials` to put the revised tutorial back live.

## Publish a batch of reviewed drafts

After editors review several tutorial drafts, you can publish them in one request while tracking any items that need attention.

To publish the reviewed drafts:

1. Call [Bulk Publish Data Item Drafts](fallback::https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-publish-data-item-drafts) with `dataCollectionId` set to `tutorials` and `dataItemIds` set to the IDs of the reviewed drafts. Set `returnEntity` to `true` if you need the published items in the response.
1. Check each entry in `results`. Use `itemMetadata.originalIndex` to match it to the corresponding ID in `dataItemIds`. If `itemMetadata.success` is `false`, inspect `itemMetadata.error` and address that item separately.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

Bulk Create Data Item Drafts