Skip to Content
OpenRoam Docs
Hotels

Book hotels

Places and pays for hotel bookings of up to 5 searched or quoted rates.

POST
/v1/hotels/order

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

  1. 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.

Response Body

OK

  1. response

The current state of an order.

id*string

Order id.

Formatuuid
origin*

Where the order was created.

status*string

Current order status: paymentPending, processing, completed, partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.

Value in"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*string

When the order was created (UTC).

Formatdate-time
updatedAt*string

When anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.

Formatdate-time
fulfillmentVersion*integer

Increases with every fulfillment change; matches the order.fulfillment.updated webhook.

Formatint64
referenceId?|

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.

Example Request
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"        }      }    }  ]}'
Example Response
{  "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"  }}