About Item Variants

The Item Variants API allows you to manage the pricing options applied to menu items. Item variants are determined by specific parameters like size, base ingredient, quantity and other customizable attributes. For example, you can have a raspberry lemonade with sizes "small", "medium", and "large", where pricing for each size is different.

The same item variant can be used across various menu items for better flexibility and consistency.

With the Item Variants API, you can:

  • Create, delete, and update item variants.
  • Retrieve the information about item variants.

Before you begin

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

  • The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Use cases

Did this help?

Item Variants: Sample Use Cases & Flows

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

Sync pizza menu across all sites

If you have several pizzeria sites that use your app you might need to sync menu across those sites. For example, if there are new variants for a drink called "Small", "Medium", and "Large", this change also needs to be reflected on other sites.

To sync the pizza menu across all sites:

  1. Call Query Variants by the name field on the site where you updated the menu.
  2. Extract all 3 variant.name field values.
  3. Call Bulk Create Variants for your other sites and pass the new variants to each.
  4. Call Update Item and add the new variant IDs to the item.priceVariants.variants array.
Did this help?

Item Variants: Supported Filters and Sorting

The following table shows field support for filters and sorting for the item variants object:

FieldSupported FiltersSortable
id$eq, $ne, $in, $ninSortable
createdDate$eq, $ne, $gt, $lt, $gte, $lteSortable
updatedDate$eq, $ne, $gt, $lt, $gte, $lteSortable
name$eq, $ne, $in, $ninSortable

Related content: API Query Language, Query Variants.

Did this help?

Item Variant Object


Properties
idstringRead-onlyformat GUID

Item variant ID.


revisionintegerRead-onlyformat int64

Revision number, which increments by 1 each time the item variant is updated. To prevent conflicting changes, the current revision must be passed when updating the item variant. Ignored when creating an item variant.


createdDatestringRead-onlyformat date-time

Date and time the item variant was created.


updatedDatestringRead-onlyformat date-time

Date and time the item variant was updated.


namestringminLength 1maxLength 40

Item variant name.


extendedFieldsExtendedFields

Extended fields.

Did this help?

GET

List Variants


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Retrieves a list of up to 100 item variants.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/restaurants/item-variants/v1/variants

Query Params
variantIdsArray <string>

Item variant IDs.


paging.limitintegerminimum 0maximum 200format int32

Number of items to load.


paging.cursorstringmaxLength 16000

Pointer to the next or previous page in the list of results.

You can get the relevant cursor token from the pagingMetadata object in the previous call's response. Not relevant for the first request.

Response Object
variantsArray <Variant>

The retrieved item variants.


metadataMetadata

The metadata of the paginated results.

List all variants
Request
cURL
curl -X GET https://www.wixapis.com/restaurants/item-variants/v1/variants \ -H 'Authorization: <AUTH>'
Response
JSON
{ "variants": [ { "id": "02042f01-58ab-441c-b5db-55f51c855a62", "revision": "1", "createdDate": "2023-12-03T21:23:33.861Z", "updatedDate": "2023-12-03T21:23:33.861Z", "name": "Small" }, { "id": "0517e5d4-8fd3-4b28-a743-68cf631e534a", "revision": "1", "createdDate": "2023-12-03T21:23:33.861Z", "updatedDate": "2023-12-03T21:23:33.861Z", "name": "Medium" }, { "id": "1c1ca051-b460-4064-b7a2-5f9df47f2d3c", "revision": "1", "createdDate": "2023-12-03T21:23:33.861Z", "updatedDate": "2023-12-03T21:23:33.861Z", "name": "Large" } ], "pagingMetadata": { "count": 3, "cursors": {}, "hasNext": false } }
Did this help?

POST

Create Variant


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Creates an item variant.

To create multiple item variants at once, use Bulk Create Variants.

Authentication

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

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/restaurants/item-variants/v1/variants

Body Params
variantVariantRequired

Item variant info.

Response Object
variantVariant

Item variant.

