Learn basic concepts and prerequisites about bookings, appointments, availability, and appointment segments used in the Square Bookings API.
Bookings API

Get Ready to Use the Bookings API

To get ready to use the Bookings API, review some basic concepts used in the API and the requirements and limitations imposed by the API.

Basic concepts Permalink Get a link to this section

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.

Requirements and limitations Permalink Get a link to this section

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 Dashboard.

  • 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 Seller 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 Seller Dashboard to do that.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.