Check order details
Use the /orders/details/ endpoints to get information about travel services orders, so you can perform different post-booking tasks.
Overview
You can use the following endpoints to get information about your orders:
| Endpoint | Action | Use it to... |
|---|---|---|
| /orders/details | Returns basic information about the order(s). | ✓ Check orders created or updated on a certain period. ✓ Look at trips that started or ended on a specific period (checkin-chekout dates) so you can manage loyalty and rewards programs. ✓ Check different travel services disclosed in an order, example: car rentals and accommodations. |
| /orders/details/accommodations | Retrieves information about the accommodation-specific part of the order. | ✓ Provide details to a customer about a specific accommodation order. ✓ Check applied cancellation policies and order status. |
| /orders/details/cars | Retrieves details about the car rental specific part of the order. | ✓ Provide information to a customer about a specific car rental order. ✓ Check order status. |
| /orders/details/flights | Returns the flight information included in an order. | ✓ Provide information to a customer about a specific flight order. ✓ Check order status. |
/orders/details/
This API endpoint provides access to general information about accommodation and other travel services (e.g. car rentals) within specific orders over a defined date range.
You can use it to perform post-booking tasks like getting commission values, cancellation or no-show statuses, manage loyalty and rewards programs, etc.
This endpoint returns accommodation orders by default. If you're looking for information on other travel services (such as car rentals or flights) included in the order, you must specify the service in your request.
See the Other travel services example for guidance.
Define your request
Key parameters
To filter the orders you want to retrieve, you must specify one (and only one) of the following fields:
| Orders | You can pass a list of order IDs to retrieve information about specific bookings. |
| Date range | Specify the date range ("from" and "to") to retrieve only orders within a specific period:
|
You also must specify the currency for the response, as it will be used as the booker currency and for commission values.
Use the common/payments/currencies endpoint to see the full list of supported currencies.
Considerations
- Updates are generally reflected in the response shortly after they occur, but it can take up to 2 hours.
- Date range constraints:
- You can only return orders created (or updated) within 1 year from the call date.
- The defined period ("from" - "to") cannot exceed 7 days interval.
- Use the (following the ISO 8601) format (YYYY-MM-DD).
Optional parameters
maximum_results | Set the limit on the number of results returned. |
sort.by | Sort results by creation or update date and specify the direction (ascending/descending). |
Request examples
Example 1 - Order creation date
You can filter orders that were created in a specific date range.
Example:
{
"created": {
"from": "2023-02-28T02:00:00+00:00",
"to": "2023-02-28T02:00:00+00:00"
},
"currency": "EUR",
"maximum_results": 20,
"sort": {
"by": "updated",
"direction": "descending"
}
}This example request would return orders created on February 28, 2023, with the results sorted by updated date.
Example 2 - Trip starting/ ending date
In this example, this request returns the orders associated to a trip that started between the 15.05.2024 and 17.05.2024.
{
"start": {
"from": "2024-05-15",
"to": "2024-05-17"
},
"maximum_results": 10,
"currency": "USD"
}This example returns orders for reservations with check-ins on May 15, 16, or 17, 2024.
The same logic applies to the end filter.
Example 3 - Other travel services
In case you wish to retrieve orders that include other travel services such as car rentals you must specify the desired service(s) in the request.
Example:
{
"created" : {
"from": "2024-09-25T00:00:00+00:00",
"to": "2024-09-30T23:00:00+00:00"
},
"services": ["cars"],
"sort": {
"by": "created",
"direction": "ascending"
},
"maximum_results": 100,
"currency": "EUR"
}This request would retrieve orders that include car rentals, created within the specified date range.
Note the "services" field is exclusive, hence if you want to retrieve both accommodation and car rental services you should specify the two services: services: ["cars", "accommodations"]
Handling large orders
If you need to retrieve more than 50,000 orders across all pages, split your request into multiple smaller calls. This ensures the response is manageable.
Response
For each order, the response contains the following:
| Basic order details: | ||
|---|---|---|
order id | Unique identifier for the order. | |
| ||
| ||
| ||
| This is the currency applied to the disclosed amounts. | |
The booker object containing Personally Identifiable Information (PII) - address, email, name and telephone | ||
commission | Shows the actual amount if this is available, or the estimated value otherwise. | |
loyalty_reward(if applicable) | Displays loyalty rewards details, such as amount, eligibility, and fulfillment date. This field is only visible for those orders that have a loyalty reward associated to them. | |
price | Both the commissionable and total amount. (Refer to Accommodation pricing section for more details) | |
status | This value indicates whether the order has been: booked, cancelled (cancelled_by_accommodation or by guest), stayed, or no-show. |
The PII fields are only returned if you are authorised to see this information.
Multi-room statuses
In cases where individual products have varying statuses, the "stayed" status takes precedence and is applied to both the accommodation and order status.
- For instance, if one room in the order is marked as "cancelled" while another is "stayed," the "stayed" status will be used for both the accommodation and the order.
The status is also shown in the /orders/details/accommodations endpoint response, at both accommodation and product level.
Response examples
Example 1 - Basic response for accommodations
A standard response for accommodation orders would be:
...
{
"id": "xxxxxxxxxxxxxxx",
"accommodations": {
"reservation": 1234567890
},
"affiliate": 123456,
"booker": {
"address": {
"city": "Amsterdam",
"country": null
},
"email": "xxxxxxx@example.com",
"name": {
"first_name": "xxxxxx",
"last_name": "xxxxxxxxxx"
},
"language": "en",
"platform": "desktop",
"telephone": "12345678",
"travel_purpose": "unknown"
},
"commission": {
"actual_amount": 17.5,
"estimated_amount": null
},
"created": "2023-08-25T12:20:30+00:00",
"currency": "EUR",
],
"price": {
"commissionable": 180.01,
"total": 180.01
},
"status": "cancelled_by_guest",
"updated": "2023-08-25T13:42:13+00:00"
},
...Example 2 - Response with loyalty_reward
In case a loyalty reward program is available, this field will be retrieved. You can check there the amount and currency, the type of the program, and timelines.
...
{
"id": "xxxxxxxxxxxxxxx",
"accommodations": {
"reservation": 1234567890
},
"affiliate": 123456,
"booker": {
"address": {
"city": "Amsterdam",
"country": null
},
"email": "xxxxxxx@example.com",
"name": {
"first_name": "xxxxxx",
"last_name": "xxxxxxxxxx"
},
"language": "en",
"platform": "desktop",
"telephone": "12345678",
"travel_purpose": "unknown"
},
"commission": {
"actual_amount": 17.5,
"estimated_amount": null
},
"created": "2023-08-25T12:20:30+00:00",
"currency": "EUR",
"loyalty_reward": [
{
"amount": 15,
"currency": "USD",
"eligible": true,
"fulfillment_at": "2023-02-10",
"fulfillment_by": "partner",
"loyalty_data": [
{
"name": "Email Id",
"value": "john_doe@booking.com"
},
{
"name": "Loyalty ID",
"value": "10101010"
}
],
"type": "point"
}
],
"price": {
"commissionable": 180.01,
"total": 180.01
},
"status": "cancelled_by_guest",
"updated": "2023-08-25T13:42:13+00:00"
},
...Example 3 - Basic response for cars
When looking for a particular car rental reservation using the "services": ["cars"]in the request, the response will retrieve the following fields:
{
"request_id": "01jdpku4ydnnstx0kgfh7kmhf4",
"data": [
{
"id": "0456411j-1c53-3c80-0efd-be8jd4pbaf9a",
"accommodations": null,
"affiliate": 1234567,
"booker": {
"address": {
"city": null,
"country": "gb"
},
"language": null,
"platform": "unknown",
"travel_purpose": null
},
"cars": {
"reservation": 123456789
},
"commission": {
"actual_amount": 0.00,
"estimated_amount": null
},
"created": "2024-09-25T00:00:00+00:00",
"currency": "EUR",
"price": {
"commissionable": 0.00,
"total": 108.40
},
"status": "booked",
"updated": "2024-09-25T05:45:30+00:00"
}
],
"metadata": {
"next_page": "eyJhbGciOQ5IUikDNiJ9.eyJwIjp7ImNyZWF0ZWQiOnsiZnJvbSI6INdh7FQtMDktMjVUMDA6MDA6MDBaIiwidG8iOiIyMDI0LTAlOv4FVDIzOjAwOjAwWiJ9LCJjdXJyZW5jeSI6IO9uh3pKeF4heGltdW1fcmVzdWx0cyI6MTAsImnFg6DldCI6Miwic2VydmljZXMiOlsiY2FycyJdLCJzb3J0Ijp7ImJ5IjoiY3JlYXRlZCIsImRpcmVjdGlvbiI6ImFzY2VuZGluZyJ9fSwiYXVkIjoiL29yZGVycy9kZXRhaWxzIiwiZXhwIjoxNzMyMDEzNzg2fQ.9B9OC-UqiCz7IDvpDA0svOqlbRt9WgMmIohlMvcIGBE",
"total_results": 218
}
}- The "accommodations" field is null as this order does not include accommodation details, but car rentals.
Example 4 - Different travel services (Car rental and accommodation)
In this case, this order has two different reservation ids, one for the accommodation and another one for the car rental reservation.
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [
{
"id": "509430129718799",
"accommodations": {
"reservation": 12345677
},
"affiliate": 111111,
"booker": {
"address": {
"city": "Amsterdam",
"country": "nl"
},
"email": "johndoe@booking.com",
"language": "en-gb",
"name": {
"first_name": "john",
"last_name": "doe"
},
"platform": "mobile",
"telephone": "+100000000",
"travel_purpose": "business"
},
"cars": {
"reservation": 76543210
},
"commission": {
"actual_amount": 17.5,
"estimated_amount": null
},
"created": "2023-02-28T02:00:00+00:00",
"currency": "EUR",
],
"price": {
"commissionable": 160,
"total": 170.01
},
"status": "booked",
"updated": "2023-02-28T02:00:00+00:00"
}
],
"metadata": {
"next_page": null,
"total_results": 1
}
}Flights are not yet available as a travel service in the orders/details response.
/orders/details/accommodations
Use this endpoint to retrieve details of an accommodation listed in a specific order.
→ In the orders/details/accommodations request, specify only one out of the following fields to define the orders for which you want to return information:
orders- Get the data for the specified order(s).reservations- Get the data for the specified reservation(s).Use this option only if you need to access bookings created using Demand API V2, for which you do not have an order
id. For more information, see "bookingDetails - V3 migration guide".NoteYou can retrieve details for orders or reservations placed up to one year ago.
All other fields are optional.
"currency": "USD", "extras": [ "accommodation_details", "policies", "extra_charges" ], "reservations": [ 2321873123, 4666773123 ]
Personally Identifiable Information (PII)
When a partner is authorised to access the Personally Identifiable Information (PII) then, the orders/details/accommodations response returns the following information:
- The guest
nameandemailto whom the room is allocated. - The
external_account_id: This is a unique identifier that represents the account ID in the supply partner's system.
External account id
This field is used to link a specific accommodation order to the corresponding account in the partner's system. It enables the accurate allocation of loyalty points or other benefits in the partner's loyalty and rewards programs.
],
"booker": {
"external_account": 13610217,
"platform": "mobile"
},Conditions for return the external_account_id:
Partner-specific setting:
- This field is conditionally returned based on a configuration in the partner’s admin settings.
- If the partner has enabled this setting, the external_account_id will be included in the response.
PII Agreement:
- The external_account_id will only be included if the partner has a valid Personal Identifiable Information (PII) agreement in place.
- This ensures that the inclusion of the account ID complies with privacy and data protection policies.
Format:
- A string that uniquely identifies the account within the partner's system.
- The format and length of the identifier may vary depending on the partner system configuration.
- If the
external_account_idis not included in the response, it indicates that either the setting has not been enabled by the partner, or a valid PII agreement is not in place. - The presence of
external_account_idenables partners to link bookings to their internal systems for rewards processing.
/orders/details/cars
Use this endpoint to retrieve details of a car rental order. This endpoint follows a similar pattern to that used for accommodations.
→ In the orders/details/cars request, specify one (and only one) of the following fields to define the car rental services for which you want to return information:
order- Include the car rental order id to retrieve the data for the specified order. You can add one or several ids, to retrieve more car rental orders.reservation- Alternatively you can use a reservation ID (or list of ids) to filter data for the specified reservation(s), when you do not have an orderid.NoteYou can retrieve details for orders or reservations placed up to one year ago.
Optionally, you can also pass:
currency- To retrieve pricing in the desired currency.extras.policies- To get the associated policies such as the payment timings.{ "currency": "EUR", "extras": [ "policies" ], "orders": [ "123456789" ] }
/orders/details/flights
Use this endpoint to retrieve details of a flight reservation order. This endpoint follows a similar pattern to that used for accommodations and cars.
→ In the orders/details/flights request, specify the following fields:
order- Include the flight order id to get the data retrieved. You can add one or several ids, to get more flight orders.
Optionally, you can also pass:
currency- To retrieve pricing in the desired currency.NoteYou can retrieve details for orders placed up to one year ago.
"currency": "EUR", ], "orders": [ 12345678895 ]
Post-booking tasks
You can use the affiliate id, booker details, commission_details, loyalty_reward, price, and status to perform different post-booking tasks, like cancellations or reporting the commission due to your affiliates for new orders.
- Learn about accommodation pricing and how you can display them in your application.
- Make yourself familiar with the cancellation process checking the Cancellations guide.