About the Data Items API

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.

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 or 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 for more information and instructions for overriding this.
• When querying Wix app collections, 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.
• After connecting external database collections to a Wix site using the External Database Connections API, 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 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 or 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 or 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 — 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 — replaces the published item with a pending draft and deletes the draft.
• Unpublish Data Item — removes the published item and creates (or overwrites) a draft seeded with the previously-published data.

To list pending drafts, call Query Data Items with dataCollectionId set to the drafts shadow collection ID.

Publish Data Item Draft always triggers domain events on both collections: a Data Item Created or Data Item Updated event on the published collection, and a Data Item Deleted event on the drafts shadow collection.

Unpublish Data Item always triggers a Data Item Deleted event on the published collection. When copyToDraft is true (the default), it also triggers a Data Item Created or 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.
• Publish content through the editorial draft lifecycle.
• Query data items by category.
• Get statistics for data item by category.