BedsChain Partner API

Connect your own booking system to BedsChain: search hotels at your prices, hold a price, book, cancel, and hear about every change by webhook.

Getting started

  1. Ask your BedsChain account manager to switch on API access for your account.
  2. Sign in to the agent portal and open Developers. Create a sandbox key (it starts with bc_test_); it is shown once, so store it safely.
  3. Build against the sandbox, then pass certification. Your live key (bc_live_) is made on the live portal after that.

The API is at https://api.bedschain.com/partner/v1 (live) and on the sandbox host your account manager gives you. JSON only, UTF-8; times in ISO 8601; money always as {"amount": "123.45", "currency": "AED"} with the amount as text. Every response carries X-Request-Id: quote it to support. Ignore fields you do not know; new fields are added without a new version.

Open the developer console

Authentication

Send your key on every request. Keys have scopes; a key without the scope an endpoint needs gets 403. A key can be limited to your IP addresses (CIDR ranges) and given an expiry date.

curl https://api.bedschain.com/partner/v1/wallet \
  -H "Authorization: Bearer bc_live_AbCdEfGhIjKl.0123456789abcdefghijklmnopqrstuv"

To rotate a key, create a new one, switch your system to it, then revoke the old one; both work until you do.

Booking flow

1. POST /availability      → hotels with offers at your price (offerId)
2. POST /prebook {offerId} → prebookId, the price held for you, cancellation terms
3. POST /bookings          → 201 CONFIRMED, or 202 PROCESSING / ON_REQUEST
4. Webhook booking.confirmed / booking.failed  (or poll GET /bookings/{reference})

Search

POST /partner/v1/availability
{
  "checkIn": "2026-12-10", "checkOut": "2026-12-13",
  "destination": { "cityId": "6f1c…" },            // or { "hotelIds": ["2b7e…", …] }, up to 500
  "rooms": [{ "adults": 2, "childAges": [7] }],
  "nationality": "PK",
  "timeoutMs": 8000, "maxOffersPerHotel": 20,
  "filters": { "refundableOnly": false, "boards": ["BB", "HB"] }
}
→ { "searchId": "…", "complete": true, "currency": "AED",
    "hotels": [ { "hotelId": "2b7e…", "lowestPrice": {…}, "offers": [
      { "offerId": "…", "roomName": "Deluxe King Room", "boardCode": "BB", "refundable": true,
        "price": { "amount": "1124.50", "currency": "AED" },
        "cancellationPolicy": [ { "from": "2026-12-06T20:00:00Z", "charge": { "amount": "1124.50", "currency": "AED" } } ] } ] } ] }

complete: false means the time ran out before every supplier answered: show what you have, or search again. Prices are yours: your BedsChain rates in your account currency. City and hotel ids come from /destinations.

Book

POST /partner/v1/bookings
Idempotency-Key: 3f1e0c3a-…            (a new UUID per booking)
{
  "prebookId": "…", "clientReference": "PARTNER-88812", "paymentMethod": "WALLET",
  "holder": { "email": "ali@example.com", "phone": "+923001234567" },
  "rooms": [ { "guests": [
    { "type": "ADULT", "title": "MR", "firstName": "Ali", "lastName": "Khan", "lead": true },
    { "type": "CHILD", "firstName": "Sara", "lastName": "Khan", "age": 7 } ] } ]
}
Never book again after a 202 or a timeout. Send the same request with the same Idempotency-Key (you get the original answer), or poll GET /bookings/{reference}, or wait for the webhook. Names in Latin letters. paymentMethod is WALLET (balance, then credit) or PAY_LATER where the price check says it is available.

Cancel

Get /bookings/{reference}/cancel-quote, then POST /bookings/{reference}/cancel with {"expectedCharge": <the quoted charge>}. If the charge has changed since, you get 409 and a new quote.

Endpoints

All under /partner/v1. The full reference, with every field, is the OpenAPI 3.1 file: import it into Postman, Insomnia or your code generator.

MethodPathScopeWhat it does
GET/destinations?q=content:readCities, areas and hotels by name (2 to 100 characters)
GET/hotels?city=&page=&size=content:readThe hotels of a city, a page at a time (up to 200)
GET/hotels/changes?since=content:readHotels changed since a time, to keep your own copy current (1,000 a page; follow next)
GET/hotels/{hotelId}content:readA hotel’s static content
POST/availabilitysearchSearch a city or up to 500 hotels; answers when complete or at timeoutMs
POST/prebookbookCheck an offer with the hotel and hold its price; returns prebookId (Idempotency-Key required)
POST/bookingsbookBook a held price (Idempotency-Key required)
GET/bookings?from=&to=&clientReference=bookings:readYour bookings
GET/bookings/{reference}bookings:readOne booking, with its latest status
GET/bookings/{reference}/cancel-quotecancelWhat cancelling now costs
POST/bookings/{reference}/cancelcancelCancel at the quoted charge (Idempotency-Key required)
GET/walletwallet:readBalances, credit and what is available
GET POST/webhookswebhooks:manageYour webhook endpoints; adding one returns its signing secret once
DELETE/webhooks/{id}webhooks:manageRemove an endpoint
POST/webhooks/{id}/testwebhooks:manageSend a test event

