Partner API V1

Testing

Validate the connection lifecycle, mapping, reservation recovery, webhook processing, availability, and calendar result before synchronizing a live property. Bolt provisions test access manually in V1.

There is no self-service sandbox

Bolt provides credentials and designated test property data during partner onboarding. All examples use the production Partner API base URL, so coordinate the test connection with Bolt and never point these requests at an unintended live property.

End-to-end test plan

  1. 1

    Obtain test partner credentials

    Receive a manually issued client ID and client secret from Bolt through the approved onboarding channel.

  2. 2

    Create a test property connection

    Have the designated Bolt test property select your channel manager so Bolt creates a PENDING request.

  3. 3

    Fetch the pending connection

    Authenticate and confirm that only the partner's requested test property is listed.

  4. 4

    Accept the matched property

    Supply a stable external property ID and verify that the connection becomes ACTIVE.

  5. 5

    Fetch Bolt rooms

    Confirm the expected bookable room types, total units, and current mapping indicators.

  6. 6

    Save room mappings

    Map each selected Bolt room ID to a unique stable external room ID.

  7. 7

    Send positive availability

    Set a future property-local date to a value between 1 and the room's total inventory.

  8. 8

    Close a date

    Send available: 0 and confirm that Bolt no longer offers that room-date.

  9. 9

    Test a partial failure

    Mix a mapped room with an unmapped external room ID and verify accepted, rejected, errors, and index values.

  10. 10

    Test idempotent replay

    Repeat the same payload and key, then verify that Bolt replays the original response without a second mutation.

  11. 11

    Test a disconnected connection

    Have the Bolt test property disconnect, then verify that room and availability writes return CONNECTION_NOT_ACTIVE.

  12. 12

    Confirm the Bolt calendar

    Inspect the designated property in Bolt and compare every tested room-date value and the last-sync timestamp.

Full curl walkthrough

Replace every placeholder and change the example dates to future dates in the test property's timezone. Run each numbered command in order.

Shell walkthrough
BASE_URL="https://www.boltlabs.app/partner-api/v1"
CLIENT_ID="<CLIENT_ID>"
CLIENT_SECRET="<CLIENT_SECRET>"
ACCESS_TOKEN="<ACCESS_TOKEN>"
CONNECTION_ID="<CONNECTION_ID>"
BOLT_ROOM_ID="<BOLT_ROOM_ID>"
EXTERNAL_ROOM_ID="<EXTERNAL_ROOM_ID>"
EXTERNAL_PROPERTY_ID="<EXTERNAL_PROPERTY_ID>"

# Use future dates in the test property's timezone.
SINGLE_DATE="2026-08-20"
RANGE_FROM="2026-08-21"
RANGE_TO="2026-08-25"
INDIVIDUAL_KEY="availability:$EXTERNAL_PROPERTY_ID:single-001"
RANGE_KEY="availability:$EXTERNAL_PROPERTY_ID:range-001"

# 1. Authenticate. Copy access_token from the response into ACCESS_TOKEN.
curl --request POST \
  --url "$BASE_URL/auth/token" \
  --header "Content-Type: application/json" \
  --data "{
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET"
  }"

# 2. List pending connections. Copy connection_id into CONNECTION_ID.
curl --request GET \
  --url "$BASE_URL/connections?status=PENDING&limit=100" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

# 3. Accept the matched property.
curl --request POST \
  --url "$BASE_URL/connections/$CONNECTION_ID/accept" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    "external_property_id": "$EXTERNAL_PROPERTY_ID"
  }"

# 4. Fetch Bolt rooms. Copy the chosen room id into BOLT_ROOM_ID.
curl --request GET \
  --url "$BASE_URL/connections/$CONNECTION_ID/rooms" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

# 5. Save the room mapping.
curl --request PUT \
  --url "$BASE_URL/connections/$CONNECTION_ID/room-mappings" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    "mappings": [
      {
        "bolt_room_id": "$BOLT_ROOM_ID",
        "external_room_id": "$EXTERNAL_ROOM_ID"
      }
    ]
  }"

