Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Bookings

  • List bookings

  • Create booking

  • Search availability

  • Bulk retrieve bookings

  • Retrieve business booking profile

  • List location booking profiles

  • Retrieve location booking profile

  • List team member booking profiles

  • Bulk retrieve team member booking profiles

  • Retrieve team member booking profile

  • Retrieve booking

  • Update booking

  • Cancel booking

  • Webhooks

  • booking.created

  • booking.updated

<- Bookings API

Bookings API

All versions ->

Search availability

POST

 /v2/bookings/availability/search

Searches for availabilities for booking.

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
Link to section

Request body

Example code

Link to section

query

Required

Query conditions used to filter buyer-accessible booking availabilities.

Link to section

Response fields

Link to section

availabilities

List of appointment slots available for booking.

Link to section

errors

Errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/bookings/availability/search
curl https://connect.squareup.com/v2/bookings/availability/search \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "query": { "filter": { "start_at_range": { "start_at": "2020-11-26T13:00:00Z", "end_at": "2020-11-27T13:00:00Z" }, "location_id": "LEQHH0YY8B42M", "segment_filters": [ { "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "team_member_id_filter": { "any": [ "TMXUrsBWWcHTt79t", "TMaJcbiRqPIGZuS9" ] } } ] } } }'

Response JSON

{ "availabilities": [ { "start_at": "2020-11-26T13:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T13:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T14:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T14:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T15:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T15:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-26T16:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T09:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T09:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T10:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T10:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T11:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T11:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T12:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T12:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T13:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T13:30:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] }, { "start_at": "2020-11-27T14:00:00Z", "location_id": "LEQHH0YY8B42M", "appointment_segments": [ { "duration_minutes": 60, "team_member_id": "TMaJcbiRqPIGZuS9", "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "service_variation_version": 1599775456731 } ] } ], "errors": [] }