# About the Bookings Reader V2 API

With the Bookings Reader V2 API you can retrieve extended bookings for a site's services.
The extended booking object holds information about the customer, the session or
schedule they have booked, whether they can cancel or reschedule, and attendance details.

The Bookings Reader V2 API allows you to retrieve extended bookings and count
how many bookings match a specific filter.

You can read more about:

+ [Bookings Writer V2 API](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/introduction):
  Create bookings and manage their life cycle.
+ [Attendance API](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/attendance/introduction):
  Track attendance data for booking sessions.
+ [Bookings Services API](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction):
  Manage a site's services so customers can book appointments, class sessions, and courses.
+ [Availability Calendar API](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/time-slots/availability-calendar/introduction):
  Calculate the availability of appointments and class sessions.
+ [Calendar V3 APIs](fallback::https://dev.wix.com/docs/rest/business-management/calendar/introduction):
  Manage a site's business schedules and events.
  
## Use cases

- [Reach out to customers who have recently canceled](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-reader-v2/sample-flows).

## Before you begin

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

- [Wix Bookings](fallback::https://www.wix.com/app-market/web-solution/bookings)
  must be installed on a site before you can use the Bookings Reader V2 APIs.
- There is no Get Extended Booking method, instead you can call [Query Extended Booking](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-reader-v2/count-extended-bookings)
  specifying a single booking ID in the filter.
- The `participantNotification` object is overridden every time a new
  message about a booking change is specified. The objects holds only the very
  last message. It also doesn't specify whether the message was sent due to
  canceling, rescheduling, declining, or confirming the booking.

## Terminology

- **Booking**: An entity representing a scheduled appointment, class session,
  or course. Includes details about the customer and payment status.
- **Booked entity**: Details about the timing of the appointment, class session,
  or course that has been booked.
- **Extended booking**: A booking with additional information such as attendance
  details and whether the customer can cancel or reschedule.

For a comprehensive glossary of Wix Bookings terms, see [Terminology](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/terminology).

@sdk_package_setup

# Bookings Reader V2: Supported Filters

The following table shows field support for filters
for the extended booking object in
[Query Extended Bookings](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::cf43f2ae-e5f0-462d-adde-0da2cb5606b2slug::query-extended-bookings*fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/bookings-v2/bookings-reader-v2/query-extended-bookings)
and [Count Extended Bookings](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::cf43f2ae-e5f0-462d-adde-0da2cb5606b2slug::count-extended-bookings*fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/bookings-v2/bookings-reader-v2/count-extended-bookings):

| Field                                                                       | Supported Filters                             |
|-----------------------------------------------------------------------------| --------------------------------------------- |
| `id`                                                                          | `eq`, `ne`, `in` |
| `bookedEntity.item.slot.sessionId`                                          | `eq`, `ne`, `in` |
| `bookedEntity.item.slot.eventId`                                          | `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` |
| `contactDetails.email`                                                    | `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` |

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

## Filter Performance

For optimal query performance, use at least one of the following fields when filtering data:

+ `id`
+ `startDate`
+ `endDate`
+ `contactDetails.contactId`
+ `contactDetails.email`
+ `bookedEntity.item.slot.sessionId`
+ `bookedEntity.item.schedule.scheduleId`
+ `bookedEntity.item.slot.eventId`

We strongly recommend including `startDate` as filter in all
[Query Extended Bookings](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::cf43f2ae-e5f0-462d-adde-0da2cb5606b2slug::query-extended-bookings*fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/bookings-v2/bookings-reader-v2/query-extended-bookings)
requests, especially when not using any of the other filters listed above.

## See also

To learn about working with _Query_ endpoints, see
[API Query Language](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::8158a590-f60c-4606-9fed-16a34e275f3a*fallback::https://dev.wix.com/api/rest/getting-started/api-query-language),
[Sorting and Paging](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::070cf69c-a779-4b95-b522-a094d30dff2f*fallback::https://dev.wix.com/api/rest/getting-started/sorting-and-paging),
and [Field Projection](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::eaf4d3d6-5b76-489f-8839-f66476be32e6*fallback::https://dev.wix.com/api/rest/getting-started/field-projection).

# Bookings Reader V2: Sample Flows

This article shares basic flows you could support. You're certainly not
limited to these use cases, but they can be a helpful jumping-off point for your
planning. Your app could add identify customers who have recently canceled
their booking and reach out to them.

## Reach out to customers who have recently canceled

Your app could add identify customers who have canceled a booking that was
scheduled to take place during a specific month and reach out to them.

To identify recently canceled bookings:

1. Call Query Extended Bookings
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/extended-bookings/query-extended-bookings) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-reader-v2/query-extended-bookings)). Use this query filter:
   
   ```json
   {
     "query":{
       "filter":{
         "status":"CANCELED",
         "$and":[
           {
             "startDate":{
               "$gte":"2025-02-01T00:00:00Z"
             }
           }
         ],
         "$and":[
           {
             "startDate":{
               "$lte":"2025-02-28T23:59:59Z"
             }
           }
         ]
       }
     }
   }
   ```

   Make sure to include at least one filter performance-optimized filter
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/extended-bookings/supported-filters#filter-performanc) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-reader-v2/supported-filters#filter-performance)).
1. For every retrieved booking, save `contactDetails.email`.
1. Reach out to the relevant customers.