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.

Link to section

Seller-level and buyer-level permissions

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.

Link to section

Bookings API operations

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.

Link to section

Integration with paid subscription plans

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:

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

Link to section

One-year support for legacy integration

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.

Link to section

Integration with other Square APIs

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.

Link to section

Next steps

• Get Ready to Use the Bookings API

• Onboard to Square Appointments

• Use the Bookings API

• Handle Bookings Webhook Events