Create a variant
Request
cURL
curl -X POST https://www.wixapis.com/restaurants/item-variants/v1/restaurants-menus-item-variant \ -H 'Authorization: <AUTH>' \ --data-binary '{ "variant": { "name": "Small" }'
Response
JSON
{ "variant": { "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47", "revision": 1, "createdDate": "2019-10-30T17:22:10.299Z", "updatedDate": "2019-10-30T17:22:10.299Z", "name": "Small" } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Variant


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Retrieves an item variant by ID.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/restaurants/item-variants/v1/variants/{variantId}

Path Params
variantIdstringRequired

ID of the item variant to retrieve.

Response Object
variantVariant

Item variant.

Retrieve a variant
Request
cURL
curl -X GET https://www.wixapis.com/restaurants/item-variants/v1/variants/02042f01-58ab-441c-b5db-55f51c855a62 -H 'Authorization: <AUTH>'
Response
JSON
{ "variant": { "id": "02042f01-58ab-441c-b5db-55f51c855a62", "revision": "1", "createdDate": "2023-12-03T21:23:33.861Z", "updatedDate": "2023-12-03T21:23:33.861Z", "name": "Small" } }
Did this help?

DELETE

Delete Variant


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Permanently deletes an item variant.

Authentication

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

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/restaurants/item-variants/v1/variants/{variantId}

Path Params
variantIdstringRequired

Item variant ID.

Response Object
Returns an empty object.
Delete a variant
Request
cURL
curl -X DELETE https://www.wixapis.com/restaurants/item-variants/v1/variants/cbbf4358-292c-4e9e-a820-7e75b4551120 \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Variant


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Updates an item variant.

To update multiple item variants at once, use Bulk Update Variants.

Each time an item variant is updated, its revision increments by 1. The existing revision must be included when updating the variant. This ensures you're working with the latest variant information, and it prevents unintended overwrites.

Authentication

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

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/restaurants/item-variants/v1/variants/{variant.id}

Path Params
variant.idstringRequired

Item variant ID.

Body Params
variantVariantRequired

Item variant to update.

Response Object
variantVariant

Updated item variant.

Update a variant
Request
cURL
curl -X PATCH https://www.wixapis.com/restaurants/item-variants/v1/variants/02042f01-58ab-441c-b5db-55f51c855a11?variantId=02042f01-58ab-441c-b5db-55f51c855a11 \ -H 'Authorization: <AUTH>' \ --data-binary '{ "variant": { "id": "02042f01-58ab-441c-b5db-55f51c855a11", "revision": "1", "name": "Medium" }, "mask": { "paths": [ "name" ] } }'
Response
JSON
{ "variant": { "id": "02042f01-58ab-441c-b5db-55f51c855a11", "revision": "2", "createdDate": "2023-12-04T08:12:01.896Z", "updatedDate": "2023-12-04T08:38:47.940Z", "name": "Medium" } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Bulk Create Variants


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Creates multiple item variants.

Authentication

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

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/restaurants/item-variants/v1/bulk/variants/create

Body Params
variantsArray <Variant>RequiredmaxItems 100

Item variants details.


returnEntityboolean

Whether to receive the created item variants in the response.

Response Object
resultsArray <BulkVariantResult>

Information about the created item variants.


bulkActionMetadataBulkActionMetadata

Metadata for the API call.

Create multiple variants
Request
cURL
curl -X POST https://www.wixapis.com/restaurants/item-variants/v1/bulk/variants/create \ -H 'Authorization: <AUTH>' --data-binary '{ "variants": [ { "name": "Small" }, { "name": "Medium" }, { "name": "Large" } ], "returnEntity": false }'
Response
JSON
{ "results": [ { "itemMetadata": { "id": "02042f01-58ab-441c-33db-55221c855c11", "originalIndex": 0, "success": true } }, { "itemMetadata": { "id": "02022fe1-58ab-ee1c-33db-45521c855e11", "originalIndex": 1, "success": true } } ], "bulkActionMetadata": { "totalSuccesses": 3, "totalFailures": 0, "undetailedFailures": 0 } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Bulk Update Variants


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Updates multiple item variants.

Each time an item variant is updated, its revision increments by 1. The existing revision must be included when updating variant. This ensures you're working with the latest item information, and it prevents unintended overwrites.

Up to 100 item variants can be returned per request.

Authentication

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

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/restaurants/item-variants/v1/bulk/variants/update

Body Params
variantsArray <MaskedVariant>RequiredminItems 1maxItems 100

Item variants to be updated.


returnEntityboolean

Whether to receive the updated item variants in the response.

Response Object
resultsArray <BulkVariantResult>minItems 1maxItems 100

Information about the updated item variants.


bulkActionMetadataBulkActionMetadata

Metadata for the API call.

Event TriggersThis method triggers the following events:
Did this help?

POST

Query Variants


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item Variants API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Retrieves a list of item variants given the provided paging, filtering, and sorting. Up to 100 item variants can be returned per request.

For a detailed list of supported operations, see the Supported Filters and Sorting article. To learn how to query item variants, see API Query Language

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/restaurants/item-variants/v1/variants/query

Body Params
queryQuery

Query options.

Response Object
variantsArray <Variant>

Retrieved item variants.


pagingMetadataPagingMetadata

Metadata of the paginated results.

Query all variants by the name
Request
cURL
curl -X POST https://www.wixapis.com/restaurants/item-variants/v1/variants/query \ -H 'Authorization: <AUTH>' --data-binary '{ "query": { "sort": [], "filter": { "name": "Small" } } }'
Response
JSON
{ "variants": [ { "id": "02042f01-58ab-441c-b5db-55f51c855a10", "revision": "1", "createdDate": "2023-12-04T08:12:10.571Z", "updatedDate": "2023-12-04T08:12:10.571Z", "name": "Small" } ], "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false } }
Did this help?

POST

Count Variants


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Item API only works with the Wix Restaurants Menus (New) app. Make sure you have installed this app from the Wix App Market.

Retrieves the number of item variants that match a specified filter.

If a filter isn't passed in the request, the endpoint returns the count of all item variants.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/restaurants/item-variants/v1/variants/count

Body Params
filterstruct

Filter for counting variants.

Response Object
countinteger

Counted variants.

Errors
428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

Item Variant Created


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
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.restaurants.menus.v1.item_variant.


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.restaurants.menus.v1.item_variant_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 } } }

ItemVariantCreated
JSON
{ "id": "52269077-05f2-4b59-ba4f-36ef8c4c1e11", "entityFqdn": "wix.restaurants.menus.v1.item_variant", "slug": "created", "entityId": "8046df3c-7575-4098-a5ab-c91ad8f33c47", "createdEvent": { "entity": { "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47", "revision": 1, "createdDate": "2019-10-30T17:22:10.299Z", "updatedDate": "2019-10-30T17:22:10.299Z", "name": "Small" } }, "eventTime": "2020-10-18T13:40:58.304800Z", "triggeredByAnonymizeRequest": false }
Did this help?

Item Variant Deleted


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
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.restaurants.menus.v1.item_variant.


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.restaurants.menus.v1.item_variant_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 } } }
Did this help?

Item Variant Updated


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
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.restaurants.menus.v1.item_variant.


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.restaurants.menus.v1.item_variant_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 } } }

ItemVariantUpdated
JSON
{ "id": "52269077-05f2-4b59-ba4f-36ef8c4c1e11", "entityFqdn": "wix.restaurants.menus.v1.item_variant", "slug": "updated", "entityId": "8046df3c-7575-4098-a5ab-c91ad8f33c47", "updatedEvent": { "currentEntity": { "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47", "revision": "2", "createdDate": "2024-01-14T12:41:35.833Z", "updatedDate": "2024-01-14T12:42:53.067Z", "name": "Medium" } }, "eventTime": "2020-10-18T13:40:58.304800Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "2" }
Did this help?