Use the Bookings API
You can use the Bookings API to create appointment-based applications that allow a customer of a Square seller to book an appointment for a particular service provided by the seller or one of the seller's team members. In addition to the Bookings API, you are likely to use other related Square APIs, such as the Locations API, Customers API, Team API, and Catalog API.
In general, a booking application supports a frontend as an interface with a user to let the user book an appointment for a particular service at a particular location. At various stages of the user interaction, you need to perform the following operations targeted at the backend:
Call the Locations API to list and retrieve business locations for the user to choose from for a particular booking.
Call the Catalog API to create, list, or search for services that can be booked by customers online.
Call the Customers API to create or search for a customer profile representing the user to receive the service for a booking.
Call the Bookings API to list or retrieve a booking profile of a team member who can provide a service for a booking.
Call the Bookings API to retrieve the booking profile of a business that provides a service in a booking.
Call the Bookings API to search for available service segments that can be booked in a booking.
Call the Bookings API to create, inspect, or update a booking.
Depending on the permissions granted, the user might succeed in performing all or some of the actions or have access to the whole or part of resulting booking information.
In the following sections, you learn how booking data can be accessed with buyer-level and seller-level permissions and how to call the API using cURL commands.
Applications with buyer-level permissions and those with seller-level permissions create different bookings and receive different booking event data. The differences are manifested in different scopes of access to the booking data by the two types of booking applications.
The following table lists the different scopes of access to booking data, with buyer-level and seller-level permissions. Attributes with read/write access can be set when a booking is created or modified when a booking is updated. Attributes with read-only or read/write access are included in the result from RetrieveBooking or ListBookings and they are included as part of event data in the webhook notification of the booking.created or booking.updated event.
Object | Field | Buyer-level access | Seller-level access |
|---|---|---|---|
| Booking | |||
| id | Read-only | Read-only | |
| version | Set for optimistic locking | Set for optimistic locking | |
| status | Read-only | Read-only | |
| created_at | Read-only | Read-only | |
| updated_at | Read-only | Read-only | |
| start_at | Read/write | Read/write | |
| location_id | Read/write[*] | Read/write[*] | |
| customer_id | Read/write[*] | Read/write[*] | |
| customer_note | Read/write | Read/write | |
| seller_note | None | Read/write | |
| transition_time_minutes | None | Read-only | |
| all_day | Read-only | Read-only | |
| creator_details | None | Read-only | |
| source | None | Read-only | |
| location_type | None | Read/write | |
| appointment_segments | Read/write[*] | Read/write | |
| AppointmentSegment | |||
| duration_minutes | Read-only | Read/write | |
| service_variation_id | Read/write | Read/write | |
| team_member_id | Read/write | Read/write | |
| service_variation_version | Read/write | Read/write | |
| any_team_member | Read-only | Read-only | |
| intermission_minutes | None | Read-only | |
| resource_ids | None | Read-only |
[*] When set, the value becomes immutable and cannot be updated with the specified permissions.
When enabling bookings for a service, the seller chooses one or more locations where to make the service available. To book a service, the customer must choose a business location for the scheduled appointment.
A business location is represented by a Location object and a booking is represented by a Booking object. To specify a business location for a booking, you reference the ID of the Location object in the Booking object.
To create and manage a booking, you need to supply the business location ID of a Square seller. To determine the location ID, you can call the ListLocations endpoint of the Locations API and present the result to the user to a location.
The following example shows how to call the ListLocations endpoint in a cURL command:
In this example, the seller runs the business at one location only. In addition to the business address, you can find the business hours in the result. Pay attention to the business hours so that you do not attempt to create a booking outside of the stated business hours.
When creating a booking, you need to specify a team member as the service provider. You reference the team member by the team member ID.
To determine team member IDs, call the ListTeamMemberBookingProfiles endpoint of the Bookings API, following this example:
Each bookable team member has a booking profile that has the is_bookable attribute set to true. Only bookable team members can be assigned to provide the service in a booking. A seller might have other employees as team members who are not bookable for any service. These employees are not included in the response.
Typically, you present the list of returned team members for the user to choose from to provide the service in a booking. When there is only one choice, simply make note of the returned team_member_id value and provide this ID to a booking afterwards.
To create a booking, you must specify a bookable service to be provided by the seller or one of the seller's team members. A bookable service is represented by a CatalogItemVariation object with its available_for_booking attribute set to true. To specify a bookable service, you reference the ID of the corresponding CatalogItemVariation object.
To determine the ID of a bookable service, you can call the SearchCatalogItems endpoint, set the product_types query expression to [APPOINTMENT_SERVICE], and inspect the result. The following example shows how to do this in cURL:
Did you know?
In the previous response, the non-zero cancellation fee (as expressed by the no_show_fee object) is set in the Seller Dashboard. It cannot be set using the Bookings API. The service with a non-zero now_show_fee value cannot be booked using the Bookings API.
You can infer the locations where the service is available from the present_at_all_locations, present_at_locations_ids, and absent_at_location_ids attribute values of the returned services.
Make note of the ID and version number of the desired service item variation. You need to provide the ID when creating a booking afterwards. Do not use the ID of the parent item, as represented by a CatalogItem object.
For a new bookable service, you must create a service variation, as represented by a CatalogItemVariation instance embedded within a CatalogItem object. You can do so in two ways:
Using the Catalog API, you can call the UpsertCatalogObject or BatchUpsertCatalogObjects endpoint to create a service variation and set the
available_for_bookingattribute totrue.Using the Seller Dashboard, you can create a bookable service variation by enabling the Bookable by Customers Online option for the newly created service.
To create a booking, you must specify a customer to receive the bookable service provided by the assigned or selected team member. In the Square API, a customer is represented by a Customer object.
To specify a customer, you reference the ID of the Customer object.
For a new customer, you can call the Customers API to create the customer, get the customer ID from the returned response, and specify the customer ID when creating a booking. The following example shows how to call the Customers API to create a new customer:
When creating a customer to be used as an input to CreateBooking, the Customer object must have the phone_number attribute defined.
Make note of the customer ID from the response. You need to supply it when creating a booking.
For an existing customer, you can call the SearchCustomers or ListCustomers endpoint of the Customers API to search for or retrieve the customer profile. The following cURL example shows how to call the SearchCustomers endpoint to find the ID of the customer whose email address is [email protected]:
Make note of the id attribute value of the returned customer. You need to supply it when creating a booking.
You can use different search filters to select an existing customer by other supported attributes, including the name and phone number. For more information, see Search for Customer Profiles.
To determine how a Square seller accepts and manages bookings, you can call the RetrieveBusinessBookingProfile endpoint of the Bookings API to retrieve the business booking profile of the seller. The seller identity is inferred from the access token obtained using the OAuth API. For more information, see OAuth Walkthrough: Test Authorization with a Web Server.
The following cURL example retrieves a business booking profile:
By inspecting the returned business booking profile, you can determine the booking policy for the business concerning, for example, whether the seller accepts booking requests automatically, whether multiple bookings are allowed, the booking's lead time, whether the customer can cancel a booking, and whether the customer can choose a team member.
An available slot, also called an availability, is a block of contiguous service segments that can be booked together by a customer at a particular location and starting time. Each segment includes a particular service, a particular team member providing the service, and the duration of the service offered in the segment.
Before creating a booking, you should search for availabilities by calling the SearchAvailability endpoint of the Bookings API. You can turn an availability into a booking by simply adding a customer to it. In other words, a booking is an availability plus a customer.
The following cURL example shows how to call the SearchAvailability endpoint to retrieve availabilities for the service provided by specified team members between 9 AM December 1, 2021, and 9 AM December 2, 2021 (Pacific Standard Time).
In the request body, the stated local times are converted to the corresponding UTC times (2021-12-01T17:00:00Z and 2020-12-01T17:00:00Z), which in this case is 8 hours ahead of the local time. The service is referenced by service_variation_id and the team members are referenced by the any expression of the team_member_id_filter. In this example, there is only one team member.
Important
The specified time range to search for availabilities must be longer than or equal to 24 hours and shorter than or equal to 31 days.
For the SearchAvailability endpoint, the all query expression is not supported by the team_member_id_filter. If you set the start_at_range filter to the following, you get an error because the specified time duration is 1 second less than 1 day:
On the other hand, if you set the start_at_range filter to the following, you get an error because the specified time duration is 1 second longer than 31 days:
If successful, the previous request returns a response similar to the following, which contains the available time slots that can be used for bookings within the specified time period. Unlisted time slots within this time period are already booked.
The response body contains a list of time slots available for a customer to book the referenced service provided by the referenced team member in the referenced location. Each time slot can be an available appointment that starts at the time specified by start_at and lasts for the sum of all the duration_minutes values under appointment_segments. Appointment segments are continuous parts of an appointment in which a customer can receive one or more services provided by one or more team members. For example, if a barber cuts only hair in one appointment setting, the appointment_segments object has a single appointment segment. If a hair salon cuts, washes, and perms hair in one appointment setting, one appointment might have three segments of services each of which might be provided by a different team member or the same team member. In this example, an appointment has a single service segment of 60 minutes and can start on the hour or the half hour.
If any appointment slot is already booked, that slot and any affected adjacent slots are not returned in the response. In this example, the team member is already booked for another appointment between the local times of 12 PM and 1 PM on November 5, 2020 (or 2020-11-05T20:00:00Z and 2020-11-05T21:00:00Z) and, hence, is unavailable for any 60-minute appointments starting at 11:30 AM or 12:00 PM. The team member would be double booked during the last half of the 11:30 AM appointment and double booked during the entire 12:00 PM appointment. Missing in the response are the two time slots starting at 2020-11-05T19:30:00Z and 2020-11-05T20:00:00Z.
In normal business operation, you need to display the available appointment slots for the customer to browse through and choose one. With the chosen appointment slot, you can proceed to create a booking.
With an available appointment slot returned from the SearchAvailability request, you have all the required information, except for the customer ID, at your disposal to call CreateBooking to create a booking. Ideally, you should already have the customer ID because you have interacted with the customer in the normal workflow of your application.
Important
You cannot use the Bookings API to book a service that has a non-zero cancellation fee set on its no_show_fee attribute.
The following cURL example creates a booking for the 60-minute service ("service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B") provided by the team member ("team_member_id": "2_uNFkqPYqV-AZB-7neN") in the location ("location_id": "SNTR5190QMFGM") starting at 1 PM local time (or 2020-11-05T21:00:00Z UTC). By extracting this information from a retrieved availability, you can successfully create an appointment, provided that you supply a valid customer ID.
If your application has seller-level permissions or if the seller allows buyers to create a booking with multiple services, you can call the CreateBooking endpoint with more than one appointment segments (as elements of the appointment_segments list) with any valid combination of services and providers.
The Bookings API requires that the Customer object referenced by the input parameter of customer_id have the phone_number attribute defined. If the specified Customer does not have phone_number specified, you get a 400 error response with the following error message:
For the seller_note attribute (or another seller-accessible attribute) to be set in the catalog, the caller must have seller-level permissions. With buyer-level permissions, any application-set value is ignored. For more information about buyer-accessible and seller-accessible booking data, see Access scopes of booking data.
If successful, the previous request returns a response similar to the following:
In this example, the caller has the seller-level permissions. Otherwise, the seller_note field would not be present in the response and the creator_type would be CUSTOMER.
Make note of the booking ID. You need to provide it later to retrieve or update this booking. Typically, you should let the customer keep a record of the booking ID and ask the customer to supply it when inquiring or changing the appointment in the future.
To retrieve an existing booking, call the RetrieveBooking endpoint with the booking ID specified as a path parameter. The following cURL example retrieves the booking created in Create a booking.
In this example, the caller has seller-level permissions. With buyer-level permissions, the result would be a subset of the above. For more information about buyer-accessible and seller-accessible booking data, see Access scopes of booking data.
To browse a collection of a seller's bookings, call the ListBookings endpoint. You can scope the retrieval to a particular service-providing team member, a particular service location, or a specific range of the service-starting time.
You define the retrieval scopes by specifying in the URL the path parameters of team_member_id, location_id, start_at_min, or start_at_max. Notice that the start-time range cannot be longer than 31 days.
When calling ListBookings, you can specify a location ID, team member ID, or range of start times. If none of these are set, their default values are used as follows:
If
team_member_idis not specified, bookings of all team members of the seller are returned.If
start_at_minis not specified, the current time becomes the earliest start time by which to retrieve bookings.If
start_at_maxis not specified, 31 days afterstart_at_minis the latest start time by which to retrieve bookings.
The following is an example showing how to list bookings with explicit specifications of a location and a start-time range.
This cURL example retrieves all available bookings with services provided at a specific business location ("SNTR5190QMFGM") of a seller and starting between a specified time range ("2021-12-01T00:00:00Z" - "2021-12-30T23:59:59Z").
The following shows an example response of two bookings that has their start_at times within the specified start_at duration:
They start between 17:00:00 UTC, December 1 (“2021-12-01T17:00:00Z”) and 17:00:00 UTC, December 15, 2021 (“2021-12-15T17:00:00Z”).
They are reserved for different customers ("SWPBCE0VRCXSQ57EEJ1PP77TKG" and "K48SGF7H116G59WZJRMYJNJKA8").
The first booking is created by the customer and the second booking is created by the seller.
They are serviced by the same team member ("2_uNFkqPYqV-AZB-7neN").
In this example, the result contains two bookings. The first booking is created by the customer because creator_type has a value of CUSTOMER. The second booking is created by the seller because the creator_type has a value of TEAM_MEMBER. The caller has seller-level permissions.
After an appointment is created, your application user can call the UpdateBooking endpoint to make certain changes. Because this endpoint supports sparse updates, you only need to specify the desired fields. Unspecified fields are not affected by the operation.
Updatable booking data varies depending on whether the caller has buyer-level or seller-level permissions. Updatable booking properties are summarized in the table in Access scopes of booking data.
For updates that modify the appointment's start time and date (start_at) with buyer-level permissions, you should call SearchAvailability
first to retrieve available appointment segments to ensure that the attempted update does not result in duplicated bookings. With seller-level permissions, this is not necessary if the seller permits double bookings.
The following cURL example moves an existing appointment's start time and date to 2021-12-17T18:00:00Z:
Your application user can call the CancelBooking endpoint to cancel an existing booking as long as all of the following criteria are met:
With seller-level permissions, the caller can cancel a booking provided that
The booking's status is
ACCEPTED.
With buyer-level permissions, the caller can cancel a booking if all of the following are true:
The customer is allowed to cancel his or her bookings, which can be created by the customer or by others. You can determine whether the customer can cancel bookings by inspecting the allow_user_cancel attribute on the BusinessBookingProfile returned from a call to the RetrieveBusinessBookingProfile endpoint.
The cancellation window has not elapsed for the booking under consideration. You can determine the duration of the cancellation window by inspecting the cancellation_window_seconds value on the business_appointment_settings attribute of BusinessBookingProfile returned from a call to the RetrieveBusinessBookingProfile endpoint. The cancellation window for a booking has elapsed if the time interval (in seconds) from the booking's
start_timeto the current time is shorter than thecancellation_window_secondsvalue.The booking's start time is not in the past.
The booking's status is
PENDINGorACCEPTED.
The following cURL example shows how to cancel a booking:
The booking_version value must match the version value of the Booking object. Otherwise, an error is returned.
If successful, the previous request to cancel the booking returns a response similar to the following:
If the caller has buyer-level permissions, the returned status is "CANCELLED_BY_CUSTOMER". Seller-specific information, such as seller_note, is not included in the response.
With buyer-permissions only, if the specified booking's start time is in the past, the caller gets the following error response:
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.