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

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

In the following sections, you learn how to perform the back-end operations using cURL commands.

List business locations Permalink Get a link to this section

When enabling bookings for a service, the seller decides 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 ID of a business location of a Square seller. To determine the location ID, you can call the ListLocations endpoint of the Locations API and present the result for the user to select one.

The following example shows how to call the ListLocations endpoint in a cURL command:

Request: list business locations Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  https://connect.squareupsandbox.com/v2/locations

Response: list business locations Permalink Get a link to this section

{
  "locations": [
    {
      "id": "EZDZF5AVRBXY4",
      "name": "Default Test Account",
      "address": {
        "address_line_1": "1600 Pennsylvania Ave NW",
        "locality": "Washington",
        "administrative_district_level_1": "DC",
        "postal_code": "20500",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING"
      ],
      "status": "ACTIVE",
      "created_at": "2020-04-15T00:26:32Z",
      "merchant_id": "AM442MXDT6705",
      "country": "US",
      "language_code": "en-US",
      "currency": "USD",
      "phone_number": "+1 206-222-1111",
      "business_name": "Mr. Mo's Hair",
      "type": "PHYSICAL",
      "business_hours": {
        "periods": [
          {
            "day_of_week": "MON",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          },
          {
            "day_of_week": "TUE",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          },
          {
            "day_of_week": "WED",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          },
          {
            "day_of_week": "THU",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          },
          {
            "day_of_week": "FRI",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          }
        ]
      },
      "business_email": "sandbox-seller@squareup.com",
      "coordinates": {
        "latitude": 38.897675,
        "longitude": -77.036547
      },
      "mcc": "7299"
    }
  ]
}

In this example, the seller runs the business in one location only. In addition to the business address, you can also 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.

List booking profiles of team members Permalink Get a link to this section

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:

Request: List booking profiles of team members Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H "Accept: application/json" \
  https://connect.squareupsandbox.com/v2/bookings/team-member-booking-profiles

Response: list booking profiles of team members Permalink Get a link to this section

{
  "team_member_booking_profiles": [
    {
      "team_member_id": "pRNYL8gtKDFeFUtvC_Tz",
      "display_name": "Sandbox Seller",
      "is_bookable": true
    }
  ],
  "errors": []
}

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.

Search for bookable services Permalink Get a link to this section

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:

Request: Search for available services Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -X POST https://connect.squareupsandbox.com/v2/catalog/search-catalog-items \
  -d '{
    "product_types": [
      "APPOINTMENTS_SERVICE"
    ]
  }’

Response: Search for an appointment service Permalink Get a link to this section

{
  "items": [
    {
      "type": "ITEM",
      "id": "GU3K6H36IETW5BJXNUVQIITT",
      "updated_at": "2020-10-26T05:03:12.977Z",
      "version": 1603688592977,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Hand Clean",
        "description": "House cleaning service",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "YW337JZR267JIALGVE5WWZR7",
            "updated_at": "2020-10-26T05:03:12.977Z",
            "version": 1603688592977,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "GU3K6H36IETW5BJXNUVQIITT",
              "name": "Regular",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 8000,
                "currency": "USD"
              },
              "service_duration": 7200000,
              "available_for_booking": true,
              "no_show_fee": {
                "amount": 2500,
                "currency": "USD"
              },
              "transition_time": 0
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "KRV4AOIPRWAMSBPBSSU2A2UW",
            "updated_at": "2020-10-26T05:03:12.977Z",
            "version": 1603688592977,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "GU3K6H36IETW5BJXNUVQIITT",
              "name": "Power Clean",
              "ordinal": 2,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 10000,
                "currency": "USD"
              },
              "service_duration": 9000000,
              "available_for_booking": true,
              "no_show_fee": {
                "amount": 2500,
                "currency": "USD"
              }
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE",
        "skip_modifier_screen": false
      }
    },
    {
      "type": "ITEM",
      "id": "EC66KHZQFDXS2CUMBELGF2YK",
      "updated_at": "2020-10-26T05:03:12.977Z",
      "version": 1603688592977,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Mr. Mo's Hair",
        "description": "Hair styling for men and women",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "RCTL5QBJIWUUDWGOX4YWOSNR",
            "updated_at": "2020-10-26T05:03:12.977Z",
            "version": 1603688592977,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EC66KHZQFDXS2CUMBELGF2YK",
              "name": "Men's hair cut",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "service_duration": 1800000,
              "transition_time": 0
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "RHMBHQBSCELBY6LUR75OCK5H",
            "updated_at": "2020-10-26T05:03:12.977Z",
            "version": 1603688592977,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EC66KHZQFDXS2CUMBELGF2YK",
              "name": "Women's hair styling",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 10000,
                "currency": "USD"
              },
              "service_duration": 7200000
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE"
      }
    }
  ],
  "matched_variation_ids": [
    "YW337JZR267JIALGVE5WWZR7",
    "KRV4AOIPRWAMSBPBSSU2A2UW",
    "RCTL5QBJIWUUDWGOX4YWOSNR",
    "RHMBHQBSCELBY6LUR75OCK5H"
  ]
}

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 one of two ways:

  • Using the Catalog API, you can call the UpsertCatalogObject or BatchUpsertCatalogObjects endpoint to create a service variation and set the available_for_booking attribute to true.

  • Using the Square Seller Dashboard, you can create a bookable service variation by enabling the Bookable by Customers Online option for the newly created service.

