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:
The Data Items API only works with existing collections. To create and manage data collections, use the Data Collections API.
It's important to note the following points before starting to code:
The Wix Data APIs support a wide range of data types, including numbers, plain and rich text, arrays, URLs, media files, and more. The APIs accept and return data in JSON format, so it’s important to understand the structure and formatting specific to each data type. To ensure data consistency and minimize potential errors, follow these formats when querying, inserting, and updating items in a collection.
Wix Data works with a schemaless database behind the scenes. In theory, you can store any type of data in any database collection field. In practice, however, it's best to conform to each collection’s schema as defined either in the Content Management System (CMS) or when using the Data Collections API. The schema is used to determine which page elements can connect to which fields and to provide a better experience for site admins when using the CMS. For example, if a field's type is set to Date and Time, its values will appear as dates in the CMS. Site admins can then connect that field to site elements that work with dates.
The following table lists supported field types along with their corresponding data type and format.
Field Type | Data Type | Format |
---|---|---|
Address | Object | An Address object. See the Address Object's structure structure. |
Array | Array | |
Audio | String | A web URL or a Media Manager URL. Learn more about working with media files. |
Boolean | Boolean | true or false |
Date | String | A date string in ISO 8601 date format: YYYY-MM-DD . |
Date and Time | Object | An object in the following format: "someFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"} Note: Milliseconds can be omitted: "$date": "YYYY-MM-DDTHH:mm:ss" |
Document | String | A web URL or a Media Manager URL. Learn more about working with media files. |
Image | String | A web URL or a Media Manager URL. Learn more about working with media files. |
Media Gallery | Array of image and video URLs | Array items are either web URLs or Media Manager URLs. Learn more about working with media files. |
Number | Number | |
Object | Object | |
Rich Content | Object | A rich content object. Learn more about working with rich content. |
Rich Text | String | A string that may contain a subset of HTML tags. |
Single Reference/ Multi- Reference | Single Reference: String/ object Multi-reference: Array of strings/ array of objects | An item ID or multiple item IDs from the referenced collection. See Query Referenced Data Items to learn about item references. |
Tags | Array of strings | |
Text | String | |
Time | String | A string in hh:mm:ss.SSS format. |
URL | String | A valid URL. |
Video | String | A web URL or a Media Manager URL. Learn more about working with media files. |
With the Wix Data APIs, you can manage media items of any supported type. Items can be stored on an external service, or directly on Wix using the Wix Media Manager. Learn more about which data types are supported in the Media Manager.
To learn about uploading files to the Media Manager, see the Upload API and the Resumable Upload API. To learn how media items are stored in the Media Manager, see the List Files and Get File Descriptors endpoints.
Address objects have the following structure:
Name | Type | Description |
---|---|---|
formatted | String | Address in human-readable format. |
location | Object | Address coordinates |
location.latitude | Number | Address latitude |
location.longitude | Number | Address longitude |
streetAddress | Object | Address street name and number |
streetAddress.name | String | Street name |
streetAddress.number | Number | Street number |
city | String | Address city |
subdivision | String | Address subdivision of a country, such as a state or province |
country | String | Address country |
postalCode | String | Address postal code |
Data item ID.
ID of the collection this item belongs to
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.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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to insert the item.
Item to insert.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Inserted data item.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItem": {
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
}
}'
{
"dataItem": {
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Data item ID.
ID of the collection containing the existing item.
Updated data item content. The existing data item's content is replaced entirely.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Updated data item.
curl -X PUT \
'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItem": {
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
}
}'
{
"dataItem": {
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to insert or update the item.
Data item to insert or update.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
The action carried out for the item.
Inserted or updated data item.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/save' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItem": {
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
}
}'
{
"dataItem": {
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
}
}
Retrieves an item from a collection.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the data item to retrieve.
ID of the collection from which to retrieve the data item.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Fields to return for the item. Only fields specified in the array are included in the response. If the array is empty, all fields are returned.
Note: The _id
system field is always returned.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Retrieved item.
curl -X GET \
'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228?dataCollectionId=cities' \
-H 'Authorization: <AUTH>' \
{
"dataItem": {
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T13:24:45.845Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the item to remove.
ID of the collection from which to remove the item.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Removed item.
curl -X DELETE \
'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228?dataCollectionId=cities' \
-H 'Authorization: <AUTH>' \
{
"dataItem": {
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection to truncate.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/truncate' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities"
}'
{}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection to query.
Query preferences. For more details on using queries, see API Query Language.
Whether to return the total count in the response for a query with offset paging.
When true
, the pagingMetadata
object in the response contains a total
field.
Default: false
Properties for which to include referenced items in the query's results. Up to 50 referenced items can be included for each item that matches the query.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Options for retrieving referenced items.
Retrieved items.
Paging information.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/query' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"query": {
"filter": {
"state": "California"
},
"paging": {
"limit": 2
}
}
}'
{
"dataItems": [
{
"id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"dataCollectionId": "cities",
"data": {
"_id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "Los Angeles",
"population": 3800000.0
}
},
{
"id": "9b05dd0f-b3b6-481f-a9af-97379f4c81bb",
"dataCollectionId": "cities",
"data": {
"_id": "9b05dd0f-b3b6-481f-a9af-97379f4c81bb",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"state": "California",
"year": 2022.0,
"city": "San Francisco",
"population": 840000.0
}
}
],
"pagingMetadata": {
"count": 2,
"tooManyToCount": false,
"hasNext": true
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection on which to run the aggregation.
Filter applied to the collection's data prior to running the aggregation. See API Query Language for information on how to structure a filter object.
Note: The values you provide for each filter field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: "someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}
. Learn more about data types in Wix Data.
Aggregation applied to the data.
Filter applied to the processed data following the aggregation. See API Query Language for information on how to structure a filter object.
Note: The values you provide for each filter field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: "someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}
. Learn more about data types in Wix Data.
Sort object in the following format:
[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]
Whether to return the total count in the response for a query with offset paging.
When true
, the pagingMetadata
object in the response contains a total
field.
Default: false
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Paging options to limit and skip the number of items.
Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not filter
or sort
.
Aggregation results.
Paging information.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/aggregate' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"initialFilter": {
"year": 2022
},
"aggregation": {
"groupingFields": ["state"],
"operations": [
{
"resultFieldName": "totalPopulation",
"sum": {
"itemFieldName": "population"
}
}
]
}
}'
{
"results": [
{
"_id": {
"state": "New York"
},
"totalPopulation": 20000000.0,
"state": "New York"
},
{
"_id": {
"state": "California"
},
"totalPopulation": 39000000.0,
"state": "California"
}
],
"pagingMetadata": {
"count": 2,
"tooManyToCount": false,
"hasNext": false
}
}
Counts the number of items in a data collection that match the provided filtering preferences.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection for which to count query results.
Filter object in the following format:
"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }
.
Examples of operators: $eq
, $ne
, $lt
, $lte
, $gt
, $gte
, $in
, $hasSome
, $hasAll
, $startsWith
, $contains
.
Note: The values you provide for each field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: "someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}
. Learn more about data types in Wix Data.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Number of items matching the query.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/count' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"filter": {
"state": "California"
}
}'
{
"totalCount": 4
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection to query.
Item field name for which to return all distinct values.
Filter object in the following format:
"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }
.
Examples of operators: $eq
, $ne
, $lt
, $lte
, $gt
, $gte
, $in
, $hasSome
, $hasAll
, $startsWith
, $contains
.
Note: The values you provide for each field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: "someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}
. Learn more about data types in Wix Data.
Sort order.
Whether to return the total count in the response for a query with offset paging.
When true
, the pagingMetadata
object in the response contains a total
field.
Default: false
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Paging options to limit and skip the number of items.
Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not filter
or sort
.
List of distinct values contained in the field specified in fieldName
.
Paging information.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/query-distinct-values' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"fieldName": "city"
}'
{
"distinctValues": ["San Francisco", "Los Angeles"],
"pagingMetadata": {
"count": 2,
"tooManyToCount": false,
"hasNext": false
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to insert the items.
Data items to insert.
Whether to return the inserted data items.
When true
, the results
objects contain a dataItem
field.
Default: false
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Information about the inserted items.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItems": [
{
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
},
{
"data": {
"state": "California",
"year": 2022,
"city": "San Francisco",
"population": 840000
}
}
]
}'
{
"results": [
{
"action": "INSERT",
"itemMetadata": {
"id": "aa019290-b546-4b3e-b302-8f6474baedf9",
"originalIndex": 0,
"success": true
}
},
{
"action": "INSERT",
"itemMetadata": {
"id": "39cbd938-7b42-4e33-8acf-ff1ce278664c",
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to update items.
Data items to update.
Whether to return the updated data items.
When true
, the results
objects contain a dataItem
field.
Default: false
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Information about the updated items.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/update' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItems": [
{
"id": "40877d18-c5fe-4ed5-b495-d84bb4c027bd",
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
},
{
"id": "6c38b4f7-7b8d-4702-9283-66a5889f8e17",
"data": {
"state": "California",
"year": 2022,
"city": "San Francisco",
"population": 840000
}
}
]
}'
{
"results": [
{
"action": "UPDATE",
"itemMetadata": {
"id": "40877d18-c5fe-4ed5-b495-d84bb4c027bd",
"originalIndex": 0,
"success": true
}
},
{
"action": "UPDATE",
"itemMetadata": {
"id": "6c38b4f7-7b8d-4702-9283-66a5889f8e17",
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to insert or update the items.
Data items to insert or update.
Whether to return the saved data item.
When true
, the results
objects contain a dataItem
field.
Default: false
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Information about the saved items.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/save' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItems": [
{
"data": {
"state": "California",
"year": 2022,
"city": "Los Angeles",
"population": 3800000
}
},
{
"data": {
"state": "California",
"year": 2022,
"city": "San Francisco",
"population": 840000
}
}
]
}'
{
"results": [
{
"action": "INSERT",
"itemMetadata": {
"id": "aa019290-b546-4b3e-b302-8f6474baedf9",
"originalIndex": 0,
"success": true
}
},
{
"action": "INSERT",
"itemMetadata": {
"id": "39cbd938-7b42-4e33-8acf-ff1ce278664c",
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection from which to remove the item.
IDs of data items to remove.
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Information about the removed data items.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/remove' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "cities",
"dataItemIds": [
"6d717171-6f4d-4794-b6ea-7aea0071a76b",
"6c38b4f7-7b8d-4702-9283-66a5889f8e17"
]
}'
{
"results": [
{
"action": "DELETE",
"itemMetadata": {
"id": "6d717171-6f4d-4794-b6ea-7aea0071a76b",
"originalIndex": 0,
"success": true
}
},
{
"action": "DELETE",
"itemMetadata": {
"id": "6c38b4f7-7b8d-4702-9283-66a5889f8e17",
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring item.
ID of the referring item.
Field containing references in the referring item.
Order of the returned referenced items. Sorted by the date each item was referenced.
Whether to return the total count in the response.
When true
, the pagingMetadata
object in the response contains a total
field.
Default: false
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.
If not provided, result text is not translated.
Fields to return for each referenced item. Only fields specified in the array are included in the response. If the array is empty, all fields are returned.
Note: The _id
system field is always returned.
Additional parameters specific to the Wix app collection you are querying:
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.
Paging options to limit and skip the number of items.
Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not filter
or sort
.
Referenced items and/or IDs. For successfully resolved references, the referenced data item is returned. For references that can't be resolved, the ID is returned.
Paging information.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/query-referenced' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105"
}'
{
"results": [
{
"dataItem": {
"id": "99cb26d5-dd42-4384-af30-3bb6e4026bd0",
"dataCollectionId": "songs",
"data": {
"_id": "99cb26d5-dd42-4384-af30-3bb6e4026bd0",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"title": "I Should Have Known Better"
}
}
},
{
"dataItem": {
"id": "b10170b2-2e0d-4093-b472-cf8f2982a247",
"dataCollectionId": "songs",
"data": {
"_id": "b10170b2-2e0d-4093-b472-cf8f2982a247",
"_createdDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" },
"_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360",
"title": "If I Fell"
}
}
}
],
"pagingMetadata": {
"count": 2
}
}
Checks whether a field in a referring item contains a reference to a specified item.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring data item.
Field to check for a reference to the item that may be referenced.
ID of the referring item.
ID of the item that may be referenced.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
Whether the specified reference exists.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/is-referenced' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "99cb26d5-dd42-4384-af30-3bb6e4026bd0"
}'
{
"isReferenced": true
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection in which to insert the reference.
Reference to insert
Additional parameters specific to the Wix app collection you are querying.
When querying the Wix Stores Products collection, pass the following optional parameters:
includeHiddenProducts
: Whether to include hidden products in the response. Default: false
.includeVariants
: Whether to include product variants in the query. Default: false
.Inserted reference.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/insert-reference' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"dataItemReference": {
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
}
}'
{
"dataItemReference": {
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
}
}
Removes the specified reference from the specified field.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring item.
Reference to remove.
Removed reference.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/remove-reference' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"dataItemReference": {
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
}
}'
{
"dataItemReference": {
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring items.
References to insert.
Whether to return the inserted data item references.
When true
, the results
objects contain a dataItemReference
field.
Default: false
Information about the inserted references.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert-references' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"dataItemReferences": [
{
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
},
{
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "e7fe3827-5102-470a-a10a-b6221dd0b4a9"
}
]
}'
{
"results": [
{
"action": "INSERT",
"referenceMetadata": {
"originalIndex": 0,
"success": true
}
},
{
"action": "INSERT",
"referenceMetadata": {
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
Removes one or more references.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring items.
References to remove.
Information about the removed references.
Bulk action metadata.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/remove-references' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"dataItemReferences": [
{
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
},
{
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "e7fe3827-5102-470a-a10a-b6221dd0b4a9"
}
]
}'
{
"results": [
{
"action": "DELETE",
"referenceMetadata": {
"originalIndex": 0,
"success": true
}
},
{
"action": "DELETE",
"referenceMetadata": {
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring item.
Field containing references in the referring item.
ID of the referring item.
List of new referenced item IDs to replace the existing ones.
Updated references.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/replace-references' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataCollectionId": "albums",
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"newReferencedItemIds": ["aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"]
}'
{
"dataItemReferences": [
{
"referringItemFieldName": "songs",
"referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
"referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
}
]
}
Triggered when a data item is inserted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data.v2.data_item_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "7d4d5a64-6faa-4ff0-bbce-1b7fd64777f4",
"entityFqdn": "wix.data.v2.data_item",
"slug": "created",
"entityId": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"createdEvent": {
"entity": {
"id": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"dataCollectionId": "cities",
"data": {
"_id": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"_owner": "ea435a36-6ab0-401f-82c2-22395fa6b573",
"_createdDate": {
"$date": "2024-05-20T12:13:49.189Z"
},
"_updatedDate": {
"$date": "2024-05-20T12:13:49.189Z"
},
"city": "Los Angeles",
"state": "California",
"year": 2022.0,
"population": 3800000.0
}
}
},
"eventTime": "2024-05-20T12:13:51.868311441Z",
"triggeredByAnonymizeRequest": false
}
Triggered when a data item is deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data.v2.data_item_deleted",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "61635914-103b-4b23-9782-afd9794c8b6c",
"entityFqdn": "wix.data.v2.data_item",
"slug": "deleted",
"entityId": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"deletedEvent": {
"deletedEntity": {
"id": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"dataCollectionId": "cities"
}
},
"eventTime": "2024-05-20T12:14:15.146099243Z",
"triggeredByAnonymizeRequest": false
}
Triggered when a data item is updated.
Note: When scheduling an item's visibility change, the event is triggered when the scheduled change is set up, not when it goes into effect.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data.v2.data_item_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "0b8c8bfc-1357-423a-aad8-3595feb83d5d",
"entityFqdn": "wix.data.v2.data_item",
"slug": "updated",
"entityId": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"updatedEvent": {
"currentEntity": {
"id": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"dataCollectionId": "cities",
"data": {
"_id": "de17fb92-4448-4d90-bc0b-8b99dcadfa86",
"_owner": "ea435a36-6ab0-401f-82c2-22395fa6b573",
"_createdDate": {
"$date": "2024-05-20T12:13:49.189Z"
},
"_updatedDate": {
"$date": "2024-05-20T12:14:06.529Z"
},
"city": "Los Angeles",
"state": "California",
"year": 2023.0,
"population": 3900000.0
}
}
},
"eventTime": "2024-05-20T12:14:08.615901811Z",
"triggeredByAnonymizeRequest": false
}