About the Wix Bookings Service Options and Variants API

With the Wix Bookings Service Options and Variants API, you can manage custom options and variants for services. This allows site owners to offer different prices for the same service based on their customers' choices.

You can read more about using the:

Checking for Existing Pricing Options

You can check whether a service has existing pricing options, and what they are, by retrieving the rate object of the service's active schedule. Check this flow for more details.

There are 3 different possible rates:

  • labeledPriceOptions: For services with the standard Wix Bookings pricing.
  • priceText: For services with prices manually set by the business.
  • defaultPrice: For services with varied pricing.

If any of these 3 rates are defined in the service's active schedule, pricing options have already been defined.

Terminology

For a comprehensive glossary of Wix Bookings terms, see Terminology.

Before you begin

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

  • Only a single serviceOptionsAndVariants object is supported per service.

  • Currently, only a single option is supported per serviceOptionsAndVariants object.

  • You need to manually calculate and then pass all variants in the request of Create Service Options And Variants. Variants aren't automatically calculated from the specified options.

  • New variants are automatically created for services with staff member-based options whenever a new staff member is added to the service. The new variant gets the default price specified in the service's schedule.rate.default_varied_price.

  • Variants are automatically deleted for services with staff member based options whenever a staff member is removed from the service or the business.

Was this helpful?
Yes
No

Sample Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Create staff member-based service variants

Your app can set up staff member-based service variants. This allows the site owner to offer customers different service prices depending on which staff member is providing the service.

  1. Identify the relevant service ID. For example, call List services and choose the service you want to create options and variants for.

  2. Pass the serviceId inside the scheduleOwnerIds array in the List schedules call. This retrieves all schedules related to the service.

  3. Identify the active schedule from retrieved schedules. The active schedule has a status of CREATED in contrast to all other retrieved schedules.

  4. Save the scheduleOwnerId from the active schedule's availability.linkedSchedules array. These are the IDs of the staff members providing this service.

  5. Call Create Service Options and Variants and pass the relevant serviceId, STAFF_MEMBER (in the options.type field), as well as the IDs of all staff members providing the service in the variants.choices array. You can specify the price for each staff member in variants.price.

Create service variants based on the booked equipment

Your app can set up service variants based on the booked equipment. This allows them to offer customers different service prices depending on what equipment the customer has booked.

  1. Identify the relevant service ID. For example, call List services and choose the service you want to create options and variants for.

  2. Call Create Service Options and Variants and pass the relevant serviceId, CUSTOM (in the options.type field), Equipment (in the options.customData.name field), as well as all supported equipment in the options.customData.choices array. Make sure to also pass all supported variants. You can specify the price for each variant in variants.price.

Was this helpful?
Yes
No

Service Variants and Options: Supported Filters and Sorting

Query endpoints allow you to filter and sort results based on service variant and options properties. This article covers field support for filtering and sorting.

Filtering

Specify the Query Service Options and Variants filter object in the following format:

Copy
1
"filter" :
2
{
3
"fieldName": "value",
4
}

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

FieldSupported FiltersSortable
id$eq, $ne, $inSortable
serviceId$eq, $ne, $in
options.values$exists
options.values.id$hasSome, $hasAll
options.values.type$hasSome, $hasAll
options.values.optionSpecificData.customData.name$hasSome, $hasAll
variants.values$exists
variants.values.choices.choice.custom.value$hasSome, $hasAll
variants.values.price$hasSome, $hasAll
variants.values.choices.optionId$hasSome, $hasAll

Sorting

Query Service Options and Variants runs with this default:

  • sorted by id in ASC order

Specify the sort object in the following format:

Copy
1
"sort" : [
2
{
3
"fieldName":"sortField1",
4
"order":"ASC"
5
},
6
{
7
"fieldName":"sortField2",
8
"order":"ASC"
9
},
10
]

Paging

By default pagingMetadata.cursors are returned, unless you specifically pass query.paging.

The maximum for cursorPaging.limit is 100.

If you pass a cursor token that you have received in a previous query response, passing additional sort or filter information results in an invalid cursor error. This is because the received cursor token already holds all the needed information for sort and filter. Changing the sort and filter properties during the span of a cursor query isn't supported. You may provide a different limit though.

Related content:

Was this helpful?
Yes
No

Wix Bookings Service Options and Variants Errors

This articles outlines error messages that might be issued when calling endpoints of the Wix Bookings Service Options and Variants API.

Create Service Options and Variants Errors

