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.
  • Retrieve data items from a collection individually or with filtering and sorting queries.
  • Create and manage reference fields.
  • Perform aggregations and calculations on data in collections.
  • 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.
Was this helpful?
Yes
No

Data Item Object

Attributes
idstring
Data item ID.

datastruct
Data item contents. Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:
  • _id: Item ID.
  • _createdDate: Date and time the item was added to the collection.
  • _updatedDate: Date and time the item was last modified. When the item is first inserted, _createdDate and _updatedDate have the same value.
  • _ownerId: ID of the user who created the item. Can be modified with site owner permissions.
Was this helpful?
Yes
No

PostInsert Data Item

Adds an item to a collection.

An item can only be inserted into an existing connection. You can create a new collection using the Data Collections API.

When an item is inserted into a collection, the item's ID is automatically assigned a random value. You can optionally provide a custom ID in dataItem.id when inserting the item. If you specify an ID that already exists in the collection, the insertion will fail.

If dataItem.data is empty, a new item is created with no data fields.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items

Was this helpful?
Yes
No

PutUpdate Data Item

Updates an item in a collection.

This endpoint replaces the data item's existing data with the payload provided in dataItem.data in the request.

To update an item, you need to specify an item ID and a collection ID. If an item is found in the specified collection with the specified ID, that item is updated. If the collection doesn't contain an item with that ID, the request fails.

When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: After an item is updated, it only contains the fields included in the dataItem.data payload in Update Data Item request. If the existing item has fields with values and those fields aren't included in the updated item, their values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
PUT
https://www.wixapis.com/wix-data/v2/items/{dataItem.id}

Was this helpful?
Yes
No

PostSave Data Item

Inserts or updates an item in a collection.

The Save Data Item endpoint inserts or updates the specified item, depending on whether it already exists in the collection.

  • If you don't provide an ID, a new item is created.

  • If you provide an ID that does not exist in the collection, a new item is created with that ID.

  • If an item with the ID you provide already exists in the collection, that item is updated. When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: When you provide an item with an ID that already exists in the collection, the payload you provide in dataItem.data replaces the existing item with that ID. This means that the item's previous fields and values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/save

Was this helpful?
Yes
No

GetGet Data Item

Retrieves an item from a collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/wix-data/v2/items/{dataItemId}

Was this helpful?
Yes
No

DeleteRemove Data Item

Removes an item from a collection.

If any items in other collections reference the removed item in reference or multi-reference fields, those fields are cleared.

Note: Once an item has been removed from a collection, it can't be restored.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/wix-data/v2/items/{dataItemId}

Was this helpful?
Yes
No

PostTruncate Data Items

Removes all items from a collection.

If any items in other collections reference the removed items in reference or multi-reference fields, those fields are cleared.

Note: Once items have been removed from a collection, they can't be restored.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/truncate

Was this helpful?
Yes
No

PostQuery Data Items

Retrieves a list of items, on the basis of the filtering, sorting, and paging preferences you provide.

For more details on using queries, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query

Was this helpful?
Yes
No

PostAggregate Data Items

Runs an aggregation on a data collection and returns the resulting list of items.

An aggregation enables you to perform certain calculations on your collection data, or on groups of items that you define, to retrieve meaningful summaries. You can also add paging, filtering, and sorting preferences to your aggregation to retrieve exactly what you need.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/aggregate

Was this helpful?
Yes
No

PostCount Data Items

Counts the number of items in a data collection that match the provided filtering preferences.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/count

Was this helpful?
Yes
No

PostQuery Distinct Values

Retrieves a list of distinct values for a given field in all items that match a query, without duplicates.

As with the Query Data Items endpoint, this endpoint retrieves items based on the filtering, sorting, and paging preferences you provide. However, the Query Distinct Values endpoint doesn't return all of the full items that match the query. Rather, it returns all unique values of the field you specify in fieldName for items that match the query. If more than one item has the same value for that field, that value appears only once.

For more details on using queries, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query-distinct-values

Was this helpful?
Yes
No

PostBulk Insert Data Items

Adds multiple items to a collection.

When each item is inserted into a collection, its ID is automatically assigned a random value. You can optionally provide your own ID when inserting the item. If you specify an ID that already exists in the collection, the insertion will fail.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/insert

Was this helpful?
Yes
No

PostBulk Update Data Items

Updates multiple items in a collection.

This endpoint replaces each specified data item's existing data with the payload provided in the request.

Each item in the request must include an ID. If an item is found in the specified collection with the same ID, that item is updated. If the collection doesn't contain an item with that ID, the update fails.

When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: After each item is updated, it only contains the fields included in the request. If the existing item has fields with values and those fields aren't included in the updated item, their values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/update

Was this helpful?
Yes
No

PostBulk Save Data Items

Inserts or updates multiple items in a collection.

The Bulk Save Data Items endpoint inserts or updates each item provided, depending on whether it already exists in the collection. For each item:

  • If you don't provide an ID, a new item is created.

  • If you provide an ID that doesn't exist in the collection, a new item is created with that ID.

  • If an item with the ID you provide already exists in the collection, that item is updated. When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: When you provide an item with an ID that already exists in the collection, the item you provide completely replaces the existing item with that ID. This means that all of the item's previous fields and values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/save

Was this helpful?
Yes
No

PostBulk Remove Data Items

Removes multiple items from a collection.

If any items in other collections reference the removed items in reference or multi-reference fields, those fields are cleared.

Note: Once an item has been removed from a collection, it can't be restored.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/remove

Was this helpful?
Yes
No

PostQuery Referenced Data Items

Retrieves the full items referenced in the specified field of an item.

Reference and multi-reference fields refer to items in different collections. Use this endpoint to retrieve the full details of the referenced items themselves.

For example, suppose you have a Movies collection with an Actors field that contains references to items in a People collection. Querying the Movies collection using the Query Referenced Data Items endpoint returns the relevant People items referenced in the Actors field of the specified Movie item. This gives you information from the People collection about each of the actors in the specified movie.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query-referenced

Was this helpful?
Yes
No

PostIs Referenced Data Item

Checks whether a field in a referring item contains a reference to a specified item.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/is-referenced

Was this helpful?
Yes
No

PostInsert Data Item Reference

Inserts a reference in the specified field in an item in a collection.

A reference in the dataItemReference field specifies a referring item's ID, the field in which to insert the reference, and the ID of the referenced item.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/insert-reference

Was this helpful?
Yes
No

PostRemove Data Item Reference

Removes the specified reference from the specified field.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/remove-reference

Was this helpful?
Yes
No

PostBulk Insert Data Item References

Inserts one or more references in the specified fields of items in a collection.

This endpoint adds one or more references to a collection. Each new reference in the dataItemReferences field specifies a referring item's ID, the field in which to insert the reference, and the ID of the referenced item.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/insert-references

Was this helpful?
Yes
No

PostBulk Remove Data Item References

Removes one or more references.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/remove-references

Was this helpful?
Yes
No

PostReplace Data Item References

Replaces references in a specified field of a specified data item.

This endpoint replaces the existing reference or references contained in the field specified in referringItemFieldName within the data item specified in referringItemId. The endpoint removes existing references and in their place it adds references to the items specified in newReferencedItemIds.

Note: If you pass an empty array in newReferencedItemIds, all existing references are removed.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/replace-references

Was this helpful?
Yes
No