ORDERS
/
Check order details

Check order details

Use the /orders/details/ endpoints to get information about travel services orders. This enables you to perform various post-booking tasks.

/orders/details/

The /orders/details/ endpoint provides access to general information about accommodation and other travel services (such as car rentals) within specific orders, over a defined date range.

You can use this endpoint to perform post-booking tasks, including retrieving commission values, checking cancellation or no-show statuses, and managing loyalty and rewards programmes, among others.

Endpoint
Action
Use it to...
/orders/detailsReturns basic information about the order(s).✓ Check orders created or updated on a certain period.

✓ View trips that started or ended within a specific date range (e.g., check-in/check-out dates), enabling management of loyalty and rewards programmes.

✓ Check details for different travel services within an order (e.g., car rentals, accommodation).
Important
  • By default, this endpoint returns information about accommodation orders. To retrieve details about other travel services (such as car rentals or flights) included in the order, you must specify the service in your request.
  • Note there might be a delay of between 5 minutes and 1 hour between order creation, and orders/details response.

Defining your request

Key parameters

To filter the orders you want to retrieve, you must specify the currency, and either a list of order ids, or a date range:

Parameter
Description

Currency

Specify the currency for the response, which will be used for both the booker currency and for commission values.

Use the common/payments/currencies endpoint to see the full list of supported currencies.

OrdersYou can pass a single order ID or a list of order IDs to retrieve information about specific orders.
Date rangeAlternatively, you can specify the date range ("from" and "to") to retrieve orders within a defined period:
  • created- Retrieve orders created within the specified period.
  • updated- Retrieve orders updated within a specific period. Updates may include modifications or status changes.
  • start- Retrieve orders associated with trips that started within the defined period (e.g., checkin date).
  • end - Get all orders linked to trips that have ended within the specific period (e.g., checkout date).
Date range constraints
  • Orders can only be returned if they were created or updated within 1 year of the call date.
  • The date range for filters ("from" - "to") cannot exceed a 7-day interval.
  • Use the ISO 8601 format (YYYY-MM-DD).
  • Updates are generally reflected in the response shortly after they occur, but it can take up to 2 hours since the order creation.

Optional parameters

maximum_resultsSet the limit on the number of results returned.
sort.bySort results by creation or update date and specify the direction (ascending/descending).

Example - Request with order ids

This example demonstrates a request with a list of order IDs:

{
    "currency": "EUR",
    "orders": [
      "4859251752",
      "4859236984"
    ],
    "sort": {
      "by": "updated",
      "direction": "descending"
    }
  }''

Handling orders/details responses

Each order response contains the following fields:

Parameter
Description
order idUnique identifier for the order.
reservation idLinked to the travel service the order includes. Each order may have different reservation IDs if multiple services are booked (e.g., accommodation and car rental). This is needed for cancellations or customer service enquiries.
affiliate idIdentifies the partner so that commission can be attributed.
DatesIncludes created, start or end dates (depending on the request) as well as the last updated date.
CurrencyThe currency used for the disclosed amounts.
bookerContaining Personally Identifiable Information (PII) - address, email, name and telephone
commissionDisplays the actual commission amount if available, or an estimated value if not.
loyalty_rewardDisplays loyalty rewards details, such as amount, eligibility, and fulfilment date. This field is only visible for orders with a loyalty reward.
priceIncludes both the commissionable and total amounts. For more details, refer to the Accommodation pricing section.
statusIndicates whether the order is: booked, cancelled (by accommodation or guest), stayed, or no-show.

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

Considerations

Multi-room statuses

If individual products within an order have different statuses, the "stayed" status takes precedence and is applied to both the accommodation and order statuses.

For example, if one room in an order is marked as "cancelled" while another is marked as "stayed," the "stayed" status will be used for both the accommodation and order.

The status is also displayed in the /orders/details/accommodations endpoint response, both at accommodation and product level.

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.

Example - Response with 2 orders details

