Skip to main content

Availability API

GET /availability/get/ requires min_timestamp and max_timestamp Unix timestamps.

Optional comma-separated filters:

  • services
  • providers

The response is paginated: limit, offset, and cursor select the page. See Pagination.

curl "https://example.com/wp-json/thebooking/v1/API/availability/get/?min_timestamp=1779148800&max_timestamp=1779753600&services=s_demo" \
  -H "Authorization: Bearer $TBK_API_TOKEN"

The response contains canonical slots generated from plans, durations, buffers, capacity, provider conflicts, lead times, and connected calendars.

Use the returned slot identity when calling reservations/add/. Refresh availability after a 403, because another booking or a calendar change can make the slot unavailable.

Response​

Each slot of response is a time a customer could book. The fields follow the Slot schema of the API reference; values here are examples.

{
  "status": "OK",
  "response": [
    {
      "availabilityId": "example-plan-id",
      "serviceId": "s_demo",
      "providerId": 12,
      "start": 1779190000,
      "end": 1779193600,
      "bookable": true,
      "routingMode": "manual",
      "eligibleProviderIds": [12],
      "reservationsCount": 0,
      "overrides": {}
    }
  ],
  "pagination": {
    "has_more": true,
    "next_offset": 800,
    "next_cursor": "opaque-cursor-value",
    "processed_count": 800,
    "total_candidates": 2150
  }
}

routingMode is auto when the service assigns providers automatically: then eligibleProviderIds lists the providers that could take the booking.

Pagination​

A request evaluates up to 800 candidate times of the range, then returns the slots it found and a pagination object. A wide range, or many services and providers, takes several pages. Reading only the first page gives incomplete availability.

  1. Send the request without offset and cursor.
  2. Add the slots of response to your list.
  3. If pagination.has_more is false, the list is complete.
  4. Otherwise, repeat the same request, with the same range and filters, adding offset set to pagination.next_offset and cursor set to pagination.next_cursor. Then go back to step 2.

The limit counts the candidate times evaluated, not the slots returned: a page can contain few slots, or none, and still have more pages. Do not stop at an empty page; stop only when has_more is false.

limit changes the number of candidate times per page. limit=0 evaluates the whole range in one request, which can be slow or time out on a wide range.

The cursor keeps the pages consistent with the first one. If it is missing or expired, the page starts from offset.

offset=0
cursor=""
while :; do
  page=$(curl -s "https://example.com/wp-json/thebooking/v1/API/availability/get/?min_timestamp=1779148800&max_timestamp=1779753600&offset=$offset&cursor=$cursor"     -H "Authorization: Bearer $TBK_API_TOKEN")
  echo "$page" | jq '.response[]'
  [ "$(echo "$page" | jq '.pagination.has_more')" = "true" ] || break
  offset=$(echo "$page" | jq '.pagination.next_offset')
  cursor=$(echo "$page" | jq -r '.pagination.next_cursor // ""')
done

Errors​

HTTP statusWhen
401The token is missing or not valid.
Last updated on