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.
Did this help?

Data Types in Wix Data

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.

Field types and data types

The following table lists supported field types along with their corresponding data type and format.

Field TypeData TypeFormat
AddressObjectAn Address object. See the Address Object's structure structure.
ArrayArray
AudioStringA web URL or a Media Manager URL.

Learn more about working with media files.
BooleanBooleantrue or false
DateStringA date string in ISO 8601 date format: YYYY-MM-DD.
Date and TimeObjectAn object in the following format: "someFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}

Note: Milliseconds can be omitted: "$date": "YYYY-MM-DDTHH:mm:ss"
DocumentStringA web URL or a Media Manager URL.

Learn more about working with media files.
ImageStringA web URL or a Media Manager URL.

Learn more about working with media files.
Media GalleryArray of image and video URLsArray items are either web URLs or Media Manager URLs.

Learn more about working with media files.
NumberNumber
ObjectObject
Rich ContentObjectA rich content object. Learn more about working with rich content.
Rich TextStringA string that may contain a subset of HTML tags.
Single Reference/ Multi- ReferenceSingle 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.
TagsArray of strings
TextString
TimeStringA string in hh:mm:ss.SSS format.
URLStringA valid URL.
VideoStringA web URL or a Media Manager URL.

Learn more about working with media files.

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 object

Address objects have the following structure:

NameTypeDescription
formattedStringAddress in human-readable format.
locationObjectAddress coordinates
location.latitudeNumberAddress latitude
location.longitudeNumberAddress longitude
streetAddressObjectAddress street name and number
streetAddress.nameStringStreet name
streetAddress.numberNumberStreet number
cityStringAddress city
subdivisionStringAddress subdivision of a country, such as a state or province
countryStringAddress country
postalCodeStringAddress postal code
Did this help?

Data Item Object


Properties
idstring

Data item ID.


dataCollectionIdstringRead-only

ID of the collection this item belongs to


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.
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items

Body Params
dataCollectionIdstringRequired

ID of the collection in which to insert the item.


dataItemDataItemRequired

Item to insert.


appOptionsstruct

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.
Response Object
dataItemDataItem

Inserted data item.