The Create Service Options and Variants endpoint might issue the following error messages:

HTTP status
Error code
Error message
Troubleshooting
INVALID_ARGUMENT (400)UNKNOWN_OPTION_IDSUnknown option IDs <ids> aren't supported in the variants array.Make sure that all option IDs in the variants array align with the corresponding option IDs.
INVALID_ARGUMENT (400)MULTIPLE_CURRENCIESMultiple currencies <currencies> aren't supported in the variants array.Make sure that all variants use the same currency.
INVALID_ARGUMENT (400)UNSUPPORTED_OPTION_TYPEOption type <optionType> isn't supported for service <serviceId>.You can only define staff member based variants in case the service has connected staff members. If the service has no staff members you can call Update Schedule to add them. To do so, add the relevant staff member IDs as scheduleOwnerId to the active schedule's availability.linkedSchedules array.
INVALID_ARGUMENT (400)UNKNOWN_STAFF_IDSStaff members <staffIds> aren't connected to service <serviceId>.Some staff members specified in the variants array aren't connected to the service. Either call Update Schedule to add them. To do so, add the relevant staff member IDs as scheduleOwnerId to the active schedule's availability.linkedSchedules array. Or remove the staff members from the variants array.
INVALID_ARGUMENT (400)MISSING_STAFF_VARIANTSStaff members <staffIds> are missing in the variants array.Not all staff members providing the service are specified in the variants array. Either call Update Schedule to remove staff members from the service. To do so, remove the relevant scheduleOwnerIds from the active schedule's availability.linkedSchedules array. Or remove the relevant staff members from the variants array.
INVALID_ARGUMENT (400)IDENTICAL_CHOICESIdentical choices <choices> aren't supported.Make sure to remove identical choices from the request. Choices aren't case sensitive. For example, "Student" and "student" are considered to be the same choice.
INVALID_ARGUMENT (400)MISSING_CUSTOM_CHOICESChoices <choices> are missing in the variants array.Make sure to provide all custom choices in the variants array. You could either add missing variants or remove unnecessary choices.
INVALID_ARGUMENT (400)NEGATIVE_PRICESPrices must have positive values.Make sure that all prices have positive values.
INVALID_ARGUMENT (400)UNSUPPORTED_OPTION_DATAOption data isn't supported for option type <optionType> that's used for service <serviceId>.Make sure to pass customData for custom options or no data for staff member based options.

Update Service Options and Variants Errors

The Update Service Options and Variants endpoint might issue the following error messages:

HTTP status
Error code
Error message
Troubleshooting
INVALID_ARGUMENT (400)UNKNOWN_OPTION_IDSUnknown option IDs <ids> aren't supported in the variants array.Make sure that all option IDs in the variants array align with the corresponding option IDs.
INVALID_ARGUMENT (400)MULTIPLE_CURRENCIESMultiple currencies <currencies> aren't supported in the variants array.Make sure that all variants use the same currency.
INVALID_ARGUMENT (400)UNSUPPORTED_OPTION_TYPEOption type <optionType> isn't supported for service <serviceId>.You can only define staff member based variants in case the service has connected staff members. If the service has no staff members you can call Update Schedule to add them. To do so, add the relevant staff member IDs as scheduleOwnerId to the active schedule's availability.linkedSchedules array.
INVALID_ARGUMENT (400)UNKNOWN_STAFF_IDSStaff members <staffIds> aren't connected to service <serviceId>.Some staff members specified in the variants array aren't connected to the service. Either call Update Schedule to add them. To do so, add the relevant staff member IDs as scheduleOwnerId to the active schedule's availability.linkedSchedules array. Or remove the staff members from the variants array.
INVALID_ARGUMENT (400)MISSING_STAFF_VARIANTSStaff members <staffIds> are missing in the variants array.Not all staff members providing the service are specified in the variants array. Either call Update Schedule to remove staff members from the service. To do so, remove the relevant scheduleOwnerIds from the active schedule's availability.linkedSchedules array. Or remove the relevant staff members from the variants array.
INVALID_ARGUMENT (400)IDENTICAL_CHOICESIdentical choices <choices> aren't supported.Make sure to remove identical choices from the request. Choices aren't case sensitive. For example, "Student" and "student" are considered to be the same choice.
INVALID_ARGUMENT (400)MISSING_CUSTOM_CHOICESChoices <choices> are missing in the variants array.Make sure to provide all custom choices in the variants array. You could either add missing variants or remove unnecessary choices.
INVALID_ARGUMENT (400)NEGATIVE_PRICESPrices must have positive values.Make sure that all prices have positive values.
INVALID_ARGUMENT (400)UNSUPPORTED_OPTION_SPECIFIC_DATAOption data isn't supported for option type <optionType>.Make sure to pass customData for custom options or no data for staff member based options.
Was this helpful?
Yes
No

