Check order 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:

/orders/details/

Use this endpoint to retrieve general information about the order(s) for specific dates range.

Define your request

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

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

2. 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).

3. Specify the currency

   • This value is mandatory as it will be used in the response as the booker currency, and as the currency used for commission values.
   • The full list of currencies can be obtained by calling common/payments/currencies

4. You can then optionally specify the other fields.

Examples of requests

For order creation date

You can get 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"
}
}

For trip starting/ ending date

In this example, this request returns the orders associated to a trip that 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:

  • The order unique id number.
  • reservation id: Useful for cancellations or customer service support.
  • affiliate id to easily identify the partner.
  • Dates on when it was created, and when it was last updated.

• The booker object contains 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: This field is only shown for those orders that have a loyalty reward associated to them.

• status: This value indicates whether the order has been cancelled, booked, etc. These are the available statuses:

  • "Booked"
  • "Cancelled"
  • "Cancelled_by_accommodation"
  • "Cancelled_by_guest"
  • "no-show"
  • "stayed"

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

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.

/orders/details/accommodations

Use this endpoint to retrieve details of an accommodation 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.

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 order

• The accommodation id - You can use it to obtain more information about the property from the /accommodations/details endpoint.

• The accommodation_details, showing information such as name, email, location, telephone of the accommodation.

• Information about the accommodation order such as:

  • 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 checkin and checkout dates and, commission breakdown.

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

    Note

    A pin_code is only returned if the order was made through the Demand API by means of the /orders/create endpoint.

  • A breakdown of the price.

  • The stay_probability - Score that predicts the likelihood of a traveller's intent to stay, based on internal calculations. A score of 0 indicates the highest likelihood of cancellation, while a score of 1 represents the highest likelihood of the traveller staying. Note: This score may not always be available.

• 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 and email that the room is allocated to.

    Note

    These 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 and room_details such as room name and status

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

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.