About Wix Bookings Services

The Wix Bookings Services API enables you to retrieve the services your business offers.

The service contains the information customers need to decide whether to book the business offering. This includes the type of offering (appointment, class, course), scheduling information, locations, booking policies (such as the latest possible time a session can be booked), payment information, and more. Creating and managing your services is the cornerstone for working with Wix Bookings.

Once services are created, you can:

  • Use these Services APIs to retrieve information about the service(s), enabling you to make the information available to your customers.

  • Use other Bookings APIs to process customer bookings, manage schedules and calendars, check availability, and more.

More About Services

A service is an online or in-person offering that a business provides to its customers, such as courses and private sessions.

For example, a fitness studio may offer the following services:

  • A 1-hour Pilates class
  • A 30-minute 1-on-1 personal training session
  • A 4-month Yoga course for instructors

Alternatively, a hair salon may offer the following services:

  • A 30-minute haircut appointment
  • A 2-hour hair coloring appointment
  • A 3-week hair styling course

Services may differ in the offering they provide, but the API differentiates between 3 main types of services:

  • Appointments: An appointments is a 1-time session that can be booked and scheduled by a customer. The appointment takes place whenever a customer books a specific time slot.

    For example, a 30-minute haircut.

  • Classes: Recurring sessions of multiple participants scheduled by the business. Customers can book any session of the class. Classes can be scheduled on different days, at different times, with different resources, such as staff members. Customers can sign up for single sessions or a class's recurring sessions.

    For example, a language school offers a beginner's Spanish class every Monday at 8:00 PM. Customers can join the session they want and don't have to commit to attending all sessions.

  • Courses: A limited number of sessions for the same service that starts and ends on a particular day. Customers sign up for the entire course and not just one session.

    For example, a 12-session introductory course to Pilates, starting on February 1st and ending on March 17th.

Before you begin

Before using the API, make sure to set up Wix Bookings and create the right services for your business.

Sample Use Cases

Terminology

  • Booking: Information about the service that the customer has booked. Includes details about the time, location, participants, and price.

  • Schedule: A collection of sessions that belong to the same class, course, appointment, or resource. Schedules also comprise available slots that can still be booked. Additional information required to calculate availability is also contained in a schedule. Read more about schedules.

    • Appointment schedules: The schedule determines when customers can book a session. Bookability is determined using the specified session's duration, the time between sessions, and the schedules of staff members who provide the service.

      For example, given the following scheduling criteria for a business offering haircuts, the schedule allows customers to book sessions from 9:00 to 17:30 with the possibility of booking a maximum of 9 sessions per day:

      • The business offers a 30-minute haircut service.
      • The schedule allows customers to book 30-minute sessions with 30 minutes between each session.
      • The staff members are available from 9:00 to 18:00.
    • Class & course schedules: For classes and courses, the business decides when to schedule a session. This is in contrast to appointments, where the customer decides when to book a session. For classes and courses, the schedule is used to manage the available sessions and holds some aggregated information, such as the start time and end time of a course.

  • Session: An occupied period of time in a schedule. A session is a term we use for any occupied period of time, whether that period is an appointment, class, or course.

    For example, if a “Vinyasa Yoga” class-type service is offered every Monday between 6-7pm, the class on Monday June 5, 2023 from 6-7pm is 1 session in a schedule.

    Therefore, sessions are the building blocks of appointments, classes, and courses. Each of these types of services comprise sessions. The collection of related sessions for a service represent the service's schedule. Read more about sessions.

  • Slot: An available period of time in a schedule that can be booked by a customer. While this includes existing sessions that are available for booking, it can also represent a period of time that can be booked based on the availability of a resource, such as a barber with appointments of 30 minutes each that are open for booking every weekday between 8:00 - 17:00. These slots are calculated according to the constraints of the schedule.

  • Bookings Policy: Terms the business wants to enforce when customers try to book a service. For example, how far in advance customers may book a service or until what point before the start of a session customers can cancel.

Was this helpful?
Yes
No

Services: Sample Use Cases and 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.

Periodically export new Wix Bookings services to an external catalog

