Introducing Bookings API Beta

Hair salons, massage spas, and tattoo parlors all have one thing in common—they rely on appointments software to run their business. With Square Appointments, businesses can create a free online booking website that manages scheduling, staffing, inventory, customers, and payments in a single point of sale. Square Appointments simplifies day-to-day operations by enabling automated appointment reminders, saving customer profiles and purchase history, managing staff and inventory, and organizing timecards and labor reporting. Plus, businesses can get paid directly in the app through contactless payments, card on file, invoices, gift cards, or other payment methods.

Many businesses also rely on third-party booking apps to generate demand for their business and grow their revenue. Today, we’re bridging the gap by releasing Square Bookings API in beta to extend the power of Square Appointments to any third-party software. Now developers building booking apps can better serve businesses that want to manage scheduling and payments with Square while scaling their business on third-party apps. In turn, developers can attract new Square businesses to their apps and increase the number of services they offer to customers.

For large, multi-location businesses, developers can leverage Bookings API to integrate sophisticated booking functionality into custom-built websites and point-of-sale systems. Specifically, developers can create, update, retrieve, and search availability for bookings as well as list the locations, customers, services, and team members that constitute those bookings. They can also integrate features like automated reminders, individual calendar management, and customer profiles. No matter where businesses reach their customers, they can access a single, comprehensive view of their bookings and payments in Square Dashboard.

How it works

Let’s say you create a booking app for nail salons. A customer opens your app to book an appointment on Sunday afternoon with a business called Nailed It Salon. First, you have to search for bookable services using the SearchCatalogItems endpoint. Then, specify the customer requesting a booking by either creating a new customer or 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: 2020-10-28' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "start_at_range": {
          "start_at": "2020-12-20T12:00:00Z",
          "end_at": "2020-12-20T17:00:00Z"
        },
        "location_id": "SNTR5190QMFGM",
        "segment_filters": [
          {
            "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
            "team_member_id_filter": {
              "any": [
                "2_uNFkqPYqV-AZB-7neN"
              ]
            }
          }
        ]
      }
    }
  }'

In response, you’ll get a list of time slots available for the customer to book. Using the Customer ID and available time slots, you can now call the CreateBooking endpoint.

curl https://connect.squareupsandbox.com/v2/bookings \
  -X POST \
  -H 'Square-Version: 2020-10-28' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H "Accept: application/json" \
  -d '{
    "idempotency_key": "33a530f5-caab-4a6b-8edc-4e18cce5ca29",
    "booking": {
      "location_id": "SNTR5190QMFGM",
      "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
      "customer_note": "Gel manicure",
      "start_at": "2020-12-20T12:00:00Z",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN"
        }
      ]
    }
  }'

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). That’s all—the customer is scheduled and ready to go.

Get started

Bookings API is available in beta to developers in the U.S., Canada, and Australia, and can be accessed publicly in sandbox and in production. Sellers can use Square Appointments for free as an individual with one calendar and pay 2.6% + 10¢ per card-present transaction. Additional staff calendars require a monthly subscription with a 2.5% + 10¢ card-present transaction fee.

Check out the Bookings API beta documentation to learn how to get started and access the API reference docs. 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.