Docs
Get an API key
Hotel bookings

Prebook a hotel stay

POST
/v1/hotel/prebook

You bind an offer to your contact and room guests. Supply one adult lead per room and keep the room order from your offer. Repeat your idempotency key to read the existing booking. A payment SDK token is returned once in meta.payment_sdk.token when you request SDK payment; it is not stored for later retrieval.

Authorization

x-api-key<token>

Your API key. Issued and revoked from the TrustPixel dashboard; the gateway resolves it to an owning organization on every request.

In: header

Header Parameters

x-request-id?string

Correlation id echoed to the upstream service and returned on the response. Generated as req_<uuid> when omitted.

x-idempotency-key*string
Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/hotel/prebook" \  -H "x-idempotency-key: string" \  -H "Content-Type: application/json" \  -d '{    "offer_reference": "REPLACE_WITH_RETURNED_OFFER_REFERENCE",    "reference_id": "order-example",    "use_payment_sdk": false,    "contact": {      "first_name": "Alex",      "last_name": "Morgan",      "email": "alex@example.com",      "phone": "+447700900123"    },    "rooms": [      {        "guests": [          {            "first_name": "Alex",            "last_name": "Morgan",            "type": "ADULT",            "is_lead": true          },          {            "first_name": "Sam",            "last_name": "Morgan",            "type": "ADULT",            "is_lead": false          }        ]      },      {        "guests": [          {            "first_name": "Jamie",            "last_name": "Lee",            "type": "ADULT",            "is_lead": true          },          {            "first_name": "Taylor",            "last_name": "Lee",            "type": "ADULT",            "is_lead": false          }        ]      }    ]  }'

{  "data": {    "id": "bkg_example",    "reference_id": "order-example",    "status": "READY_FOR_COMPLETE",    "hotel": {      "id": "htl_example",      "name": "Example Marina Hotel",      "address": "Example Avenue, Dubai, AE"    },    "check_in": "2027-11-22",    "check_out": "2027-11-24",    "total": {      "amount": 600,      "currency": "USD"    },    "created_at": "2027-10-01T10:01:00Z",    "updated_at": "2027-10-01T10:01:01Z",    "confirmed_at": null,    "canceled_at": null,    "payments": [],    "cancellations": [],    "hotel_confirmation_code": null,    "hotel_remarks": null,    "offer_expires_at": "2027-10-01T10:15:00Z",    "due_at_property": null,    "cancellation_policy": null,    "contact": {      "first_name": "Alex",      "last_name": "Morgan",      "email": "alex@example.com",      "phone": "+447700900123"    },    "loyalty": null,    "rooms": [      {        "id": "room_example1",        "position": 0,        "name": "Deluxe Twin",        "board": "ROOM_ONLY",        "board_name": "Room Only",        "adults": 2,        "children": [],        "total": {          "amount": 300,          "currency": "USD"        },        "due_at_property": null,        "cancellation_policy": {          "version": 1,          "refundable": true,          "deadline": "2027-11-20T00:00:00Z",          "penalties": [            {              "from": "2027-11-20T00:00:00Z",              "type": "AMOUNT",              "amount": {                "amount": 150,                "currency": "USD"              }            }          ],          "restrictions": []        },        "promotions": null,        "supplier_reference_number": null,        "hotel_confirmation_code": null,        "canceled_at": null,        "guests": [          {            "id": "guest_example11",            "first_name": "Alex",            "last_name": "Morgan",            "type": "ADULT",            "is_lead": true          },          {            "id": "guest_example12",            "first_name": "Sam",            "last_name": "Morgan",            "type": "ADULT",            "is_lead": false          }        ]      },      {        "id": "room_example2",        "position": 1,        "name": "Deluxe Double",        "board": "ROOM_ONLY",        "board_name": "Room Only",        "adults": 2,        "children": [],        "total": {          "amount": 300,          "currency": "USD"        },        "due_at_property": null,        "cancellation_policy": {          "version": 1,          "refundable": true,          "deadline": "2027-11-20T00:00:00Z",          "penalties": [            {              "from": "2027-11-20T00:00:00Z",              "type": "AMOUNT",              "amount": {                "amount": 150,                "currency": "USD"              }            }          ],          "restrictions": []        },        "promotions": null,        "supplier_reference_number": null,        "hotel_confirmation_code": null,        "canceled_at": null,        "guests": [          {            "id": "guest_example21",            "first_name": "Jamie",            "last_name": "Lee",            "type": "ADULT",            "is_lead": true          },          {            "id": "guest_example22",            "first_name": "Taylor",            "last_name": "Lee",            "type": "ADULT",            "is_lead": false          }        ]      }    ]  }}

Estimate your cancellation fee GET

You receive an advisory quote from fresh supplier data: SUPPLIER_QUOTE uses a cancellation preview (WebBeds), while POLICY_ESTIMATE calculates from a freshly retrieved booking policy (LiteAPI and Duffel Stays). checked_at is the UTC time when the supplier reads completed, not a guaranteed validity deadline. Unreadable or missing booking policies return available=false; failed reads or unusable supplier preview responses return an error instead of stale terms. A local booking change during retrieval returns 409. An active stored WebBeds restriction returns 422 cancellation_restricted before or after the supplier reads. available describes the amount, not whether a new cancellation can start while earlier refund processing remains unfinished. The supplier's cancellation response determines the final fee. Your estimated refund uses the released price; the actual refund is capped by captured funds less previous refund intents.

Complete your hotel booking POST

You complete a ready booking with your saved payment instrument, or send an empty object after authorizing the SDK payment. A repeated confirmed booking returns its stored result. Read an in-progress booking when the result is unknown; do not create a replacement purchase.