Bookings API Concepts

Applies to: Bookings API

Learn basic concepts and prerequisites about bookings, appointments, availability, and appointment segments.

The Bookings API makes use of the following concepts:

• Booking - An agreement between a seller and a customer to provide a specific service or a set of services at a particular location in contiguous time slots of fixed durations starting at a specific time.

• Appointment - A block of contiguous time slots, also known as the service segments or appointment segments. Each segment references a service and a team member to provide the service.

• Availability - An inventory of available appointment segments pertaining to one or more services, team members as service providers, and service locations.

• Appointment segment - A portion of an appointment in which a specific service is provided. A segment is time-bound and segments within an appointment are ordered and non-overlapping.

• Paid Appointments plan - Appointments Plus or Appointments Premium is a paid subscription plan that is required to create, update, and cancel a seller-level booking. A seller can subscribe to only one (free or paid) Appointments plan, which is applied to all active locations of the seller. Each active location is billed, independently, according to the subscribed plan.

Before using the Bookings API, make sure that the following requirements are met and limitations understood:

• You must have a Square developer account. To create your developer account, sign up for a Square developer account.
• You must have at least one application created in your developer account. To create one, go to the Square Developer Console.
• You must have the application's access token ready when calling the API. For more information, see Get a personal access token.
• Your application must have appropriate buyer-level or seller-level permissions to access booking resources for buyer-initiated or seller-initiated operations, respectively:
  • For applications with buyer-level permissions, they must have APPOINTMENTS_READ, APPOINTMENT_BUSINESS_SETTINGS_READ, or both OAuth scopes for read operations and they must have APPOINTMENTS_WRITE, APPOINTMENT_BUSINESS_SETTINGS_WRITE, or both OAuth scopes for write operations.
  • For applications with seller-level permissions, they must have the APPOINTMENTS_ALL_READ OAuth scope plus APPOINTMENTS_READ, APPOINTMENT_BUSINESS_SETTINGS_READ, or both for read operations and they must have APPOINTMENTS_ALL_WRITE plus APPOINTMENTS_WRITE, APPOINTMENT_BUSINESS_SETTINGS_WRITE, or both for write operations.
• You must ensure that a targeted seller has subscribed to a paid Appointments plan before creating, updating, or canceling a seller-level booking.
• You cannot use the Bookings API to create team members or make them bookable to provide scheduled services offered by the seller. The seller must use the Square Dashboard to make a team member bookable by adding the team member to a bookable service for bookings. Nevertheless, you can call the Team API to create team members.
• The Bookings API is limited in international locales. For supported international locales, see Square Appointments FAQs.
• You cannot currently use the Bookings API to create a booking with a non-zero cancellation fee. You must use the Square Dashboard to do that.