Service Options And Variants Object

Attributes
idstringRead-onlyformat GUID
ID of the serviceOptionsAndVariants object.

serviceIdstringformat GUID
ID of the service related to these options and variants.

optionsobject
Service options. Note that currently only a single option is supported per service.

variantsobject
Information about the service's variants.

minPriceobject
Price of the cheapest service variant.

maxPriceobject
Price of the most expensive service variant.

revisionobject
Revision number, which increments by 1 each time the serviceOptionsAndVariants object is updated. To prevent conflicting changes, the current revision must be passed when updating and deleting the serviceOptionsAndVariants object. Ignored when creating a serviceOptionsAndVariants object.
Was this helpful?
Yes
No

PostCreate Service Options And 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.

Creates options and variants for a service.

Before creating the serviceOptionsAndVariants object you need to anticipate and manually define all variants based on the defined options and their choices. You then pass the options and variants arrays in the request. Variants aren't automatically calculated from the defined options and choices.

Current Limitations:

  • Only a single serviceOptionsAndVariants object is supported per service.

  • Only a single option is supported per serviceOptionsAndVariants object. This means that services are limited to a single option. Therefore, variantsprovides pricing details for either all choices of the single option (for CUSTOM options) or all staff members providing the service (for STAFF_MEMBER options).

For a list of error messages, see Create Service Options and Variants Errors.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Manage Service Options And Variants
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostClone Service Options And 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.

Clones a serviceOptionsAndVariants object. This endpoint can be called, for example, to duplicate a service. The cloned service contains all the original service options and variants.

Each option in the cloned service has a newly-generated ID that is copied to all choices of the variants in the clone. The cloned service references the service provided in the request by target_service_id.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Manage Service Options And Variants
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/{cloneFromId}/clone

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet Service Options And 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.

Retrieves a serviceOptionsAndVariants object by service_options_and_variants_id.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Read Bookings - Including Participants
Read Service Options And Variants
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/{serviceOptionsAndVariantsId}

Was this helpful?
Yes
No

DeleteDelete Service Options And 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.

Deletes a serviceOptionsAndVariants object.

Because each service has only a single serviceOptionsAndVariants object, the service won't have any supported options and variants any longer. Instead, the standard Wix Bookings service price calculation is used.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Manage Service Options And Variants
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/{serviceOptionsAndVariantsId}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet Service Options And Variants By Service Id

Developer Preview

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

Retrieves a service's options and variants by service_id.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Read Bookings - Including Participants
Read Service Options And Variants
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/service_id/{serviceId}

Was this helpful?
Yes
No

PatchUpdate Service Options And 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.

Updates the specified fields of the serviceOptionsAndVariants object.

Currently, only a single option is supported per serviceOptionsAndVariants object.

If you want to update variants, you must pass the full list of supported variants.

If you want to update options, you must pass the full list of supported options.

For a list of error messages, see Update Service Options and Variants Errors.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Manage Service Options And Variants
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/{serviceOptionsAndVariants.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Service Options And 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.

Retrieves a list of serviceOptionsAndVariants, given the provided paging, filtering, and sorting.

Query Service Options And Variants runs with these defaults, which you can override:

  • id is sorted in ASC order
  • cursorPaging.limit is 100

For a detailed list of supported filtering operations see supported filters.

To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings Services and Settings
Read Bookings - Including Participants
Read Service Options And Variants
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/bookings/v1/serviceOptionsAndVariants/query

Was this helpful?
Yes
No

Service Options And Variants 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.

Triggered when a serviceOptionsAndVariants object is created.

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.bookings.catalog.v1.service_options_and_variants.

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.

createdEventobject
Event information.
Was this helpful?
Yes
No

Service Options And Variants 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.

Triggered when a serviceOptionsAndVariants object is updated.

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.bookings.catalog.v1.service_options_and_variants.

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.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Service Options And Variants 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.

Triggered when a serviceOptionsAndVariants object is deleted.

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.bookings.catalog.v1.service_options_and_variants.

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.
Was this helpful?
Yes
No