Bookings API Overview
The Bookings API lets you create applications for Square sellers and their customers to create and manage bookings. A booking refers to a reservation of a service provided by a staff of the seller for a customer over a specified time duration at a particular time and location.
Both the seller (including an authorized team member, often referred to as staff) and the customer (also known as the buyer) can create and manage a booking. However, the seller has more control in how to create and manage a booking and has a wider scope of access to existing bookings than the buyer. As such, seller-scoped and buyer-scoped operations require different levels of access permissions that are referred to in this documentation as seller-level permissions and buyer-level permissions, respectively.
You can add custom attributes to the Booking object. To do so, use the Booking Custom Attributes API.
Seller-level permissions grant an application full visibility into a seller's calendar and they enable full control of the seller's bookings.
Buyer-level permissions, on the other hand, grant partial visibility into a seller's calendar, limited to bookings created by the calling application. Buyer-level permissions enable limited control of bookings for buyers only.
With seller-level permissions, the following can happen:
An application can access and view every booking of a seller. For example, calling ListBookings can return every booking in the seller's calendar.
Every change to a booking is sent to webhooks, as a booking.created or booking.updated event.
An application can create double bookings to serve different customers at the same time or location. It can also create off-hour bookings outside the seller's regular business hours.
With buyer-level permissions, the following can happen:
An application can only access and view bookings that it created. Calling
ListBookings
returns bookings created by the application only.An application must create a booking to receive event notifications of changes to a booking for the user if the booking was created using the API or when the API-created booking is updated using the API, the Seller Dashboard, or the seller's booking site.
An application cannot create double bookings for the user or create a booking outside the seller's regular business hours.
Using the Bookings API, your application can perform the following tasks:
Retrieve bookings and inspect the details of each booking, including services to be provided, bookable team members providing the services, and the location where the customer receives the services.
Search for the availability of a service, team member, and location to facilitate a booking. The returned availability can be turned into a booking by adding a customer.
Maintain bookings, including the creation, update, and cancellation of a booking. To create, update, or cancel a seller-level booking, the targeted seller must have subscribed to a paid Appointments subscription plan and your application must have seller-level permissions.
Square Appointments Plus or Appointments Premium is a monthly paid subscription plan to Square Appointments. When a seller subscribes to a paid subscription plan, you can call the Bookings API to create, update and cancel seller-level bookings with the seller. By default, a seller subscribes to the free subscription plan that offers basic Appointments features. With the free subscription plan, you can call the Bookings API to create, update or cancel buyer-level bookings with the seller and to access any readable property of a booking.
To integrate the Bookings API with a paid Appointments subscription plan of a seller for creating, updating or canceling a seller-level booking, your application must have the writeable seller-level permissions. The OAuth scopes must include the following permissions:
APPOINTMENTS_WRITE
APPOINTMENTS_ALL_WRITE
When using the Bookings API with the free Appointments subscription plan, the application must have all of the buyer-level permissions plus the readable seller-level permission. The OAuth scopes can include the following permissions:
APPOINTMENTS_READ
APPOINTMENTS_WRITE
APPOINTMENTS_ALL_READ
APPOINTMENTS_BUSINESS_SETTINGS_READ
You can call the Bookings API to verify whether a seller supports creating, updating or canceling a seller-level booking, before attempting to carry out such operations. To do so, call RetrieveBusinessBookingProfile and inspect the response for the support_seller_level_writes attribute. Only when the returned value is true
can you proceed successfully to create, update, or cancel seller-level bookings.
When a seller does not have the Appointments Plus or Premium subscription plan, all the API calls targeted at the seller with buyer-level permissions and those with seller-level readable permissions succeed. However, API calls targeted at the seller with seller-level writeable permissions fail with a 403
response containing the following error message:
When a seller subscribes to an Appointments plan, the same plan applies to all active locations of the seller and each location is billed the same price of the chosen plan. A seller cannot subscribe to one plan at a location and another plan at another location.
As of May 12, 2022, applications creating, updating or cancelling bookings with seller-level permissions are granted a legacy exception for one year. By May 12, 2023, a legacy seller must subscribe to a paid subscription plan for the existing integration to continue to work.
A booking application using the Bookings API uses several other Square APIs. They include:
The Locations API, which is used to choose a seller's business location where a customer receives a booked service provided by a team member of the seller.
The Team API, which is used to choose a team member of the seller to provide a booked service.
The Customers API, which is used to create a new customer or search for an existing customer for a booking.
The Catalog API, which is used to create a bookable service that is represented by a CatalogItemVariation object.
A team member who can be booked to provide a service must be a bookable team member. The seller or a designated representative of the seller can make a team member a bookable team member by adding the team member (an employee) to a service in the Seller Dashboard. This task cannot be delegated to any third-party developer calling the Square API.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.