If a site owner manages their services in an external catalog, you can export new services to it. To do this, your app can periodically bulk load new services being offered:

  1. For the first load after the app is installed and services are defined, use Query Services to retrieve all services. By default the initial paging limit is 100.

  2. If you receive 100 services, there may be more services to retrieve. Run the request again, and increase paging.offset to 100. Keep running the request, each time increasing the offset, until all services are retrieved.

  3. Upload the retrieved services to the external catalog.

  4. Save the current datetime, and use it in the next request. Each subsequent request will need to use the datetime of the request that came before it.

  5. For all subsequent loads, use Query Services , and filter for new services created since the last load:

    Copy
    1
    {
    2
    "sort": {
    3
    "fieldName": "createdDate",
    4
    "order": "ASC"
    5
    },
    6
    "filter": {
    7
    "createdDate": {
    8
    "$gt": "<PREVIOUS_LOAD_DATETIME>"
    9
    }
    10
    }
    11
    }
  6. Repeat steps 2 to 4 for each subsequent load. You can allow the site admin to configure the time interval in your app to fit their needs.

Was this helpful?
Yes
No

Services: Filtering and Sorting

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

Filtering

Specify the filter object in the following format:

Copy
1
{
2
"filter": {
3
"fieldName": {
4
"$eq": "value"
5
}
6
}
7
}

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

FieldSupported FiltersSortable
name$eq, $ne, $exists, $in, $startsWithSortable
type$eq, $ne, $exists, $in,Sortable
description$eq, $ne, $exists, $in, $startsWithSortable
hidden$eq, $ne, $exists, $in
tagLine$eq, $ne, $exists, $in, $startsWithSortable
staffMemberIds$eq, $ne, $exists, $in, $hasSome, $startsWith
form.id$eq, $ne, $exists, $in, $startsWith
category.id$eq, $ne, $exists, $in, $startsWith
mainSlug.name$eq, $ne, $exists, $in, $startsWithSortable
supportedSlugs.name$eq, $ne, $exists, $in, $hasSome, $startsWithSortable
locations.business.id$eq, $ne, $exists, $in, $hasSome, $startsWith
onlineBooking.enabled$eq, $ne, $exists, $in
payment.options.online$eq, $ne, $exists, $in
payment.options.inPerson$eq, $ne, $exists, $in
payment.options.pricingPlan$eq, $ne, $exists, $in

Sorting

The default sort is by createdDate in ascending (ASC) order.

Specify the sort object in the following format:

Copy
1
{
2
"sort": [
3
{
4
"fieldName": "sortOrder",
5
"order": "ASC"
6
},
7
{
8
"fieldName": "createdDate",
9
"order": "DESC"
10
}
11
]
12
}

Fields

Specify the fields object in the following format:

Copy
1
{
2
"fields": [
3
"name",
4
"type",
5
"description"
6
]
7
}

Related content:

Was this helpful?
Yes
No

Receiving payments

Payment rates

The service price can be expressed in one of the following ways:

  • Fixed rate: The service price is fixed and does not change.
  • Varied rate: The service price may depend on different factors, such as the staff member providing the service or custom price options. Read more about price options.
  • Custom rate: The service price is expressed as a custom string. For example, "Free", "Donation", or "Contact us for pricing".

Payment options

Payment options dictate in what manner the customer can pay for the service. The following payment options are available:

Copy
1
{
2
"onlinePayment": true,
3
"inPerson": true,
4
"deposit": true,
5
"pricingPlan": true,
6
}

It's required to specify either onlinePayment or inPerson as true.

Online payments

Enabling online payments allows customers to pay for the service at the time of booking.

To read more about the variety of ways you can receive online payments, please refer to the dedicated article.

Paying in person

Enabling a costumer to pay in person allows customers to pay for the service at the time of the service, and to book the service without going through the payment process.

It's recommended to set up online payments as services that accept online payment significantly reduce no-shows.

Requiring deposit

Setting a deposit requirement allows you to charge some amount of the service price as a deposit. The deposit is charged at the time of booking and the remaining balance is charged at the time of the service.

Setting deposit to true requires onlinePayment to be true as well.

