Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

Information about filters, paging, and sorting.

query

CommonQueryV2

Additional options for performing the query.

options

QueryExtendedBookingsOptions

Retrieves a list of bookings, including additional extended information, given the provided paging, filtering, and sorting.

Up to 100 extended bookings can be returned per request.

`queryExtendedBookings()` runs with these defaults, which you can override:

- `createdDate` sorted in `DESC` order
- `cursorPaging.limit` is `50`


You can retrieve information about which actions the customer can perform
for the bookings. To do so, pass `withBookingAllowedActions` as `true`.


For field support, see
[supported filters](https://www.wix.com/velo/reference/wix-bookings-v2/extendedbookings/supported-filters)
for more information.

You can specify a filter only once per query. If you specify a filter
more than once, only the first filter determines the extended bookings that are returned.

When filtering by date, you must use [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).

import { extendedBookings } from '@wix/bookings';

async function queryExtendedBookings(query, options) {
  const response = await extendedBookings.queryExtendedBookings(query, options);
};

queryExtendedBookings: Wix-hosted

import { createClient } from '@wix/sdk';
import { extendedBookings } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { extendedBookings },
  // Include the auth strategy and host as relevant
});


async function queryExtendedBookings(query, options) {
  const response = await myWixClient.extendedBookings.queryExtendedBookings(query, options);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

queryExtendedBookings: Self-hosted

queryExtendedBookings

Manage Bookings - all permissions

Read Bookings - all read permissions

Manage Bookings

Read Bookings - Including Participants

Read bookings calendar - including participants

QueryExtendedBookingsResponse

---
title: Introduction
---

# Introduction

With the Wix Bookings Extended Bookings API, you can retrieve bookings for a site's services.  

In addition to retrieving information about bookings, you also retrieve additional extended information, such as whether the booking can be refunded or rescheduled, and attendance for the booking.

## Terminology

For a comprehensive glossary of Wix Bookings terms, see [Terminology](https://dev.wix.com/docs/sdk/backend-modules/bookings/terminology).  


To use the ExtendedBookings API, install the `@wix/bookings` package using npm or Yarn:
  ```console
npm install @wix/bookings
```

or

```console
yarn add @wix/bookings
```

Then import `{ extendedBookings }` from `@wix/bookings`:

```js
import { extendedBookings } from '@wix/bookings'
```
  

---
title: Supported Filters
---

# Supported Filters

[`queryExtendedBookings()`](https://dev.wix.com/docs/sdk/backend-modules/bookings/extended-bookings/query-extended-bookings) runs with these defaults:

+ sorted by `id` in `ASC` order
+ cursorPaging.limit is `50`

`query.fields` and `query.fieldsets` aren't supported for this endpoint.

The following table shows field support for filters for the booking object:


| Field                                                                       | Supported Filters                             |
|-----------------------------------------------------------------------------| --------------------------------------------- |
| id                                                                          | `eq`, `ne`, `in` |
| bookedEntity.item.slot.sessionId                                            | `eq`, `ne`, `in` |
| bookedEntity.item.slot.serviceId                                            | `eq`, `ne`, `in` |
| bookedEntity.item.slot.scheduleId                                           | `eq`, `ne`, `in` |
| bookedEntity.item.slot.resource.id                                          | `eq`, `ne`, `in` |
| bookedEntity.item.slot.location.id                                          | `eq`, `ne`, `in` |
| bookedEntity.item.slot.location.locationType                                | `eq`, `ne`, `in` |
| bookedEntity.item.schedule.scheduleId                                       | `eq`, `ne`, `in` |
| bookedEntity.item.schedule.serviceId                                        | `eq`, `ne`, `in` |
| bookedEntity.item.schedule.location.id                                      | `eq`, `ne`, `in` |
| bookedEntity.item.schedule.location.locationType                            | `eq`, `ne`, `in` |
| bookedEntity.tags                                                           | `hasSome`, `hasAll` |
| contactDetails.contactId                                                    | `eq`, `ne`, `in` |
| status                                                                      | `eq`, `ne`, `in` |
| paymentStatus                                                               | `eq`, `ne`, `in` |
| selectedPaymentOption                                                       | `eq`, `ne`, `in` |
| createdDate                                                                 | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| externalUserId                                                              | `eq`, `ne`, `in` |
| createdBy.contactId                                                         | `eq`, `ne`, `in` |
| createdBy.id.appId                                                          | `eq`, `ne`, `in` |
| createdBy.id.wixUserId                                                      | `eq`, `ne`, `in` |
| createdBy.id.memberId                                                       | `eq`, `ne`, `in` |
| createdBy.id.anonymousVisitorId                                             | `eq`, `ne`, `in` |
| startDate                                                                   | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| endDate                                                                     | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| updatedDate                                                                 | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| doubleBooked                                                                | `eq`, `ne` |
| participantsInfo.type.totalParticipants.value                               | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| participantsInfo.type.participantsChoices.serviceChoices.choices.optionId       |  `hasSome`, `hasAll` |
| participantsInfo.type.participantsChoices.serviceChoices.choices.choice.custom.value |  `hasSome`, `hasAll` |

You can only specify a filter only once per query. If a filter is provided 
more than once, only the first occurrence affects the returned bookings.

When using filters for dates, you must use [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).

Bookings belonging to a schedule don't have a `sessionId`. Therefore you 
must use the `sessionId` filter that isn't part of the `query` object to 
filter bookings for courses.


bookings_extended-bookings

Address

Main address line, usually street and number, as free text.

addressLine

Street name, number and apartment number.

streetAddress

Free text providing more detailed address info. Usually contains Apt, Suite, and Floor.

addressLine2

string

city

country

countryFullname

A string containing the full address of this location.

formattedAddress

geocode

AddressLocation

hint

postalCode

Subdivision. Usually state, region, prefecture or province code, according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2).

subdivision

Multi-level subdivisions from top to bottom.

subdivisions

latitude

number

longitude

AllowedActions

Whether the customer is allowed to cancel the booking.

cancel

boolean

Deprecated.
Whether the customer is entitled to a refund when canceling the booking.

refund

Whether the customer is allowed to reschedule the booking.

reschedule

Attendance

Total number of participants that attended the session.

numberOfAttendees

General Information about the booking's attendance.

+ `NOT_SET`: There is no available attendance information.
+ `ATTENDED`: At least 1 participant attended the session.
+ `NOT_ATTENDED`: No participant attended the session.

status

AttendanceStatus

BookedEntity

The booked schedule. The booking is automatically assigned to the schedule's sessions.

schedule

The booked slot, once booked becomes a session, The booking is automatically assigned to the session if it already exists, or creates a session if one doesn't already exist.

slot

List of tags for the booking.
System-assigned tags for sessions and schedules are:
+ "INDIVIDUAL" Appointments, including appointments with more than 1 participant.
+ "GROUP" Individual classes.
+ "COURSE" Courses.

title

BookedResource

email

name

scheduleId

BookedSchedule

The start time of the first session in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
format. Required.

firstSessionStart

The end time of the last session in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
format. Required.

lastSessionEnd

Location where the schedule's sessions take place. Read only.

location

Location

serviceId

The timezone according to which the slot was shown to the user when booking, and should be shown in future.

timezone

BookedSlot

The end time of this slot in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
format.

endDate

Calendar 3 event ID
If not empty, on all write flows (create / update) gets priority over session_id.
so if both session_id and event_id are provided, the session_id that will be set on the booking will be based on the event_id.
Otherwise, if event_id is empty on write flow,

eventId

Location where the slot's session takes place.

The enriched resource assigned to the slot, can be either the requested resource or the resource chosen by the system.
When populated, the given resource will be booked according to it's availability.
When empty, If `skip_availability_validation` is `false`, a random available resource will be assigned to the slot upon confirmation,
otherwise one of the service resources will be assigned to the slot randomly upon confirmation.
This resource is the slot primary resource.

resource

ID of the underlying session when session is a single session or generated from a recurring session.
If `sessionId` is defined in the `Create Booking` request, the `startDate`, `endDate`, `timezone`, `resource`, and `location` fields are ignored and populated from the existing session's information.

sessionId

The start time of this slot in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
format.

startDate

Booking

Information about the booked service choices and participants.
Available only when the booking includes multiple service variants.

participantsChoices

Total number of participants. Available only when the booking includes a single service variant.

totalParticipants

_createdDate

_updatedDate

Additional custom fields submitted with the booking form.

additionalFields

An object describing the slot or schedule that was booked.

bookedEntity

Contact details of the site visitor or member making the booking.

contactDetails

ContactDetails

ID of the creator of the Booking.
If `appId` and another ID are present, the other ID takes precedence.

createdBy

IdentificationData

Whether this booking overlaps another existing confirmed booking. Returned when: `true`

doubleBooked

The end date of this booking. For a slot, this is the end date of the slot. For a schedule, this is the end date of the last session.

Custom field data for this object. Extended fields must be configured in the Wix Dev Center before they can be accessed with API calls.

extendedFields

ExtendedFields

External ID provided by the client app on creation.

externalUserId

Payment status.
One of:
- `"NOT_PAID"` The booking is not paid for.
- `"PAID"` The booking is fully paid.
- `"PARTIALLY_PAID"` The booking is partially paid.
- `"REFUNDED"` The booking is refunded.
- `"EXEMPT"` The booking is free of charge.

paymentStatus

PaymentStatus

Revision number to be used when updating, rescheduling, or cancelling the booking. Revision number, which increments by 1 each time the booking is updated, rescheduled, or canceled. To prevent conflicting changes,the current revision must be passed when updating the booking.

revision

Selected payment option.
One of the payment options offered by the service, or another option if `skipSelectedPaymentOptionValidation` is `true`.
When undefined, the payment option is resolved by the service configuration on checkout.

selectedPaymentOption

SelectedPaymentOption

The start date of this booking. For a slot, this is the start date of the slot. For a schedule, this is the start date of the first session.

Booking status.

Supported values:
- `CREATED`: The booking was created.
- `UPDATED`: The booking was updated.
- `PENDING`: The booking is waiting to be confirmed or declined by the business owner. A booking is automatically set as `PENDING` if the service is configured to require manual business onwer confirmation and an [eCommerce order](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/introduction) was created.
- `CONFIRMED`: The booking was confirmed. A booking is automatically confirmed if the service is configured to automatically confirm bookings and an [eCommerce order](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/introduction) was created. If the service isn't configured to automatically confirm bookings, you can use [Confirm Or Decline Booking](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/bookings-v2/bookings-v2-and-confirmation/confirm-or-decline-booking).
- `DECLINED`: The booking was declined by the business owner. A booking is also declined if an [eCommerce order](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/introduction) was created that resulted in a double booking.
- `CANCELED`: The booking was canceled.
- `WAITING_LIST`: The booking is on a wait list.

BookingStatus

CommonPaging

limit

Number of items to skip in the current sort order.

offset

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

cursorPaging

Paging options to limit and skip the number of items.

paging

Filter object in the following format:
`"filter" : {
"fieldName1": "value1",
"fieldName2":{"$operator":"value2"}
}`
Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`

  See [Supported Filters](https://www.wix.com/velo/reference/wix-bookings-v2/extendedbookings/supported-filters)
for a full list.

filter

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

sort

ConferencingDetails

URL used by a guest to join the conference.

guestUrl

password

contactId

Contact's country in [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.

countryCode

Contact's email, used to create a new contact or get existing one from the [Contacts API](https://dev.wix.com/api/rest/contacts/contacts). Used to validate coupon usage limitations per contact. If not passed, the coupon usage limitation will not be enforced. (Coupon usage limitation validation is not supported yet).

Contact's first name. When populated from a standard booking form, this property corresponds to the **Name** field.

firstName

fullAddress

lastName

phone

timeZone

CursorPaging

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

Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response.
Not relevant for the first request.

cursor

Maximum number of items to return in the results.

Cursors

Cursor string pointing to the next page in the list of results.

CustomFormField

ID of the form field as defined in the form.

Form field's label at the time of submission.

label

value

valueType

ValueType

ExtendedBooking

Information about which actions the customer can perform for the
booking. Available only when passing `withBookingAllowedActions` as `true`.

allowedActions

Information about attendance. Available only when passing
`withBookingAttendanceInfo` as `true`.

attendance

booking

Information about the online conferencing details. Available only when passing
`withBookingConferencingDetails` as `true`.

conferencingDetails

Extended field data. Each key corresponds to the namespace of the app that created the extended fields.
The value of each key is structured according to the schema defined when the extended fields were configured.

You can only access fields for which you have the appropriate permissions.

Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields).