Partner API V1
Availability
Push current and future absolute inventory from your channel manager to Bolt. Reservation notifications are handled by the companion event and webhook endpoints.
/connections/{connectionId}/availabilityFull URL: https://www.boltlabs.app/partner-api/v1/connections/<CONNECTION_ID>/availability
curl --request PUT \
--url "$BASE_URL/connections/<CONNECTION_ID>/availability" \
--header "Authorization: Bearer <ACCESS_TOKEN>" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: availability:hotel-456:batch-20260805-001" \
--data '{
"updates": [
{
"external_room_id": "<EXTERNAL_ROOM_ID>",
"date": "2026-08-20",
"available": 3
},
{
"external_room_id": "<EXTERNAL_ROOM_ID>",
"from": "2026-08-21",
"to": "2026-08-25",
"available": 0
}
]
}'| Header | Value | Purpose |
|---|---|---|
Authorization | Bearer <ACCESS_TOKEN> | Authenticates the approved channel-manager partner. |
Content-Type | application/json | Identifies the JSON request body. |
Idempotency-Key | A unique key of at most 255 characters | Makes uncertain retries safe and is required on this endpoint. |
Use date when one room receives one inventory value for one property-local calendar date.
{
"updates": [
{
"external_room_id": "<EXTERNAL_ROOM_ID>",
"date": "2026-08-20",
"available": 3
}
]
}Use from and to together to apply the same value to every date in an inclusive range. The example below expands to six room-date entries. V1 does not support a weekday filter.
{
"updates": [
{
"external_room_id": "<EXTERNAL_ROOM_ID>",
"from": "2026-08-20",
"to": "2026-08-25",
"available": 0
}
]
}available: 0 closes inventory
available: 0 means the mapped room cannot be booked on that date. V1 does not expose a separate stop-sell or closed-to-arrival field.| Field | Type | Required | Rules |
|---|---|---|---|
external_room_id | string | Yes | Must match a room mapping saved on this connection. |
date | YYYY-MM-DD string | For an individual date | Cannot be combined with from or to. |
from | YYYY-MM-DD string | For a range | Must be supplied with to and cannot be after it. |
to | YYYY-MM-DD string | For a range | Inclusive final date; must be supplied with from. |
available | integer | Yes | Must be 0 or greater and cannot exceed the Bolt room's total_units value. |
- Dates use the connected property's IANA timezone and must be real calendar dates in
YYYY-MM-DDformat. - The earliest accepted date is the current date in the property's timezone. Past dates are rejected.
- The latest accepted date is 730 days after the current property-local date.
- One request can expand to at most 5,000 room-date entries. Each date in an inclusive range counts as one expanded entry. A larger request is rejected with HTTP 413
TOO_MANY_UPDATES. - Availability must be a non-negative integer no greater than the mapped Bolt room's
total_units. - A mapped room that still has a conflicting iCal source is rejected with
ROOM_AVAILABILITY_SOURCE_CONFLICTuntil the property resolves that source in Bolt.
Bolt processes valid entries even when other entries in the same batch fail. This example accepts the first two individual dates and rejects the third because its external room ID has no mapping.
{
"updates": [
{
"external_room_id": "CM_ROOM_1001",
"date": "2026-08-20",
"available": 3
},
{
"external_room_id": "CM_ROOM_1001",
"date": "2026-08-21",
"available": 2
},
{
"external_room_id": "CM_ROOM_999",
"date": "2026-08-22",
"available": 1
}
]
}{
"request_id": "req_example",
"status": "PARTIALLY_PROCESSED",
"accepted": 2,
"rejected": 1,
"errors": [
{
"index": 2,
"code": "ROOM_MAPPING_NOT_FOUND",
"message": "No room mapping exists for CM_ROOM_999."
}
]
}How partial counts and indexes work
accepted counts successfully applied expanded room-date entries. rejected counts expanded room-date entries when Bolt can expand a valid date or range. A structurally invalid update, such as a missing or invalid date or availability value, counts as one rejected input because it cannot be expanded. Every error's index points to the original zero-based updates array index.| Status | Meaning |
|---|---|
PROCESSED | Every expanded room-date entry was accepted. |
PARTIALLY_PROCESSED | At least one expanded room-date entry succeeded and at least one was rejected. |
REJECTED | No room-date entry was accepted. Inspect errors before creating a corrected batch. |
Bolt updates last_availability_sync_at when at least one expanded room-date entry succeeds. A fully rejected batch does not advance it. Read the connection to reconcile the timestamp after a successful or partially successful request.
Only the availability endpoint requires an idempotency key in V1. The uniqueness scope is the authenticated partner, connection, and exact key. A useful format is availability:<external-property-id>:<batch-id>.
| Situation | Bolt behavior | What to do |
|---|---|---|
| Same key and same canonical JSON payload after the first request completes | Replays the original response without applying the batch again. | Treat the replay as the result of the original request. |
| Same key with a materially different payload | HTTP 409 IDEMPOTENCY_KEY_REUSED | Generate a new key for the new logical batch. |
| Same key while the original request is still processing | HTTP 409 IDEMPOTENCY_REQUEST_IN_PROGRESS | Wait, then retry the same payload with the same key. |
| The client times out before receiving a response | The original request may still have succeeded. | Retry the same canonical JSON payload with the same key. |
Keys do not expire automatically in V1
The default availability limit is 120 requests per authenticated partner per minute and is configurable by Bolt. Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset. HTTP 429 responses also include retry-after. Back off until the stated reset rather than increasing concurrency.
- Send changed dates in bounded batches instead of repeatedly replacing the complete future calendar; every
availablevalue is still absolute. - Batch by connection and room, but stay within the 5,000 expanded-entry limit.
- Send
available: 0immediately when inventory closes. - Avoid concurrent requests for overlapping room-date entries. Preserve ordering in your own queue.
- Periodically reconcile future dates in bounded batches. Coordinate the cadence of any full-calendar refresh with Bolt during onboarding.
- Persist the Bolt connection ID, stable external room IDs, mappings, request key, and response request ID needed to investigate a sync.
Availability remains absolute