bookings-create-bookable-service-on-dashboard

Specify a customer for a booking Permalink Get a link to this section

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.

Find the ID of a new customer Permalink Get a link to this section

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:

Request: Create a new customer Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -X POST https://connect.squareupsandbox.com/v2/customers \
  -d '{
    "given_name": "John",
    "family_name": "Doe",
    "email_address": "john.doe@acme.com"
    "idempotency_key": "49a9a126-1f13-4c93-a51b-1559322ce385"
  }’

Response: Create a new customer Permalink Get a link to this section

{
  "customer": {
    "id": "5XSG36ZZ4WTF32XPGK0A7NZNMC",
    "created_at": "2020-11-02T06:06:13.921Z",
    "updated_at": "2020-11-02T06:06:13Z",
    "given_name": "John",
    "family_name": "Doe",
    "email_address": "john.doe@acme.com",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY"
  }
}

Make note of the customer ID from the response. You need to provide it to create a booking afterwards.

Find the ID of an existing customer Permalink Get a link to this section

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 joel@acme.com:

Request: Search for customer by exact email address Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "email_address": {
          "exact": "joel@acme.com"
        }
      }
    }
  }'

Response: Search for customer by exact email address Permalink Get a link to this section

{
  "customers": [
    {
      "id": "W3T65DYFQCXJXAW72Y677P5SW8",
      "created_at": "2020-07-24T19:49:02.070Z",
      "updated_at": "2020-07-24T19:49:02Z",
      "given_name": "Joel",
      "family_name": "Carpenter",
      "email_address": "joel@acme.com",
      "address": {
        "address_line_1": "1234 major street E",
        "administrative_district_level_1": "WA",
        "postal_code": "98101",
        "country": "US"
      },
      "phone_number": "2061112222",
      "note": "not so private note",
      "company_name": "ACME",
      "preferences": {
        "email_unsubscribed": false
      },
      "groups": [
        {
          "id": "AM442MXDT6705.REACHABLE",
          "name": "Reachable"
        },
        {
          "id": "gv2:Q4N92Z69694EDDNFYFC2D2Q5KG",
          "name": "Email Subscribers"
        }
      ],
      "creation_source": "THIRD_PARTY",
      "birthday": "2001-01-01T00:00:00-00:00",
      "segment_ids": [
        "AM442MXDT6705.REACHABLE",
        "gv2:Q4N92Z69694EDDNFYFC2D2Q5KG"
      ]
    }
  ]
}

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.

Retrieve a business booking profile Permalink Get a link to this section

To determine how a Square seller accepts and manages bookings, you can call the RetrieveBusinessBookingProfile endpoint of the Bookings API to fetch 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 API: Walkthrough.

The following cURL example retrieves a business booking profile:

Request: retrieve a business booking profile Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H "Accept: application/json" \
  https://connect.squareupsandbox.com/v2/bookings/business-booking-profile

Response: retrieve a business booking profile Permalink Get a link to this section

{
  "business_booking_profile": {
    "seller_id": "AM442MXDT6705",
    "created_at": "2020-10-22T16:38:24Z",
    "booking_enabled": true,
    "customer_timezone_choice": "CUSTOMER_CHOICE",
    "booking_policy": "ACCEPT_ALL",
    "allow_user_cancel": true,
    "business_appointment_settings": {
      "location_types": [
        "BUSINESS_LOCATION"
      ],
      "alignment_time": "HALF_HOURLY",
      "min_booking_lead_time_seconds": 0,
      "max_booking_lead_time_seconds": 31536000,
      "any_team_member_booking_enabled": true,
      "multiple_service_booking_enabled": true,
      "cancellation_fee_money": {
        "currency": "USD"
      },
      "cancellation_policy": "CUSTOM_POLICY",
      "skip_booking_flow_staff_selection": false
    }
  },
  "errors": []
}

By inspecting the returned business booking profile, you find out the booking policy for the business, concerning whether the seller accepts booking requests automatically, whether multiple bookings are allowed, the booking's lead time, whether the customer can cancel a booking, whether the customer can choose a team member, and other options.

Search for available slots Permalink Get a link to this section

An available slot, also referred to as an availability, refers to 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 fetch availabilities for the service provided by specified team members between 9 AM November 5, 2020, and 9 AM November 6, 2020 (US west coast standard time).

