Last updated

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 ActionUse it to...
/orders/detailsReturns 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/accommodationsRetrieves 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/carsRetrieves 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/flightsReturns 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.

Important

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

Filter orders

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.

    • created - Get all orders that have been created within a defined date range.

    • updated - Retrieve orders that were updated within a specific period. Updates can include order modifications or status changes.

      Updates are generally reflected in the response shortly after they occur, but it can take up to 2 hours.

    • start - Retrieve orders associated with trips that started within the defined period (e.g., check-in date).

    • end - Get all orders linked to trips that has ended within the specific period (e.g., check-out date).

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

Currency

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.

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.

Important

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.

    • reservation id - Use it for cancellations or customer service enquiries.

    • affiliate id - To easily identify the partner.

    • Dates on when it was created, and when it was last updated.

    • Currency - This is the currency applied to the disclosed amounts.

  • The booker object containing Personally Identifiable Information (PII): address, email, name and telephone

The PII fields are only returned if you are authorised to see this information.

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

Example:

    },
  "commission": {
    "actual_amount": 17.5,
    "estimated_amount": null
  },

  • 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 Prices in orders 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.

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

    Note

    You 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 name and email to 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_id is 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_id enables 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 - Get the data for the specified reservation(s), when you do not have an order id

    Note

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

    Note

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

Curious to know more?
Previous page
Next page