Applies to: Bookings API | Booking Custom Attributes API | Locations API | Team API | Customers API | Catalog API
Learn about using the Bookings API to 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 doesn't 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:
{
"errors": [
{
"category": "AUTHENTICATION_ERROR",
"code": "FORBIDDEN",
"detail": "Merchant subscription does not support write operations."
}
]
}
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.