In the request body, the stated local times are converted to the corresponding UTC times (2020-11-05T17:00:00Z and 2020-11-06T17: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 at least 24 hours long and at most 31 days.

Request: search availability Permalink Get a link to this section

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-11-05T17:00:00Z",
          "end_at": "2020-11-06T17:00:00Z"
        },
        "location_id": "SNTR5190QMFGM",
        "segment_filters": [
          {
            "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
            "team_member_id_filter": {
              "any": [
                "2_uNFkqPYqV-AZB-7neN"
              ]
            }
          }
        ]
      }
    }
  }'

For the SearchAvailabily 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:

{
  "start_at_range": {
    "start_at": "2020-11-05T16:00:00Z",
    "end_at": "2020-11-06T16:59:59Z"
  }  
}

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:

{
  "start_at_range": {
    "start_at": "2020-11-05T17:00:00Z",
    "end_at": "2020-12-06T17:00:01Z"
  }  
}

Response: Permalink Get a link to this section

{
  "availabilities": [
    {
      "start_at": "2020-11-05T17:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T17:30:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T18:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T18:30:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T19:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T21:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T21:30:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T22:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T22:30:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T23:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-05T23:30:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-06T00:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    },
    {
      "start_at": "2020-11-06T17:00:00Z",
      "location_id": "SNTR5190QMFGM",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN",
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016
        }
      ]
    }
  ],
  "errors": []
}

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 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 in the last half of the 11:30 AM appointment and in the whole of the 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.

Create a booking Permalink Get a link to this section

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.

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 are guaranteed a successful creation of an appointment, provided that you supply a valid customer ID.

Request: create a booking Permalink Get a link to this section

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": "Window seat, please",
      "start_at": "2020-11-05T21:00:00Z",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
          "service_variation_version": 1604352990016,
          "team_member_id": "2_uNFkqPYqV-AZB-7neN"
        }
      ]
    }
  }'

Response: create a booking Permalink Get a link to this section

If the previous request succeeds, the response is similar to the following:

{
  "booking": {
    "id": "09yfm194f876xg",
    "version": 0,
    "status": "ACCEPTED",
    "created_at": "2020-11-03T04:11:37Z",
    "updated_at": "2020-11-03T04:11:37Z",
    "location_id": "SNTR5190QMFGM",
    "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
    "customer_note": "Window seat, please",
    "seller_note": "",
    "start_at": "2020-11-05T21:00:00Z",
    "appointment_segments": [
      {
        "duration_minutes": 60,
        "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
        "team_member_id": "2_uNFkqPYqV-AZB-7neN",
        "service_variation_version": 1604352990016
      }
    ]
  },
  "errors": []
}

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.

Retrieve a booking Permalink Get a link to this section

To retrieve an existing booking, call the RetrieveBooking endpoint with the booking ID.

The following cURL example retrieves the booking created in Create a booking section:

Request: retrieve a booking Permalink Get a link to this section

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H "Accept: application/json" \
  -X GET https://connect.squareupsandbox.com/v2/bookings/09yfm194f876xg

Response: retrieve a booking Permalink Get a link to this section

{
  "booking": {
    "id": "09yfm194f876xg",
    "version": 0,
    "status": "ACCEPTED",
    "created_at": "2020-11-03T04:11:37Z",
    "updated_at": "2020-11-03T04:11:37Z",
    "location_id": "SNTR5190QMFGM",
    "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
    "customer_note": "Window seat, please",
    "seller_note": "",
    "start_at": "2020-11-05T21:00:00Z",
    "appointment_segments": [
      {
        "duration_minutes": 60,
        "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
        "team_member_id": "2_uNFkqPYqV-AZB-7neN",
        "service_variation_version": 1604352990016
      }
    ]
  },
  "errors": []
}

Update a booking Permalink Get a link to this section

After an appointment is created, you can call the UpdateBooking endpoint to make certain changes. Currently supported updates are

  • The customer can postpone the appointment.

  • The customer can supply a new customer note.

For updates that modify the appointment's start time and date (start_at), you should call SearchAvailability first to fetch available appointment segments to ensure that the attempt results in a valid update.

Request: update a booking to a new start time and date Permalink Get a link to this section

The following cURL example moves an existing appointment's start time and date to 2020-11-06T21:00:00Z:

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X PUT https://connect.squareupsandbox.com/v2/bookings/09yfm194f876xg \
  -d '{
    "booking": {
      "start_at": "2020-11-06T21:00:00Z"
    }
  }'

Response: update a booking to a new start time and date Permalink Get a link to this section

{
  "booking": {
    "id": "09yfm194f876xg",
    "version": 1,
    "status": "ACCEPTED",
    "created_at": "2020-11-03T04:11:37Z",
    "updated_at": "2020-11-03T05:11:39Z",
    "location_id": "SNTR5190QMFGM",
    "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
    "customer_note": "",
    "seller_note": "",
    "start_at": "2020-11-06T21:00:00Z",
    "appointment_segments": [
      {
        "duration_minutes": 60,
        "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
        "team_member_id": "2_uNFkqPYqV-AZB-7neN",
        "service_variation_version": 1604352990016
      }
    ]
  },
  "errors": []
}