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.

PUT/connections/{connectionId}/availability
Applies valid updates to an ACTIVE connection after resolving each external room ID through the saved room mappings.

Full URL: https://www.boltlabs.app/partner-api/v1/connections/<CONNECTION_ID>/availability

Request
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
      }
    ]
  }'

Required headers

HeaderValuePurpose
AuthorizationBearer <ACCESS_TOKEN>Authenticates the approved channel-manager partner.
Content-Typeapplication/jsonIdentifies the JSON request body.
Idempotency-KeyA unique key of at most 255 charactersMakes uncertain retries safe and is required on this endpoint.

Individual-date updates

Use date when one room receives one inventory value for one property-local calendar date.

Request body
{
  "updates": [
    {
      "external_room_id": "<EXTERNAL_ROOM_ID>",
      "date": "2026-08-20",
      "available": 3
    }
  ]
}

Inclusive date ranges

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.

Request body
{
  "updates": [
    {
      "external_room_id": "<EXTERNAL_ROOM_ID>",
      "from": "2026-08-20",
      "to": "2026-08-25",
      "available": 0
    }
  ]
}

available: 0 closes inventory

Sending 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.

Update fields

FieldTypeRequiredRules
external_room_idstringYesMust match a room mapping saved on this connection.
dateYYYY-MM-DD stringFor an individual dateCannot be combined with from or to.
fromYYYY-MM-DD stringFor a rangeMust be supplied with to and cannot be after it.
toYYYY-MM-DD stringFor a rangeInclusive final date; must be supplied with from.
availableintegerYesMust be 0 or greater and cannot exceed the Bolt room's total_units value.

Date and batch limits

  • Dates use the connected property's IANA timezone and must be real calendar dates in YYYY-MM-DD format.
  • 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_CONFLICT until the property resolves that source in Bolt.

Partial success

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.

Request body
{
  "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
    }
  ]
}
200 response
{
  "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.
StatusMeaning
PROCESSEDEvery expanded room-date entry was accepted.
PARTIALLY_PROCESSEDAt least one expanded room-date entry succeeded and at least one was rejected.
REJECTEDNo room-date entry was accepted. Inspect errors before creating a corrected batch.

Last-sync timestamp

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.

Idempotency

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>.

SituationBolt behaviorWhat to do
Same key and same canonical JSON payload after the first request completesReplays the original response without applying the batch again.Treat the replay as the result of the original request.
Same key with a materially different payloadHTTP 409 IDEMPOTENCY_KEY_REUSEDGenerate a new key for the new logical batch.
Same key while the original request is still processingHTTP 409 IDEMPOTENCY_REQUEST_IN_PROGRESSWait, then retry the same payload with the same key.
The client times out before receiving a responseThe original request may still have succeeded.Retry the same canonical JSON payload with the same key.

Keys do not expire automatically in V1

Bolt retains availability idempotency records without an automatic V1 expiry. Never recycle a key for another logical batch, even after a long interval.

Rate limit

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.

Synchronization guidance

  • 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: 0 immediately 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

Availability flows from the channel manager to Bolt as absolute room/date values. Confirmed Bolt reservations are notified through reservation events; after processing an event, send the revised absolute value here and acknowledge the event.