Request
cURL
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 } } }'
Response
JSON
{ "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 } } }
Did this help?

PUT

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
PUT
https://www.wixapis.com/wix-data/v2/items/{dataItem.id}

Path Params
dataItem.idstringRequired

Data item ID.

Body Params
dataCollectionIdstringRequired

ID of the collection containing the existing item.


dataItemDataItemRequired

Updated data item content. The existing data item's content is replaced entirely.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
dataItemDataItem

Updated data item.

Update existing item
Request
cURL
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 } } }'
Response
JSON
{ "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 } } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/save

Body Params
dataCollectionIdstringRequired

ID of the collection in which to insert or update the item.


dataItemDataItemRequired

Data item to insert or update.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
actionstring

The action carried out for the item.


dataItemDataItem

Inserted or updated data item.

Save item
Request
cURL
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 } } }'
Response
JSON
{ "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 } } }
Did this help?

GET

Get Data Item


Retrieves an item from a collection.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/wix-data/v2/items/{dataItemId}

Path Params
dataItemIdstringRequired

ID of the data item to retrieve.

Query Params
dataCollectionIdstringRequired

ID of the collection from which to retrieve the data item.


consistentReadboolean

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


languagestring

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.


fieldsArray <string>

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.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
dataItemDataItem

Retrieved item.

Request
cURL
curl -X GET \ 'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228?dataCollectionId=cities' \ -H 'Authorization: <AUTH>' \
Response
JSON
{ "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 } } }
Did this help?

DELETE

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/wix-data/v2/items/{dataItemId}

Path Params
dataItemIdstringRequired

ID of the item to remove.

Query Params
dataCollectionIdstringRequired

ID of the collection from which to remove the item.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
dataItemDataItem

Removed item.

Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/wix-data/v2/items/5331fc15-9441-4fd4-bc7b-7f6870c69228?dataCollectionId=cities' \ -H 'Authorization: <AUTH>' \
Response
JSON
{ "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 } } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/truncate

Body Params
dataCollectionIdstringRequired

ID of the collection to truncate.

Response Object
Returns an empty object.
Remove all items
Request
cURL
curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/truncate' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "dataCollectionId": "cities" }'
Response
JSON
{}
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query

Body Params
dataCollectionIdstringRequired

ID of the collection to query.


queryQuery

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


returnTotalCountboolean

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


includeReferencedItemsArray <string>deprecated - use referencedItemOptions instead

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.


consistentReadboolean

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


languagestringformat LANGUAGE_TAG

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.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.


referencedItemOptionsArray <ReferencedItemOptions>maxItems 100

Options for retrieving referenced items.

Response Object
dataItemsArray <DataItem>

Retrieved items.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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 } } }'
Response
JSON
{ "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 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/aggregate

Body Params
dataCollectionIdstringRequired

ID of the collection on which to run the aggregation.


initialFilterstruct

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.


aggregationAggregation

Aggregation applied to the data.


finalFilterstruct

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.


sortArray <Sorting>

Sort object in the following format: [{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]


returnTotalCountboolean

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


consistentReadboolean

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


languagestringformat LANGUAGE_TAG

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.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.


ONE OF:

pagingPaging

Paging options to limit and skip the number of items.


cursorPagingCursorPaging

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.

Response Object
resultsArray <object>

Aggregation results.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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" } } ] } }'
Response
JSON
{ "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 } }
Did this help?

POST

Count Data Items


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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/count

Body Params
dataCollectionIdstringRequired

ID of the collection for which to count query results.


filterstruct

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.


consistentReadboolean

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


languagestringformat LANGUAGE_TAG

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.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
totalCountnumber

Number of items matching the query.

Count items
Request
cURL
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" } }'
Response
JSON
{ "totalCount": 4 }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query-distinct-values

Body Params
dataCollectionIdstringRequired

ID of the collection to query.


fieldNamestring

Item field name for which to return all distinct values.


filterstruct

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.


orderstring

Sort order.


returnTotalCountboolean

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


consistentReadboolean

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


languagestringformat LANGUAGE_TAG

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.


publishPluginOptionsPublishPluginOptions

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.


ONE OF:

pagingPaging

Paging options to limit and skip the number of items.


cursorPagingCursorPaging

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.

Response Object
distinctValuesArray <Value>

List of distinct values contained in the field specified in fieldName.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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" }'
Response
JSON
{ "distinctValues": ["San Francisco", "Los Angeles"], "pagingMetadata": { "count": 2, "tooManyToCount": false, "hasNext": false } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/insert

Body Params
dataCollectionIdstringRequired

ID of the collection in which to insert the items.


dataItemsArray <DataItem>Required

Data items to insert.


returnEntityboolean

Whether to return the inserted data items. When true, the results objects contain a dataItem field.

Default: false


appOptionsstruct

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.
Response Object
resultsArray <BulkDataItemResult>

Information about the inserted items.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Request
cURL
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 } } ] }'
Response
JSON
{ "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 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/update

Body Params
dataCollectionIdstringRequired

ID of the collection in which to update items.


dataItemsArray <DataItem>Required

Data items to update.


returnEntityboolean

Whether to return the updated data items. When true, the results objects contain a dataItem field.

Default: false


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
resultsArray <BulkDataItemResult>

Information about the updated items.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Request
cURL
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 } } ] }'
Response
JSON
{ "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 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/save

Body Params
dataCollectionIdstringRequired

ID of the collection in which to insert or update the items.


dataItemsArray <DataItem>Required

Data items to insert or update.


returnEntityboolean

Whether to return the saved data item. When true, the results objects contain a dataItem field.

Default: false


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
resultsArray <BulkDataItemResult>

Information about the saved items.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Request
cURL
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 } } ] }'
Response
JSON
{ "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 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/remove

Body Params
dataCollectionIdstringRequired

ID of the collection from which to remove the item.


dataItemIdsArray <string>Required

IDs of data items to remove.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.

Response Object
resultsArray <BulkDataItemResult>

Information about the removed data items.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Bulk remove existing items
Request
cURL
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" ] }'
Response
JSON
{ "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 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query-referenced

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring item.


referringItemIdstring

ID of the referring item.


referringItemFieldNamestring

Field containing references in the referring item.


orderstring

Order of the returned referenced items. Sorted by the date each item was referenced.


returnTotalCountboolean

Whether to return the total count in the response. When true, the pagingMetadata object in the response contains a total field.

Default: false


consistentReadboolean

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


languagestringformat LANGUAGE_TAG

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.


fieldsArray <string>maxItems 10000maxLength 1000

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.


appOptionsstruct

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.

publishPluginOptionsPublishPluginOptions

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.


ONE OF:

pagingPaging

Paging options to limit and skip the number of items.


cursorPagingCursorPaging

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.

Response Object
resultsArray <ReferencedResult>

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.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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" }'
Response
JSON
{ "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 } }
Did this help?

POST

Is Referenced Data Item


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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/is-referenced

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring data item.


referringItemFieldNamestringRequired

Field to check for a reference to the item that may be referenced.


referringItemIdstringRequired

ID of the referring item.


referencedItemIdstringRequired

ID of the item that may be referenced.


consistentReadboolean

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

Response Object
isReferencedboolean

Whether the specified reference exists.

Is item referenced
Request
cURL
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" }'
Response
JSON
{ "isReferenced": true }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/insert-reference

Body Params
dataCollectionIdstringRequired

ID of the collection in which to insert the reference.


dataItemReferenceDataItemReference

Reference to insert


appOptionsstruct

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.
Response Object
dataItemReferenceDataItemReference

Inserted reference.

Insert item reference
Request
cURL
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" } }'
Response
JSON
{ "dataItemReference": { "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105", "referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646" } }
Did this help?

POST

Remove Data Item Reference


Removes the specified reference from the specified field.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/remove-reference

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring item.


dataItemReferenceDataItemReferenceRequired

Reference to remove.

Response Object
dataItemReferenceDataItemReference

Removed reference.

Remove item reference
Request
cURL
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" } }'
Response
JSON
{ "dataItemReference": { "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105", "referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646" } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/insert-references

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring items.


dataItemReferencesArray <DataItemReference>Required

References to insert.


returnEntityboolean

Whether to return the inserted data item references. When true, the results objects contain a dataItemReference field.

Default: false

Response Object
resultsArray <BulkDataItemReferenceResult>

Information about the inserted references.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Request
cURL
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" } ] }'
Response
JSON
{ "results": [ { "action": "INSERT", "referenceMetadata": { "originalIndex": 0, "success": true } }, { "action": "INSERT", "referenceMetadata": { "originalIndex": 1, "success": true } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 } }
Did this help?

POST

Bulk Remove Data Item References


Removes one or more references.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/bulk/items/remove-references

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring items.


dataItemReferencesArray <DataItemReference>Required

References to remove.

Response Object
resultsArray <BulkDataItemReferenceResult>

Information about the removed references.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Bulk remove references
Request
cURL
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" } ] }'
Response
JSON
{ "results": [ { "action": "DELETE", "referenceMetadata": { "originalIndex": 0, "success": true } }, { "action": "DELETE", "referenceMetadata": { "originalIndex": 1, "success": true } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 } }
Did this help?

POST

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/replace-references

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring item.


referringItemFieldNamestringRequired

Field containing references in the referring item.


referringItemIdstringRequired

ID of the referring item.


newReferencedItemIdsArray <string>

List of new referenced item IDs to replace the existing ones.

Response Object
dataItemReferencesArray <DataItemReference>

Updated references.

Replace existing references with new references
Request
cURL
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"] }'
Response
JSON
{ "dataItemReferences": [ { "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105", "referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646" } ] }
Did this help?

Data Item Created


Triggered when a data item is inserted.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

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

DataItemCreated
JSON
{ "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 }
Did this help?

Data Item Deleted


Triggered when a data item is deleted.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

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

DataItemDeleted
JSON
{ "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 }
Did this help?

Data Item Updated


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.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data.v2.data_item.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

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

DataItemUpdated
JSON
{ "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 }
Did this help?