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
- Ask your BedsChain account manager to switch on API access for your account.
- 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. - 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.
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 } ] } ]
}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.
| Method | Path | Scope | What it does |
|---|---|---|---|
| GET | /destinations?q= | content:read | Cities, areas and hotels by name (2 to 100 characters) |
| GET | /hotels?city=&page=&size= | content:read | The hotels of a city, a page at a time (up to 200) |
| GET | /hotels/changes?since= | content:read | Hotels changed since a time, to keep your own copy current (1,000 a page; follow next) |
| GET | /hotels/{hotelId} | content:read | A hotel’s static content |
| POST | /availability | search | Search a city or up to 500 hotels; answers when complete or at timeoutMs |
| POST | /prebook | book | Check an offer with the hotel and hold its price; returns prebookId (Idempotency-Key required) |
| POST | /bookings | book | Book a held price (Idempotency-Key required) |
| GET | /bookings?from=&to=&clientReference= | bookings:read | Your bookings |
| GET | /bookings/{reference} | bookings:read | One booking, with its latest status |
| GET | /bookings/{reference}/cancel-quote | cancel | What cancelling now costs |
| POST | /bookings/{reference}/cancel | cancel | Cancel at the quoted charge (Idempotency-Key required) |
| GET | /wallet | wallet:read | Balances, credit and what is available |
| GET POST | /webhooks | webhooks:manage | Your webhook endpoints; adding one returns its signing secret once |
| DELETE | /webhooks/{id} | webhooks:manage | Remove an endpoint |
| POST | /webhooks/{id}/test | webhooks:manage | Send 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 } }UNAUTHENTICATED | 401 | No key, a wrong key, or a revoked or expired one |
FORBIDDEN | 403 | Missing scope, an address not on the allow-list, or API access switched off |
NOT_FOUND | 404 | No such booking, hotel or offer for your account |
VALIDATION_FAILED | 400 / 422 | The request is not valid; details list each field |
OFFER_EXPIRED | 410 | The offer is no longer held: search again |
SOLD_OUT | 409 | The room is no longer available |
CONFLICT | 409 | The price hold expired, or the cancellation charge changed: check again |
WALLET_INSUFFICIENT_FUNDS | 402 | Not enough balance or credit for this booking |
RATE_LIMITED | 429 | Too many requests: wait for Retry-After seconds |
SERVICE_UNAVAILABLE | 502 / 503 | A 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", … } }- Answer 2xx within 5 seconds. Anything else is retried: 10 s, 20 s, 40 s … up to an hour apart, about 12 times.
- After 100 failures in a row the endpoint is switched off and you are emailed; switch it back on in the console.
- Check the signature and refuse timestamps older than 5 minutes. Order is not guaranteed: re-read the booking if in doubt.
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 name | Confirmed at once |
Onrequest | On request, then confirmed a few minutes later |
Timeout | Processing (no clear answer), then confirmed |
Timeoutfail | Processing, then failed |
Soldout | The booking is refused: sold out |
Cancelfail | Cancelling 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:
- searches by city and by hotel ids, and handles complete: false;
- checks the price, then books a refundable room;
- books a non-refundable room;
- handles a changed price: checks again or stops, never books the old offer;
- handles processing: no duplicate booking (same Idempotency-Key, or polls);
- handles an on-request booking through a webhook;
- cancels with a cancellation quote;
- verifies the webhook signature (2xx only for a valid one);
- backs off on 429;
- 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
- v1 (October 2026): search, price check, booking, cancellation, wallet, content, webhooks.