The deposit amount should be specified in the rate object, and is supported both for fixed and varied rates.

Pricing plans

Enabling payment with pricing plan enables customers to pay for the service using a pricing plan. Read more about offering pricing plans.

Was this helpful?
Yes
No

Service Object

The Service object represents the business offering that a business provides to its customers.

Attributes
idstringRead-onlyformat GUID
Service ID.

typestring
4 supported values:
UNKNOWN_SERVICE_TYPEAPPOINTMENTCLASSCOURSE
Service type.

sortOrderintegerformat int32
Order of a service within a category.

namestringmaxLength 400minLength 1
Service name.

descriptionstringmaxLength 7000
Service description, such as High-class hair styling, cuts, straightening and color.

tagLinestringmaxLength 6000
Short service description, such as Hair styling.

defaultCapacityintegerminimum 1maximum 1000format int32
Default maximum number of customers that can book the service. The service cannot be booked beyond this capacity.

mediaobject
Media associated with the service.

hiddenboolean
Whether the service is hidden from the site.

categoryobject
The category the service is associated with.

formobject
The form used when booking the service.

paymentobject
Payment options for booking the service.

onlineBookingobject
Online booking settings.

conferencingobject
Conferencing options for this service.

locationsArray <Location>maxItems 500
The locations this service is offered at. In case of multiple (more than 1) location, All locations must be of type BUSINESS. For courses only: Currently, only 1 location is supported, for all location types.

bookingPolicyobject
Policy determining under what conditions this service can be booked. For example, whether the service can only be booked up to 30 minutes before it begins.

scheduleobject
The service's schedule, which can be used to manage the service's sessions.

staffMemberIdsArray <string>maxItems 220format GUID
IDs of the staff members providing the service. For appointments only.

supportedSlugsArray <Slug>Read-onlymaxItems 100
A slug is the last part of the URL address that serves as a unique identifier of the service. The list of supported slugs includes past service names for backwards compatibility, and a custom slug if one was set by the business owner.

mainSlugobject
The main slug for the service. mainSlug is either taken from the current service name or is a custom slug set by the business owner. mainSlug is used to construct the service's URLs.

urlsobject
URLs to various service-related pages, such as the calendar page and the booking page.

extendedFieldsobject
Extensions enabling users to save custom data related to the service.

seoDataobject
Custom SEO data for the service.

createdDatestringRead-onlyformat date-time
Date and time the service was created.

updatedDatestringRead-onlyformat date-time
Date and time the service was updated.

revisionobjectRead-only
Revision number, which increments by 1 each time the service is updated. To prevent conflicting changes, the existing revision must be used when updating a service.
Was this helpful?
Yes
No

PostCreate Service

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 a new service.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/bookings/v2/services

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

GetGet Service

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Manage Bookings Services and Settings
Manage Bookings
Read Bookings - Including Participants
Read Bookings - all read permissions
Manage Bookings - all permissions
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/bookings/v2/services/{serviceId}

Was this helpful?
Yes
No

DeleteDelete Service

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/bookings/v2/services/{serviceId}

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

PatchUpdate Service

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 a service.

Partial updates are supported.

Each time the service is updated, revision increments by 1. You must include the number of the existing revision when updating the service. This ensures you're working with the latest service information and prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/bookings/v2/services/{service.id}

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

PostQuery Services

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 up to 100 services, given the provided paging, filtering, and sorting.

Define queries using WQL - Wix Query Language. For field support for filters and sorting, see Supported Filters and Sorting.

To retrieve all services use an empty query:

Copy
1
{
2
"query": {}
3
}

Query Services runs with these defaults, which you can override:

  • paging.limit is 100.
  • paging.offset is 0.

Notes:

  • Use UTC format when filtering with dates.
  • Only 1 use of each filter in the same query is supported. If a filter is defined more than once in a query, only the first occurrence is processed.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Manage Bookings Services and Settings
Manage Bookings
Read Bookings - Including Participants
Read Bookings - all read permissions
Manage Bookings - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/bookings/v2/services/query

Was this helpful?
Yes
No

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

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.services.v2.service.

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

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.services.v2.service.

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

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.services.v2.service.

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