Last updated

/orders/details/*

Use the /orders/details/* endpoints to get information that you need to perform different post-booking tasks.


You can use the following endpoints to get information about your orders:

  • /orders/details provides basic information about the order. For some tasks this endpoint provides all the information you need. For example, managing loyalty rewards.

  • If you need information about the accommodation-specific part of the order, call /orders/details/accommodations as well. For example, to provide details to the customer.

/orders/details

How to define your request

You must specify one (and only one) of the following fields to define what orders you want to return:

  • created - Get all orders that have been created in a specific time window (of up to 7 days).

  • updated - Get all orders that have been updated in a specific time window (of up to 7 days). An update is either a modification to an existing order or a change in status.

  • orders - Get one or more specific orders.

You must specify currency. This value will be used in the response as the booker currency, and as the currency used for commission values.

All other fields are optional.

Note the following:

  • You can return details about orders placed up to a year ago.

  • The response can contain a maximum of 50K orders (total over all pages). If you need to return more than this number, split the request into multiple requests with smaller time windows, so that each request returns less than 50K orders.

  • Details of any update to an order are normally available to the /orders/details/* endpoints shortly after the update takes place. Exceptionally, details may not be available for up to two hours after an update.

Response

For each matching order, the response returns the following:

  • Basic details about the order, such as its unique id, when it was created, and when it was last updated.

  • Information required for different tasks: affiliate id, booker details, commission_details, loyalty_reward, price, and status.

Note the following:

  • The address, email, name and telephone fields in the booker object contain Personally Identifiable Information (PII). Consequently, these fields are only returned if the calling partner is authorised to see this information.

  • status is also shown by /orders/details/accommodations, at both accommodation and product level. If individual products have different status values, the most appropriate value is used for the status value of the accommodation and order.

    For example, if one room in the order has the value cancelled but another has the value stayed, the stayed value is used for the accommodation and the order.

  • commission shows the actual amount if this is available, or the estimated value otherwise.

  • loyalty_reward is only shown for orders that have a loyalty reward associated with them.

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"
},
...

/orders/details/accommodations

How to 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 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 a year ago.

Response

For each order, the response returns the following information about the accommodation:

  • The id of the associated order, and the checkin and checkout dates, commission, price and status.

  • The cancellation_details, showing the cancellation fee that was charged, and when it was charged. (This field is null if the order has not been cancelled.)

  • The accommodation_details, showing the details about the accommodation such as name, email, location, telephone.

  • Details about each product included in the order, such as:

    • The guest name that the room is allocated to, and the exact alloction of guests.

    • cancellation policies, room id and room_details such as room name, status, and a breakdown of the price.

  • The accommodation id, which you can use to obtain more information about the property from the /accommodations/details endpoint.

  • A pin_code, which guests can use to modify or cancel bookings, or to prove their identity when contacting customer support.

Note also the following:

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

  • The email and name fields in the products.guests object contain Personally Identifiable Information (PII). Consequently, these fields are only returned if the calling partner is authorised to see this information.

  • A pin_code is only returned if the order was made through the Demand API, using the /orders/create endpoint.

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

Example - Retrieve affiliate commission

You need to report the commission due to each of your affiliates for new orders in the last week:

  1. Call /orders/details and specify the created_date, currency and maximum_results fields.
{
    "created" : {
        "from": "2023-08-23T00:00:00+00:00",
        "to": "2023-08-29T00:00:00+00:00"
    },
    "currency": "GBP",
    "maximum_results": 100
}
  1. Check whether each returned order has an associated affiliate_id, and whether it has earned any commission.
...
{
     "id": "xxxxxxxx",
     ...
     "affiliate": xxxxxx,
     ...
     "commission": {
         "actual_amount": 17.5,
         "estimated_amount": null
     },
     ...
     "currency": {
         "accommodation": "EUR",
         "booker": "GBP"
     },
     ...
  1. 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.