• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
List bookings

GET /v2/bookings

Retrieve a collection of bookings.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_READ and APPOINTMENTS_READ for the OAuth scope.


Permissions
APPOINTMENTS_READ
Try in API Explorer
Name Description
limit
integer (32-bit)

The maximum number of results per page to return in a paged response.

cursor
string

The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.

team_member_id
string

The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.

location_id
string

The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.

start_at_min
string

The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

start_at_max
string

The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after start_at_min is used.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

Response Fields

Name Description
bookings
Booking [ ]

The list of targeted bookings.

cursor
string

The pagination cursor to be used in the subsequent request to get the next page of the results. Stop retrieving the next page of the results when the cursor is not set.

Max Length 65536
errors
Error [ ]

Errors that occurred during the request.

Examples

You are viewing an old version of the API
GET /v2/bookings
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/bookings \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON
{
  "bookings": [
    {
      "id": "zkras0xv0xwswx",
      "version": 1,
      "status": "ACCEPTED",
      "created_at": "2020-10-28T15:47:41Z",
      "updated_at": "2020-10-28T15:49:25Z",
      "location_id": "LEQHH0YY8B42M",
      "customer_id": "EX2QSVGTZN4K1E5QE1CBFNVQ8M",
      "customer_note": "",
      "seller_note": "",
      "start_at": "2020-11-26T13:00:00Z",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_version": 1599775456731
        }
      ]
    }
  ],
  "errors": [],
  "cursor": null
}