# 6. Update one date.
curl --request PUT \
  --url "$BASE_URL/connections/$CONNECTION_ID/availability" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $INDIVIDUAL_KEY" \
  --data "{
    "updates": [
      {
        "external_room_id": "$EXTERNAL_ROOM_ID",
        "date": "$SINGLE_DATE",
        "available": 3
      }
    ]
  }"

# 7. Update an inclusive date range and close its inventory.
curl --request PUT \
  --url "$BASE_URL/connections/$CONNECTION_ID/availability" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $RANGE_KEY" \
  --data "{
    "updates": [
      {
        "external_room_id": "$EXTERNAL_ROOM_ID",
        "from": "$RANGE_FROM",
        "to": "$RANGE_TO",
        "available": 0
      }
    ]
  }"

# 8. Retry the exact same range payload with the same key.
curl --request PUT \
  --url "$BASE_URL/connections/$CONNECTION_ID/availability" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $RANGE_KEY" \
  --data "{
    "updates": [
      {
        "external_room_id": "$EXTERNAL_ROOM_ID",
        "from": "$RANGE_FROM",
        "to": "$RANGE_TO",
        "available": 0
      }
    ]
  }"

# 9. Retrieve connection and last-sync status.
curl --request GET \
  --url "$BASE_URL/connections/$CONNECTION_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Expected results

  • Authentication returns a bearer token with expires_in: 3600.
  • Acceptance changes the test connection from PENDING to ACTIVE and persists the supplied external property ID.
  • The mapping appears in both the mapping list and the room's mapped_external_room_id field.
  • A successful positive update displays the exact available unit count on the corresponding Bolt room-date.
  • The range update closes every date from RANGE_FROM through RANGE_TO, inclusive.
  • The duplicate request returns the original result and does not apply another mutation.
  • Reading the connection shows a newer last_availability_sync_at after at least one entry succeeds.

Reservation notification test

With an active mapped room and a webhook configured by Bolt, create a confirmed Bolt booking for a future date. Verify that the event appears in the pending list, the webhook signature validates, the event and reservation-detail snapshots contain only mapped inventory, the revised absolute availability request succeeds, and the acknowledgement removes the event from the default pending view. Repeat the webhook delivery to confirm event_id deduplication and modify then cancel the booking to verify versions and prior allocation snapshots.

Reservation recovery smoke test
curl -sS "$BASE_URL/reservation-events?status=PENDING&limit=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS "$BASE_URL/connections/$CONNECTION_ID/reservations/$RESERVATION_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS -X POST "$BASE_URL/reservation-events/$EVENT_ID/acknowledge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"PROCESSED"}'

Partial-failure test

This batch includes one mapped room and one deliberately unmapped external room ID. Expect the valid room-date to succeed and the second item to return ROOM_MAPPING_NOT_FOUND at index 1.

Partial-failure 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:$EXTERNAL_PROPERTY_ID:partial-001" \
  --data "{
    "updates": [
      {
        "external_room_id": "$EXTERNAL_ROOM_ID",
        "date": "$SINGLE_DATE",
        "available": 2
      },
      {
        "external_room_id": "CM_ROOM_DOES_NOT_EXIST",
        "date": "$SINGLE_DATE",
        "available": 2
      }
    ]
  }"

Idempotency conflict test

After the walkthrough's range request completes, this command reuses its key but changes availability from 0 to 1. Expect HTTP 409 IDEMPOTENCY_KEY_REUSED. Do not run this against a batch key whose original request is still in progress.

Conflict request
curl --request PUT \
  --url "$BASE_URL/connections/$CONNECTION_ID/availability" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $RANGE_KEY" \
  --data "{
    "updates": [
      {
        "external_room_id": "$EXTERNAL_ROOM_ID",
        "from": "$RANGE_FROM",
        "to": "$RANGE_TO",
        "available": 1
      }
    ]
  }"

Disconnected connection test

V1 does not expose a partner disconnect endpoint. Ask the designated Bolt test property to disconnect the integration in its dashboard, re-read the connection until it reports DISCONNECTED, and then submit a new availability batch. Expect HTTP 409 CONNECTION_NOT_ACTIVE; no inventory should change.

Static checks are not calendar verification

A successful request or application build does not prove that the property-facing calendar is correct. Complete the test by visually checking the designated Bolt property and comparing the exact room, dates, unit counts, closed dates, connection state, and last-sync time.