/orders/details/
Use the /orders/details/ endpoints to get information about the 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. | Manage loyalty and rewards programs: Filter your orders by specific checkin-chekout dates, so you can process and pay rewards based on reservations after checkout. |
/orders/details/accommodations | Retrieves information about the accommodation-specific part of the order. | Provide details to a customer about a specific accommodation order. |
/orders/details/
Use this endpoint to retrieve general information about the order(s) for specific dates range.
Define your request
- Specify one (and only one) of the following fields to filter the orders you want to return:
created
- Get all orders that have been created within the defined date range.updated
- Get all orders that have been updated in the defined date range. An update is either a modification to an existing order or a change in status.Important- Details of any order update are usually available to the
/orders/details/
endpoints shortly after the update takes place. - However, on rare occasions it might take up to 2 hours after the update.
- Details of any order update are usually available to the
start
- Get all orders associated to the trip that has started in a defined period. For example, the checkin date of the accommodation reservation.end
- Get all orders associated to the trip that has ended in a specific period. For example, the checkout date of the accommodation reservation.orders
- Get one or more specific orders.
Specify the date range ("from" and "to") to retrieve only orders whithin a specific period. Take into account there are some restrictions in dates range definition:
- You can only return orders created (or updated) within 1 year from the call.
- The defined period ("from" - "to") cannot exceed 7 days interval.
- The used format must be "YYYY-MM-DD" (in line to ISO 8601).
Specify the
currency
- This value is mandatory as it will be used in the response as the
booker
currency, and as the currency used forcommission
values. - The full list of currencies can be obtained by calling common/payments/currencies
- This value is mandatory as it will be used in the response as the
You can then optionally specify the other fields.
Example of created
request
{ "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" } }
Example of start
request
In this example, this request returns the orders associated the trip started from 15.05.2024 to 17.05.2024.
{ "start": { "from": "2024-05-15", "to": "2024-05-17" }, "maximum_results": 10, "currency": "USD" }
In this case, only those orders with reservations checkins done on the 15.05.2024, 16.05.2024 and 17.05.2024 will be returned. Same logic applies to the end
filter.
Do you need to retrieve more than 50K orders (total over all pages)? - Split the call into multiple requests with smaller date ranges, so that each request returns less than 50K orders (which is the maximum allowed number of returned orders).
Response
The response retrieves up to 50k orders (total over all pages) and for each matching order, the response returns the following:
Basic details about the order, such as its unique
id
andaffiliate
id, when it wascreated
, and when it was lastupdated
.The
address
,email
,name
andtelephone
fields in thebooker
object contain Personally Identifiable Information (PII).NoteThe PII fields are only returned if the calling partner is authorised to see this information.
commission
shows theactual
amount if this is available, or theestimated
value otherwise.loyalty_reward
is only shown for orders that have a loyalty reward associated to them.status
is also shown by /orders/details/accommodations, at both accommodation andproduct
level.- If individual
products
have differentstatus
values, the most appropriate value is used for thestatus
value of the accommodation and order. For example, if one room in the order has the valuecancelled
but another has the valuestayed
, thestayed
value is used for the accommodation and the order.
- If individual
Example /orders/details response:
... { "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.00, "currency": "EUR", "eligible": true, "fulfillment_at": "2023-09-10", "fulfillment_by": "partner", "type": "point" } ], "price": { "commissionable": 180.01, "total": 180.01 }, "status": "cancelled_by_guest", "updated": "2023-08-25T13:42:13+00:00" }, ...
You can use the
affiliate
id,booker
details,commission_details
,loyalty_reward
,price
, andstatus
to perform different post booking tasks.
/orders/details/accommodations
Use this endpoint to retrieve details of the accommodations listed in a specific order.
Define your request
You must specify one (and only one) 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 when 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".
All other fields are optional.
You can return details about orders or reservations placed up to 1 year ago.
Example of request:
{ "currency": "USD", "extras": [ "accommodation_details", "policies", "extra_charges" ], "orders": [ 2321873123, 4666773123 ] }
Response
For each order, the response returns the following information about the accommodation:
The
id
of the associated orderThe
accommodation
id - You can use it to obtain more information about the property from the /accommodations/details endpoint.The
accommodation_details
, showing information such asname
,email
,location
,telephone
of the accommodation.Information about the accommodation order such as:
cancellation_details
, showing the cancellationfee
that was charged, and when it was charged (This field isnull
if the order has not been cancelled)The
checkin
andcheckout
dates and,commission
breakdown.A
pin_code
, which guests can use to modify or cancel bookings, or to prove their identity when contacting customer support.NoteA
pin_code
is only returned if the order was made through the Demand API, using the /orders/create endpoint.A breakdown of the
price
.
Details about each
product
included in the order, such as:The exact
allocation
of guests, including adults and children (per age) allocation.The guest
name
andemail
that the room is allocated to.NoteThese field contain Personally Identifiable Information (PII). Consequently, these are only returned if the calling partner is authorised to see this information.
The applied
cancellation
policy (it can be fully flexible, with special conditions and non refundable).A breakdown of the product
price
.The
room
id androom_details
such as roomname
andstatus
Did you know?Cancellation policies are returned per-product rather than per-order. This allows you to easily manage complex multi-room bookings where different policies apply to different rooms.
Example /orders/details/accommodations response:
... "id": "xxxxxxxxxxxxx", "accommodation": xxxxxxx, "accommodation_details": { "email": "test_hotel@booking.com", "location": { "address": "111 Street Road", "city": 20089219, "coordinates": { "latitude": 11.923274, "longitude": -92.716188 }, "country": "us", "post_code": "NY 1234" }, "name": "Test Booking Hotel USA", "telephone": "+19876543210" }, "accommodation_order_references": [], "cancellation_details": null, "checkin": "2023-08-24", "checkout": "2023-08-26", "commission": { "actual_amount": ( "accommodation_currency": 17.5, "booker_currency": 14.9 }, "actual_percentage": 20, "estimated_amount": null }, "currency": { "accommodation": "EUR", "booker": "GBP" }, "label": "", "pin_code": "xxxx", "price": { "commissionable": { "accommodation_currency": 170.01, "booker_currency": 147.40 }, "total": { "accommodation_currency": 180.01, "booker_currency": 153.40 } }, "products": [ { "allocation": { "adults": 2, "children": [3,4,5], "guests": 5 }, "guests": [ { "email": "xxxxxxx@example.com", "name": "xxxxxxxxxxx" } ], "policies": { "cancellation": [ { "from": "2023-08-22T14:22:43+00:00", "price": { "accommodation_currency": 45.00, "booker_currency": 38.35 } } ], ... }, "price": { "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 21, "mode": "percentage", "percentage": 9.00, "total_amount": { "accommodation_currency": 7.43, "booker_currency": 6.33 }, "unit_amount": { "accommodation_currency": null, "booker_currency": null } } ] } }, "room": 12345, "room_details": { "name": "Double Deluxe Room" }, "status": "booked" } ], "remarks": "We will need an extra cot. Need room on higher floor", "reservation": 12345678, "status": "booked" ...
Use case - How to retrieve affiliate commission?
You need to report the commission due to each of your affiliates for new orders in the last week:
- Call /orders/details and specify the
created_date
,currency
andmaximum_results
fields.
{ "created" : { "from": "2023-08-23T00:00:00+00:00", "to": "2023-08-29T00:00:00+00:00" }, "currency": "GBP", "maximum_results": 100 }
- Check whether each returned order has an associated
affiliate_id
, and whether it has earned anycommission
.
... { "id": "xxxxxxxx", ... "affiliate": xxxxxx, ... "commission": { "actual_amount": 17.5, "estimated_amount": null }, ... "currency": { "accommodation": "EUR", "booker": "GBP" }, ...
- If the response metadata indicates that more results are available, use the
next_page
token to call each subsequent page of results until you have collected the data for all orders.
"metadata": { "next_page": "eyJhbGci...kCg", "total_results": 1456 }
You can now process the collected data to sort and total the commission for each affiliate id.