Take a booking request

A booking request asks the property for a room. It arrives in Book-ah as a pending reservation, with the same emails to the guest and the team as a request from your Book-ah site. It holds no room: the property confirms or declines it, and only a confirmed reservation takes the room.

Send a request

POST /booking-requests/, with a publishable key from your page or a secret key from your server:

const request = await fetch('https://app.book-ah.com/api/partner/v1/booking-requests/', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pk_live_YOUR_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    propertyId,
    roomId,
    checkIn: '2026-12-20',
    checkOut: '2026-12-23',
    adults: 2,
    children: 0,
    rooms: 1,
    boardType: 'BB',
    guest: { name: 'Ada Perera', email: 'ada@example.com', phone: '+94771234567' },
    message: 'We arrive late, around 10pm.',
  }),
}).then((response) => response.json());

// request.data.id: keep it to follow the request
// request.data.status: 'pending'
// request.data.quotedAmount: the total, or null if the property will quote it

The request is held to the rules of your Book-ah site: the room must be free and fit the party, the dates must meet the property’s rules, and the board must be one the room offers for those dates (leave boardType out for the first one). A request that breaks a rule answers 400 with errorCode 1001 and the field in data.fields.

Retry safely with Idempotency-Key

Networks fail, and a guest may press the button twice. Send an Idempotency-Key header, any unique string, with each new request, and send the same key when you retry it:

• the first call answers 201 with the request;
• a retry with the same key and body answers 200 with the same request, and makes no second one;
• the same key with a different body answers 409 with errorCode 4001.

Make one key per booking attempt, such as crypto.randomUUID() when the guest opens the form.

Follow the answer

From your server, with a secret key, GET /booking-requests/{bookingRequestId}/ returns the request and its status:

curl https://app.book-ah.com/api/partner/v1/booking-requests/REQUEST_ID/ \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

status is pending until the property answers, then confirmed or declined, and later cancelled or completed. The guest is emailed at each step either way, and guestUrl is their own page for the request.