Build With Bookings API, Now Generally Available

In December 2020 we released Bookings API in beta to extend the capabilities of Square Appointments — our point of sale for scheduling, bookings, and payments — to any third-party software. Since the beta launch, we’ve been close to the developer community, gathering meaningful feedback and working hard to deliver a feature-rich API that lives up to Square standards.

On May 12, 2022, we launched Bookings API to general availability, where developers in the United States, the United Kingdom, Canada, Australia, Spain, and Japan can access the API. Bookings API brings new access to key features with seller-level permissions, in addition to the existing buyer-level permissions, such as reading, writing, and receiving webhook data from Square Appointments. The API also now supports ListBookings endpoints so developers can return a collection of seller bookings.

With Bookings API, developers can now enable Square sellers to manage all customer bookings and information to deliver a personalized buyer experience based on booking details from Square Appointments, all with their application. The API seamlessly integrates with any third-party applications, including custom websites, making it easy for sellers to deliver an on-brand booking experience and build custom back-of-the-house tools to run and scale their businesses efficiently.

Bookings API is deeply integrated with the Square developers ecosystem, meaning that developers and third-party platforms can reduce development cost, quickly enrich their application’s experience, and spend less time building and maintaining bookings systems. It also means that developers can attract new Square sellers and increase the number of services they offer to customers.

Groupon, a global eCommerce marketplace connecting buyers with local merchants, was among the first Square Partners to unlock a seamless booking integration with Bookings API. With this integration Groupon can expand their bookable inventory and improve the customer journey, making the experience more seamless from purchase to first visit.

“We’re laser-focused on improving the merchant experience, and by teaming up with Square, we are creating a new ecosystem that will make it easier than ever for the local businesses that use Square to launch new campaigns on Groupon”

Brian Fields, Groupon chief commercial officer

How Bookings API works

You can use the Bookings API to create appointment-based applications that allow a Square seller’s customer to book an appointment for a particular service provided by the seller or one of the seller’s team members.

Let’s say you build a custom website for a Square seller who owns a hair salon. The seller has granted your application seller-level permissions, so you have full visibility into the seller’s calendar and full control of the seller’'s bookings.

When a customer visits your website and wants to book an appointment at the hair salon, you search for bookable services using the SearchCatalogItems endpoint. Then, specify the customer requesting a booking either by creating a new customer or by calling the SearchCustomers endpoint. Next, search for available slots by calling the SearchAvailability endpoint of the Bookings API, as shown below.

curl https://connect.squareupsandbox.com/v2/bookings/availability/search \
 -X POST \
 -H 'Square-Version: 2022-05-12' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -d '{
   "query": {
     "filter": {
       "start_at_range": {
         "start_at": "2020-12-01T17:00:00Z",
         "end_at": "2020-12-02T17:00:00Z"
       },
       "location_id": "SNTR5190QMFGM",
       "segment_filters": [
         {
           "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
           "team_member_id_filter": {
             "any": [
               "2_uNFkqPYqV-AZB-7neN"
             ]
           }
         }
       ]
     }
   }
 }'

In the SearchAvailability response, you get a list of time slots available for the customer to book. Using the Customer ID and the available time slots, you can now call the CreateBooking endpoint. This dispatches a booking.created event.

curl https://connect.squareupsandbox.com/v2/bookings \
 -X POST \
 -H 'Square-Version: 2022-05-12' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -d '{
   "booking": {
     "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
     "appointment_segments": [
       {
         "duration_minutes": 60,
         "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
         "service_variation_version": 1604352990016,
         "team_member_id": "2_uNFkqPYqV-AZB-7neN"
       }
     ],
     "customer_note": "Window seat, please",
     "location_id": "SNTR5190QMFGM",
     "location_type": "BUSINESS_LOCATION",
     "seller_note": "Complementary VIP service",
     "start_at": "2021-12-16T17:00:00Z"
   }
 }'

Once the booking has been created, a Booking ID is generated that can be used to retrieve the booking (via the RetrieveBooking endpoint) or update the booking (via the UpdateBooking endpoint). If a booking is updated, a booking.updated event is dispatched.

Your application can use webhooks to receive event notifications when a booking is created or updated and respond according to your needs. For example, when a booking is created, you can add it to a list of upcoming appointments for the customer. When a booking is updated, you can notify the service provider of the changes. Since the application has seller-level permissions, you can receive event notifications for any booking that’s visible in the API.

Get started

We’re excited to see what you'll build with Bookings API. You can check out the Bookings API documentation to learn more. To learn more about the Square developer platform, visit https://squareup.com/developers.

Need help?

If you need help with implementation or have any questions, visit our Square Developer Forums or Build with Square Slack channel, or contact our Developer Support team.