Book hotels
Places and pays for hotel bookings of up to 5 searched or quoted rates.
Places and pays for hotel bookings of up to 5 searched or quoted rates.
Requires an Idempotency-Key header (a new UUID per purchase) and an API key with order-manage
permission. Repeating the same request with the same key returns the original order; while the first
request is still running the response is 409 / 12002 with Retry-After, after which you send the
same request again. The order is paid from your wallet balance and each booking
completes asynchronously: track it with GET /orders/{id} or the order.fulfillment.updated
webhook.
The body is { currency, referenceId, items } with 1 to 5 items, each
{ publicId, quantity, inputs }. publicId is an offer's publicId from search, or the
newer one from quote, and quantity must be 1. inputs holds the holder and one
roomGuests entry per searched room (roomIndex 1 to N), whose guests must match the searched
occupancy and child ages, the optional specialRequests, and the optional price guard
maxPrice in the order currency. Unknown fields are rejected with 400.
The whole body is validated first: a body error gives 400 / 10001, also when it is in a later item. Once
the body is valid, each item is checked completely before the next, and an error names its item in
details[].path.
Before any money moves each rate is priced again in the order currency and capped: at
inputs.maxPrice when sent, else at the price shown with the publicId. Above the cap the order
returns 409 / 11002 at items[i].inputs.maxPrice or items[i] (quote again); at or below it
the rate is charged as priced, so a maxPrice above the shown price accepts a rise up to it. A rate
that cannot be booked now returns 409 / 11003, an offer priced in another currency than the order
400 / 11005, and an unknown, expired or another partner's publicId 400 / 11004, each at
items[i]. Offer and hotel-system failures return their hotel codes (21003, 21007–21010) without a
path. A wallet charge that fails gives 402 / 16000, with details[0] naming wallet and
INSUFFICIENT_BALANCE or WALLET_BLOCKED; send the same request with the same key after a
top-up. Nothing is created or charged when the order is refused.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
Idempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuid- body
The body of a B2B hotel quote and order: the currency, an optional reference and the rates to price or book.
currency?|Quote and order currency, three letters in either case; the API key's currency when omitted. An order must be
in the currency the offers were priced in; a quote prices them in it. An unsupported code gives 400 / 10001 at
currency, reason NOT_SUPPORTED, before any item is checked.
referenceId?|Your own order reference, up to 128 characters without leading or trailing spaces, unique per partner. Reusing it for a different order returns 409. A quote checks it and ignores it.
items*array<>1 to 5 items; each prices or books one rate.
OK
- response
The current state of an order.
id*stringOrder id.
uuidorigin*Where the order was created.
status*stringCurrent order status: paymentPending, processing, completed,
partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.
"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"total*What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.
refunded*What completed item refunds returned, in the order's currency; zero when nothing was
returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.
payment?|The latest payment attempt; null when none was made.
items*array<>The order items, one per unit bought.
timeline*array<>Every status the order has had, oldest first, each once per stretch.
createdAt*stringWhen the order was created (UTC).
date-timeupdatedAt*stringWhen anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.
date-timefulfillmentVersion*integerIncreases with every fulfillment change; matches the
order.fulfillment.updated webhook.
int64referenceId?|Your own order reference, when one was sent.
customer?|The traveller who paid on your hosted site, masked; null unless the origin is site, and
once the traveller's details are deleted at the end of their retention period.
curl -X POST 'https://api.sandbox.openroam.com/v1/hotels/order' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "referenceId": "partner-booking-42", "items": [ { "publicId": "rate_x5z2b4d6f3h5jn2pq7m2k4t6v3", "quantity": 1, "inputs": { "holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "ana@example.com", "phone": "+34600123456" }, "roomGuests": [ { "roomIndex": 1, "guests": [ { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "age": 34 }, { "title": "Mr", "firstName": "Luis", "lastName": "Garcia", "age": 36 }, { "title": "Miss", "firstName": "Sofia", "lastName": "Garcia", "age": 7 } ] } ], "specialRequests": "Late arrival", "maxPrice": { "amount": 650, "currency": "USD" } } } ]}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "origin": { "channel": "api" }, "status": "paymentPending", "total": { "amount": 0, "currency": "string" }, "refunded": { "amount": 0, "currency": "string" }, "payment": { "status": "pending", "method": "balance", "amount": { "amount": 0, "currency": "string" }, "wallet": { "label": "string", "debited": { "amount": 0, "currency": "string" } }, "failure": { "code": 0, "name": "string", "message": "string" } }, "items": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5", "productType": "hotel", "price": { "amount": 0, "currency": "string" }, "purchasedProduct": { "name": "string", "countryCode": "string", "logoUrl": "string", "inputs": { "holder": { "title": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string" }, "roomGuests": [ { "roomIndex": 0, "guests": [ { "nationality": "string", "countryOfResidence": "string", "title": "string", "firstName": "string", "lastName": "string", "middleName": "string", "age": 0 } ] } ], "specialRequests": "string", "specialRequestCodes": [ "string" ] }, "details": { "checkInDate": "2019-08-24", "checkOutDate": "2019-08-24", "requestedRooms": [ { "adults": 0, "children": 0, "childrenAges": [ 0 ] } ], "hotel": { "name": "string", "starRating": 0, "address": { "line1": "string", "line2": "string", "city": "string", "stateProvince": "string", "postalCode": "string", "countryCode": "string", "countryName": "string" }, "coordinates": { "latitude": 0.1, "longitude": 0.1 }, "description": "string", "imageUrls": [ "string" ], "amenityGroups": [ { "key": "string", "codes": [ "string" ] } ], "contact": { "phone": "string", "email": "string", "website": "string", "address": { "line1": "string", "line2": "string", "city": "string", "stateProvince": "string", "postalCode": "string", "countryCode": "string", "countryName": "string" } } }, "terms": { "payment": { "type": "payNow", "dueNow": { "amount": 0, "currency": "string" }, "dueLater": { "amount": 0, "currency": "string" }, "dueLaterAt": "property" }, "cancellation": { "type": "fullyRefundable", "freeUntil": "2019-08-24T14:15:22Z", "freeUntilLocalTime": "2026-12-01T08:30:00", "timezone": "string", "schedule": [ { "from": "2019-08-24T14:15:22Z", "fromLocalTime": "2026-12-01T08:30:00", "refund": { "amount": 0, "currency": "string" }, "penalty": { "amount": 0, "currency": "string" } } ], "fee": { "amount": 0, "currency": "string" } }, "changes": { "allowed": true, "fee": { "type": "fixed", "amount": { "amount": 0, "currency": "string" }, "percent": 0, "min": { "amount": 0, "currency": "string" }, "max": { "amount": 0, "currency": "string" } } } }, "rate": { "rooms": [ { "roomGroupKey": "string", "name": "string", "description": "string", "beds": [ { "type": "string", "count": 0 } ], "maxOccupancy": 0, "sizeSquareMeters": 0, "amenities": [ "string" ], "imageUrls": [ "string" ], "roomIndex": 0, "adultsCount": 0, "childrenCount": 0, "childrenAges": [ 0 ] } ], "board": { "code": "string", "name": "string", "boardType": "unknown" }, "taxes": { "included": true, "totalTaxAmount": 0, "items": [ { "name": "string", "amount": 0, "currency": "string", "includedInPrice": true } ] }, "priceIsBinding": true, "nightlyPrices": [ { "date": "2019-08-24", "amount": 0, "currency": "string" } ], "rateTags": [ "string" ], "remarks": [ "string" ], "rateConditions": [ "string" ], "withTransfers": true, "rateRules": [ "unknown" ], "amendabilityStatus": "unknown", "surcharges": [ { "type": "string", "description": "string", "price": { "amount": 0, "currency": "string" }, "approxPrice": { "amount": 0, "currency": "string" }, "includedInTotal": true, "payableAt": "property" } ], "minimumSellingPrice": { "amount": 0, "currency": "string" }, "allowsSpecialRequests": true, "specialRequestOptions": [ { "code": "string", "name": "string" } ] } } }, "fulfillment": { "status": "pending", "result": { "details": { "bookingStatus": "confirmed", "hotelConfirmationNumber": "string", "amendmentComposition": { "guests": { "addMore": true, "remove": true, "guestType": true, "names": true, "ages": true }, "rooms": { "addMore": true, "remove": true }, "dates": { "change": true }, "holder": { "change": true } }, "booking": { "checkInDate": "2019-08-24", "checkOutDate": "2019-08-24", "holder": { "title": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string" }, "roomGuests": [ { "roomIndex": 0, "guests": [ { "nationality": "string", "countryOfResidence": "string", "title": "string", "firstName": "string", "lastName": "string", "middleName": "string", "age": 0 } ] } ] } } }, "failure": { "code": 0, "name": "string", "message": "string" }, "progress": { "code": "string", "message": "string" } }, "actions": { "amendment": { "availability": "available", "reason": "string" }, "cancellation": { "availability": "available", "reason": "string" }, "update": { "availability": "available", "reason": "string" } }, "createdAt": "2019-08-24T14:15:22Z", "effectivePaidAmount": { "amount": 0, "currency": "string" }, "refund": { "status": "pending", "amount": { "amount": 0, "currency": "string" }, "updatedAt": "2019-08-24T14:15:22Z", "wallet": { "label": "string", "credited": { "amount": 0, "currency": "string" } } } } ], "timeline": [ { "status": "paymentPending", "occurredAt": "2019-08-24T14:15:22Z" } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "fulfillmentVersion": 0, "referenceId": "string", "customer": { "email": "string", "name": "string", "phone": "string", "language": "string", "countryCode": "string" }}Search gift cards GET
Searches gift cards and returns them with their offers, one page at a time. Returns `{ items, pagination }`. `countryCode`, `category`, `q` and `isRedeemableGlobally` select cards; `valueType` selects offers within them, and a card left without an offer is dropped. Pages count cards. Prices are indicative, in `currency`; a fixed offer is listed only when it is cheaper than the card's range at the same value. An invalid or unknown parameter gives 400 / 10001; an unsupported `currency` gives 400 / 10001 at `currency`.
List hotel amenities GET
Returns the amenity catalog: every amenity code and group with its display label. Use it to label the `amenityGroups` codes in hotel content and to build an amenity filter; send codes back in search `filters.amenityCodes`. `notesLabel` is the heading for a hotel's uncoded `amenityNotes`. Labels follow the request language, as `Accept-Language` sets it; the route takes no query parameters.