Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Bookings API

Get Ready to Use the Bookings API

To get you ready to use the Bookings API, review some basic concepts used in the API and 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.

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 Square API Access Tokens.

  • For your application to access Appointments resources on behalf of a Square seller with OAuth, you must have APPOINTMENTS_READ, APPOINTMENT_BUSINESS_SETTINGS_READ, or both OAuth scopes for read operations of the Bookings API and you must have APPOINTMENTS_WRITE, APPOINTMENT_BUSINESS_SETTINGS_WRITE, or both OAuth scopes for write operations.

  • 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 International Availability.