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:

• Wix Bookings Pricing API to preview and calculate the price.
• Wix Bookings Pricing Provider SPI that allows site owners to implement custom pricing logic.

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.

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

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.

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.

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.

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.

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.

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

Copy Code
"filter" : 
  { 
    "fieldName": "value",
  }

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

Field	Supported Filters	Sortable
id	$eq, $ne, $in	Sortable
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

Query Service Options and Variants runs with this default:

• sorted by id in ASC order

Specify the sort object in the following format:

Copy Code
"sort" : [ 
  { 
    "fieldName":"sortField1",
    "order":"ASC"
  },
  { 
    "fieldName":"sortField2",
    "order":"ASC"
  },
]

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:

• API Query Language
• Sorting and Paging
• Field Projection
• Query Service Options and Variants endpoint

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

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_IDS	Unknown 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_CURRENCIES	Multiple currencies <currencies> aren't supported in the variants array.	Make sure that all variants use the same currency.
INVALID_ARGUMENT (400)	UNSUPPORTED_OPTION_TYPE	Option 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_IDS	Staff 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_VARIANTS	Staff 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_CHOICES	Identical 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_CHOICES	Choices <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_PRICES	Prices must have positive values.	Make sure that all prices have positive values.
INVALID_ARGUMENT (400)	UNSUPPORTED_OPTION_DATA	Option 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.

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_IDS	Unknown 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_CURRENCIES	Multiple currencies <currencies> aren't supported in the variants array.	Make sure that all variants use the same currency.
INVALID_ARGUMENT (400)	UNSUPPORTED_OPTION_TYPE	Option 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_IDS	Staff 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_VARIANTS	Staff 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_CHOICES	Identical 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_CHOICES	Choices <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_PRICES	Prices must have positive values.	Make sure that all prices have positive values.
INVALID_ARGUMENT (400)	UNSUPPORTED_OPTION_SPECIFIC_DATA	Option data isn't supported for option type <optionType>.	Make sure to pass customData for custom options or no data for staff member based options.