A booking reads: reference, clientReference, status (PROCESSING, ON_REQUEST, CONFIRMED, CANCELLATION_PENDING, CANCELLED, FAILED), paymentStatus, hotel, checkIn, checkOut, rooms (name, board, guests, hotelConfirmation), price, cancellation and createdAt.

Errors

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. …", "reference": "req_…", "retryable": true } }
UNAUTHENTICATED401No key, a wrong key, or a revoked or expired one
FORBIDDEN403Missing scope, an address not on the allow-list, or API access switched off
NOT_FOUND404No such booking, hotel or offer for your account
VALIDATION_FAILED400 / 422The request is not valid; details list each field
OFFER_EXPIRED410The offer is no longer held: search again
SOLD_OUT409The room is no longer available
CONFLICT409The price hold expired, or the cancellation charge changed: check again
WALLET_INSUFFICIENT_FUNDS402Not enough balance or credit for this booking
RATE_LIMITED429Too many requests: wait for Retry-After seconds
SERVICE_UNAVAILABLE502 / 503A temporary problem: retry later (retryable: true)

Rate limits

Per key and per minute: 600 requests in all, 120 searches, 60 bookings and price checks. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 with Retry-After (seconds). Your account manager can raise the limits.

Webhooks

Add an https endpoint in the developer console (or POST /webhooks) and choose its events: booking.confirmed, booking.on_request, booking.failed, booking.cancelled, booking.hcn_received (the hotel's confirmation number arrived), wallet.low_balance (what you can spend fell below the alert you set under Payments) and wallet.credited (a deposit reached your wallet). Its signing secret (whsec_…) is shown once.

POST <your url>
Content-Type: application/json
X-BC-Event: booking.confirmed
X-BC-Delivery: evt_01J9Z…          (dedupe on this)
X-BC-Timestamp: 1793012345
X-BC-Signature: v1=<hex HMAC-SHA256(secret, timestamp + "." + body)>

{ "id": "evt_01J9Z…", "type": "booking.confirmed", "createdAt": "…",
  "data": { "reference": "BC-K7MP2Q4X", "clientReference": "PARTNER-88812", "status": "CONFIRMED", … } }

Node.js

import crypto from 'node:crypto';

// raw: the request body exactly as received (a string), secret: your whsec_… secret
export function verify(raw, headers, secret) {
  const ts = headers['x-bc-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.' + raw).digest('hex');
  const given = String(headers['x-bc-signature'] || '');
  return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

PHP

<?php
function bedschain_verify(string $raw, array $headers, string $secret): bool {
    $ts = $headers['X-BC-Timestamp'] ?? '';
    if (abs(time() - (int) $ts) > 300) return false;
    $expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
    return hash_equals($expected, $headers['X-BC-Signature'] ?? '');
}

Python

import hashlib, hmac, time

def verify(raw: bytes, headers: dict, secret: str) -> bool:
    ts = headers.get("X-BC-Timestamp", "")
    if abs(time.time() - int(ts or 0)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-BC-Signature", ""))

C#

using System.Security.Cryptography;
using System.Text;

static bool Verify(string raw, string timestamp, string signature, string secret)
{
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(timestamp)) > 300) return false;
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(timestamp + "." + raw));
    var expected = "v1=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signature));
}

Sandbox

The sandbox answers only with test hotels: four “BedsChain Sandbox Hotel” in each of Dubai, Makkah, Istanbul, London and Lahore (find their ids with /destinations?q=sandbox). Nothing is really booked and no real money moves (your sandbox wallet is separate). Each hotel has room-only, bed and breakfast, half board and non-refundable rates. The first guest’s last name chooses what happens:

any other nameConfirmed at once
OnrequestOn request, then confirmed a few minutes later
TimeoutProcessing (no clear answer), then confirmed
TimeoutfailProcessing, then failed
SoldoutThe booking is refused: sold out
CancelfailCancelling waits for the hotel, then is done two minutes later

To test a changed price, choose the room named Price change test: its price check comes back 5 % higher (status: PRICE_CHANGED).

Certification

Before your live key, show in the sandbox that your integration:

  1. searches by city and by hotel ids, and handles complete: false;
  2. checks the price, then books a refundable room;
  3. books a non-refundable room;
  4. handles a changed price: checks again or stops, never books the old offer;
  5. handles processing: no duplicate booking (same Idempotency-Key, or polls);
  6. handles an on-request booking through a webhook;
  7. cancels with a cancellation quote;
  8. verifies the webhook signature (2xx only for a valid one);
  9. backs off on 429;
  10. stores and shows your reference and the BedsChain reference.

Most cases are recognised from your sandbox traffic and appear in the console; a BedsChain reviewer checks the rest and then certifies you.

Changelog