Skip to main content

​
Endpoint

POST /api/book

​
Authentication

  • Required header: api-key: <partner-api-key>
  • Required body field: settings.access.code

​
Headers

HeaderRequiredDescription
Content-TypeYesapplication/json
api-keyYesPartner API key
connection-codeOptionalAuto-filled from body
session-idOptionalAuto-generated if missing

​
Request Body

​
Top-level fields

FieldTypeRequiredNotes
bookCriteriaobjectYesBooking input payload
settingsobjectYesMust include access.code
distributionContextobjectNoOptional

​
bookCriteria fields

FieldTypeRequiredNotes
quoteIdstringYesFrom quote response data.id
accommodation.typestringNoDefault Hotel
accommodation.codestringYesMust match quoted payload
occupancies[]arrayNoOptional override; if provided, validated against quote snapshot
occupancies[].occupancyIdnumberYes*Required when occupancies provided
occupancies[].paxes[]arrayYes*Required when occupancies provided
occupancies[].paxes[].agenumberYesGuest age
occupancies[].paxes[].namestringNoGuest first name
occupancies[].paxes[].surNamestringNoGuest last name
marketstringNoMarket code
paymentTypestringNoSupported enum; practical flow uses MerchantPay
partnerReferencestringYesPartner-side booking reference
holder.namestringYesBooking holder first name
holder.surNamestringYesBooking holder last name
checkInstringYesMust match quote
checkOutstringYesMust match quote
languagestringNoOptional
currencystringNoOptional
nationalitystringNoOptional

​
Example Request

{
  "bookCriteria": {
    "quoteId": "cb4af805-08aa-4ec4-9f90-a8b94e6d9d54",
    "accommodation": {
      "type": "Hotel",
      "code": "6475503709317edd78e1dbd9"
    },
    "occupancies": [
      {
        "occupancyId": 1,
        "paxes": [
          { "age": 30, "name": "John", "surName": "Smith" },
          { "age": 28, "name": "Jane", "surName": "Smith" }
        ]
      }
    ],
    "paymentType": "MerchantPay",
    "partnerReference": "partner-ref-10001",
    "holder": {
      "name": "John",
      "surName": "Smith"
    },
    "checkIn": "2026-03-01",
    "checkOut": "2026-03-03",
    "language": "EN",
    "currency": "USD",
    "nationality": "US"
  },
  "settings": {
    "access": { "code": 10001 }
  }
}

​
Success Response

{
  "data": {
    "bookingReference": "BK_EXAMPLE_001",
    "partnerReference": "partner-ref-10001",
    "status": "success",
    "chargeTotal": 138.5,
    "hotelConfirmationNumber": "CNF_EXAMPLE_001",
    "requestId": "req_book_64f5..._1739260000000_62131",
    "responseTime": 241
  },
  "message": "success"
}

​
Response Fields

FieldTypeNotes
data.bookingReferencestringSystem booking reference
data.partnerReferencestringPartner reference from request
data.statusstringsuccess on successful booking
data.chargeTotalnumberCharged total amount
data.hotelConfirmationNumberstringOptional supplier/hotel confirmation
data.requestIdstringTrace ID
data.responseTimenumberMilliseconds

​
Validation Behavior

  • quoteId must exist in quote cache and not be expired
  • Accommodation and stay dates must match quote snapshot
  • If occupancies are provided, adult/child counts and pax counts must match quote snapshot
  • settings.access.code must belong to partner linked to API key
  • On supplier booking failure, API returns 400 The booking was not successful.

​
Common Errors

  • 400 optionId is required
  • 400 Quote reference expired or invalid. Please quote again.
  • 400 Accommodation code mismatch
  • 400 Stay dates mismatch
  • 400 occupancyId is required when providing occupancies
  • 400 Occupancy X not found in cached quote
  • 400 Missing rate snapshot for booking
  • 400 Missing supplier metadata for booking
  • 400 The booking was not successful.
  • 403 Invalid connection code.
  • 404 Accommodation not found