Bookings API

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 member of the seller's staff for a customer over a specified time duration at a particular time and location.

Both the seller (or a team member, called staff) and the customer (also known as the buyer) can create and manage a booking. However, the seller has more control and access to bookings than the buyer. Therefore, seller and buyer operations need different access permissions, called seller-level and buyer-level permissions in this topic.

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. A seller must have a subscription to Appointments Plus or Premium to use this feature.

Buyer-level permissions 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. All sellers have access to this feature.

With seller-level permissions, your application can do the following:

• Access and view every booking of a seller - For example, calling ListBookings can return every booking in the seller's calendar.
• Generate bookings webhooks - Every change to a booking is sent to webhooks, as a booking.created or booking.updated event.
• Create double bookings - Allows service of 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, your application can do the following:

• Access and view bookings that it created - Calling ListBookings returns bookings created by the application only.
  • An application must create a booking to get event notifications about changes to a booking. This applies if the booking was created using the API or if an API-created booking is updated using the API, the Square 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 - 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 - 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.

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 Square Dashboard. This task cannot be delegated to any third-party developer calling the Square API.

• Bookings API Concepts
• Onboard to Square Appointments
• Create and Manage Bookings
• Handle Bookings Webhook Events