The response for two orders is shown below:

  • The "reservation" id in both orders is related to the accommodation booking.
  • The car rental and flight reservation id appears as null", as these services have not been booked in the order.
{
  "request_id": "01jqrj9pd5esn3hg91dv0yj8vy",
  "data": [
    {
      "id": "4859251752",
      "accommodations": {
        "reservation": 4859251752
      },
      "affiliate": 956509,
      "booker": {
        "address": {
          "city": "Amsterdam",
          "country": "nl"
        },
        "email": "testreservations@booking.com",
        "name": {
          "first_name": "Pega",
          "last_name": "Test Booker"
        },
        "language": "en",
        "platform": "unknown",
        "telephone": "+31000000000",
        "travel_purpose": "unknown"
      },
      "cars": null,
      "flights": null,
      "created": "2025-02-04T10:24:59+00:00",
      "currency": "EUR",
      "price": {
        "commissionable": 0,
        "total": 276.94
      },
      "status": "booked",
      "updated": "2025-02-04T10:25:00+00:00"
    },
    {
      "id": "4859236984",
      "accommodations": {
        "reservation": 4859236984
      },
      "affiliate": 956509,
      "booker": {
        "address": {
          "city": "Amsterdam",
          "country": "nl"
        },
        "email": "rezmonkey-reservations-internal+56368-250204083641-116@booking.com",
        "name": {
          "first_name": "Pega",
          "last_name": "Test Booker"
        },
        "language": "en",
        "platform": "unknown",
        "telephone": "+31612345678",
        "travel_purpose": "unknown"
      },
      "cars": null,
      "created": "2025-02-04T10:24:52+00:00",
      "currency": "EUR",
      "flights": null,
      "payment": {
        "accommodations": {
          "authorization_form": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=anNvbl9hbXM0XzY4Yjg4NWI4LTM1MWUtNGRhOC1hNGVlLTZkMDZmODk5NTI1ZA%3D%3D&lang=en-us",
          "receipt_url": null,
          "reservation": 4859236984
        },
        "method": "card",
        "paid": null,
        "pending": null,
        "timing": "pay_at_the_property"
      },
      "price": {
        "commissionable": 0,
        "total": 276.94
      },
      "status": "booked",
      "updated": "2025-02-04T10:24:53+00:00"
    }
  ],
  "metadata": {
    "next_page": null,
    "total_results": 2
  }
}

More examples

Example 1 - Orders per creation dates

This example retrieves orders created between 1st and 4th March 2025, sorted by the update date.

This example request would return all the orders created from March 1st, to 4th, 2025 with the results sorted by updated date.

Example:

{
  "created": {
    "from": "2025-03-01T02:00:00+00:00",
    "to": "2025-03-04T02:00:00+00:00"
  },
  "currency": "EUR",
  "sort": {
    "by": "updated",
    "direction": "descending"
  }
}

Use the format: YYYY-MM-DDT02:00:00+00:00. Do not forget to add times.

Example 2 - Orders per trip starting/ ending date

In this example, this request returns the orders associated to a trip that starts between the 1st March 2025 and the 7th.

  • It includes all the checkings done on March 1, 2, 3, 4, 5, 6 and 7, 2025.
  • Use the YYYY-MM-DD format, and do not include times.
{
  "start": {
    "from": "2025-03-01",
    "to": "2025-03-07"
  },
  "currency": "EUR",
  "maximum_results": 20,
  "sort": {
    "by": "updated",
    "direction": "descending"
  }
}

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 services in the request.

In this case, to retrieve car rental services details in the orders list:

  • Include: "services": ["cars"]
{
  "created": {
    "from": "2025-03-01T02:00:00+00:00",
    "to": "2025-03-07T02:00:00+00:00"
  },
  "currency": "EUR",
  "services": ["cars"],
  "maximum_results": 20,
  "sort": {
    "by": "updated",
    "direction": "descending"
  },
  "extras": [
    "payment"
  ]
}

This request retrieves 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"]

Example 4 - Orders with multiple travel services (Car rental and accommodation)

In case you wish to retrieve orders that include multiple travel services such as car rentals and accommodationas you must specify these two services in the request.

In this case, to retrieve orders with both car rental and accommodations reservations:

  • Include: "services": ["cars", "accommodations"],
{
  "created": {
    "from": "2025-03-01T02:00:00+00:00",
    "to": "2025-03-07T02:00:00+00:00"
  },
  "currency": "EUR",
  "services": ["cars", "accommodations"],
  "maximum_results": 20,
  "sort": {
    "by": "updated",
    "direction": "descending"
  },
  "extras": [
    "payment"
  ]
}

Response examples

Example 1 - Cancelled accommodation reservation

A standard response for a cancelled accommodation order 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"
},

If an accommodation reservation has been cancelled like in this example, we recommend to call the orders/details/accommodation endpoint to check further details about the applicable cancellation policies, status, etc.

Refer to the cancellation guide for more information about this use case.

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

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.

Travel services details in orders

You can also look at the details of a specific travel service as part of an order.

orders/details/accommodation

Use this endpoint to see all the details of an accommodation reservation.

orders/details/cars

Check all the details of the car rental reservation part of an order.

orders/details/flights

Look at the flight reservation details included in an order.

Curious to know more?