---
title: "Check Booking Availability"
method: POST
path: "/booking/availability"
tags: ["Booking"]
---

# Check Booking Availability

`POST /booking/availability`

## Request

- Base URL: `https://api.smartroutes.io/v2`
- URL: `https://api.smartroutes.io/v2/booking/availability`
- Auth: none declared

Checks whether one more order could be fitted in on a given date before you accept the booking. Nothing is created or reserved, and the response is just `{"booking": {"available": true|false}}`.

Availability is worked out by running the routing engine on the spot. It takes every order already scheduled for `date` in this depot, adds the order you describe, and plans the whole day from scratch on either the vehicles you list in `vehicles` or, if you leave that out, all active vehicles. `available` is `true` only if every stop, both the existing ones and the new one, fits into a route. Your existing plans and routes for that day are not used. So a day that is already overbooked returns `false` even when the new order itself would fit.

- The order's location comes from `delivery_*` fields for `delivery` orders and from `pickup_*` fields otherwise. If you don't send both `lat` and `lng`, the address and postcode are geocoded first. If geocoding fails you get `400 GEOCODING_FAILED`.
- Capacity `id`s that don't belong to the depot are ignored, and so are vehicle `id`s that don't belong to it. Look up valid capacity ids with `GET /capacities`.
- If any vehicle used for the check has no shift on that weekday, the request fails with `400 INVALID_INPUT`.

The call waits for the routing engine to finish, so it is much slower than a normal read. It also has a stricter rate limit of 5 / min (see [Rate Limits](#section/Getting-started/Rate-Limits)), so call it when a customer is booking, not in bulk.

## Request body

- object: Request body for checking availability for bookings.
  - `date` string, date, required: Requested date for order collection/delivery.
  - `order` object, required: Location and other routing information for booking availability check.
    - `type` 'delivery' | 'pickup', required
    - `delivery_address` string
    - `delivery_country_code` string: Two letter country code, e.g. 'IE'
    - `delivery_postcode` string
    - `delivery_lat` number
    - `delivery_lng` number
    - `delivery_duration` number
    - `pickup_address` string
    - `pickup_country_code` string: Two letter country code, e.g. 'IE'
    - `pickup_postcode` string
    - `pickup_duration` number
    - `pickup_lat` number
    - `pickup_lng` number
    - `capacities` object[]: List of capacities for the order.
      - `id` integer, required: Id of capacity (e.g., 1, 2).
      - `capacity` number, float, required: Capacity value for the specified type.
  - `vehicles` unknown[]: Array of vehicles to attempt to route the order with. If no vehicles provided, active vehicles will be used.
    - unknown

## Response `200`

Successful response

- BookingAvailabilityResponse
  - `booking` object, required
    - `available` boolean, required

## Other responses

- `400`: Invalid input. The request body failed validation.
- `403`: Forbidden. Returned for rate-limit exhaustion (`name = FORBIDDEN`, with `details.retry_after_seconds` and `Retry-After` header) and permission gate failures (`name = PERMISSION`). Inspect `name` to disambiguate. Send `x-sr-api-features: rate-limit-429` to receive `429 RATE_LIMIT_EXCEEDED` for the rate-limit case instead, leaving `403` to mean permission failures only — see [API Features](#section/Getting-started/API-Features).
- `429`: Rate limit exceeded (`name = RATE_LIMIT_EXCEEDED`). **Only returned to callers that opt in** with the `x-sr-api-features: rate-limit-429` request header; without it the same condition returns `403` with `name = FORBIDDEN` and an otherwise identical body. See [API Features](#section/Getting-started/API-Features).
- `500`: An unexpected server error occurred. The body carries only `name` and `description`: internal details are never returned.

---

[API](https://skmtc.dev/smartroutes/apis/smartroutes-api.md) · [All operations](https://skmtc.dev/smartroutes/apis/smartroutes-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smartroutes/apis/smartroutes-api/revisions/a7ea507afac7?raw)