# Run order reports

**Use the /orders/details endpoint to retrieve reporting and reconciliation data for existing orders across supported travel services from a single endpoint. It provides a consolidated view of order, pricing, payment, commission, attribution, and service-specific booking data without requiring separate requests to each travel vertical.**

## /orders/details/

The /orders/details endpoint is designed for reporting, synchronisation, and operational workflows across multiple travel services.

Typical use cases include:

* Financial reconciliation and reporting.
* Attribution tracking and performance analysis.
* Synchronising Booking.com order data with internal systems.
* Validating booking, payment, and commission information.
* Retrieving consolidated order information across supported travel services.


Use /orders/details when you need consistent reporting or operational data across multiple travel services in a single response.

### When to use this endpoint

Use /orders/details when you need to:

| 
| ✓ | Generate consolidated reports across multiple travel services from a single request. |
| ✓ | Reconcile bookings, payments, and commissions. |
| ✓ | Synchronise order changes directly with your internal systems. |
| ✓ | Track attribution using partner labels. |
| ✓ | Retrieve booking information for one or more existing orders. |


If you require detailed post-booking operations for a specific travel service (for example, cancellations or modifications), use the corresponding /orders/details/{service} endpoint instead.

## How it works

Call [orders/details endpoint](/demand/docs/open-api/3.2/demand-api/orders/orders/details) using one supported filter type.

Only one filter type can be used per request. Combining identifier filters with date filters (for example orders and created) is not supported.

### Supported filters

| Filter type | Description |
|  --- | --- |
| Identifiers | Retrieve specific orders or reservations.* `orders` (max 100)
* `reservations` (max 100)

 |
| Date-based reporting | Retrieve orders matching reporting windows.* `created` (max 7 days)
* `updated` (max 7 days)
* `start` (checkin, pickup)
* `end` (checkout, dropoff)

 |


Date filter limits
* Date ranges **cannot exceed 7 days**.
* created and updated filters can only retrieve orders from the **previous 12 months**.
* Updates may take **up to 2 hours** to become available.
* Dates must use ISO 8601 format. See the Data conventions guide for details.


### Required parameters

All requests require:

* `currency` - three-letter ISO 4217 code.


The only exception is requests using `page`, where the pagination token already preserves the original query context.

See [Conventions](/demand/docs/development-guide/code-conventions#currency-codes) and [Pagination](/demand/docs/development-guide/pagination) guides for details.

### Optional parameters

You can also include:

* `extras` — Request additional information (Currently supports `payment`)
* `services` — Restrict results to one or more travel services.
* `maximum_results` — Limit the number of results returned.
* `sort.by` and `sort.direction` — Sort results by creation or update date and specify the direction (ascending/descending).


#### Filtering by travel services

The `services` parameter acts as an inclusion filter.
Use the optional `services` field to limit results to specific travel services, for example:

`"services": ["accommodations", "cars"]`

**Default behaviour when services is omitted:**

The default behaviour depends on the filter type:

* Identifier-based requests (orders or reservations): if services is omitted, only accommodation orders are returned.
* Date-based requests (created, updated, start, or end): if services is omitted, all travel services available to your account are returned.


To ensure predictable behaviour, explicitly specify services whenever you want to control which travel services are included.

### Important notes for developers

* Do not assume ID-based requests return all verticals.
* Use date-based filters when building:
  * dashboards.
  * reconciliation pipelines.
  * CRM synchronisation.
* Always explicitly set services when you need a reduced dataset in reporting flows.
* Expect different payload shapes depending on the specific travel service returned (e.g., accommodations vs cars).


## Common use cases

### Retrieve specific reservations

> **Scenario:** *Retrieve payment, pricing, or commission details for known reservations.*


```json
{
  "currency": "EUR",
  "reservations": [
    "2321873123",
    "4666773123"
  ],
  "sort": {
    "by": "updated",
    "direction": "descending"
  },
  "extras": [
    "payment"
  ]
}
```

### Retrieve recently created orders

> **Scenario:**  *Synchronise newly created accommodation and car bookings for a certain period.*


```json
{
    "created": {
      "from": "2025-12-01T02:00:00+00:00",
      "to": "2025-12-07T02:00:00+00:00"
    },
    "currency": "EUR",
    "services": ["cars", "accommodations"],
    "extras": [
      "payment"
    ]
  }
```

#### Retrieve all orders ended from a date for all services

> **Scenario:**  *Get all the orders across all travel services (available to the partner) that ended from 05 June 2026 to sync with an internal Customer Relationship Management tool (CRM).*


```json
{
    "end": {
      "from": "2026-06-05T02:00:00+00:00",
      "to": "2026-06-08T02:00:00+00:00"
    },
    "currency": "EUR",
    "sort": {
      "by": "updated",
      "direction": "descending"
    },
    "extras": [
      "payment"
    ]
  }
```

### Building synchronisation jobs

To build incremental sync logic for regularly updating systems:

* Use `created.from` and `created.to` to retrieve newly created orders.
* Use `updated` with small rolling windows (for example, every 30–60 minutes) to detect changes to existing orders.
* Use pagination (`metadata.next_page`) when processing large result sets.


See the [Order details - use cases](/demand/docs/orders-api/order-details-examples) for more examples.

## Response overview

Each returned order contains common reporting fields regardless of travel service.

|  Field | Description |
|  --- | --- |
| `id` | Order identifier |
| `affiliate` | Affiliate ID |
| `booker` | * Containing Personally Identifiable Information (PII) (returned only if authorised)
* `address`, `email`, `name` and `telephone`, `language`, `platform` and `travel_purpose`.

 |
| `created`/ `updated` | Date when the order was created and last updated. |
| `commission` | Commission details (actual and estimated). |
| `currencies` | * `booker` - Currency shown to the booker.
* `product` - Currency in which the product is priced.

 |
| `label` (v3.2) | Custom partner string for tracking and attribution. |
| `loyalty_reward` | Displays loyalty rewards details (if applicable), such as amount, eligibility, and fulfilment date. |
| `payment` | Payment details (only when `extras=["payment"]`). |
| `price` | Total and commissionable amounts. See [Pricing guide](/demand/docs/accommodations/prices-accommodations) |
| `status` | Aggregated order status (booked, cancelled, no-show, etc) |
| `start` / `end` | Aggregated service dates. |
| Travel service blocks | Service-specific booking data. |
| `metadata.next_page` | Token used to retrieve the next page via the `page` filter. |


### Payment information

When `extras` includes `payment`, the response may contain:

* `method`
* `timing`
* `paid` → completed transactions.
* `pending`→ upcoming or scheduled transactions.


Accommodation payments may also include:

* `authorisation_form`
* `receipt_url`


See the [Payments section](/demand/docs/payments/overview) for details

### Travel service objects

Each order may contain one or more travel service objects depending on what was booked.

Possible service objects include:

* `accommodations`
* `cars`
* `flights`
* `attractions` (v3.2)
* `taxis` (v3.2)


Services that are not part of the order are returned as `null` (or omitted according to the response schema).

### Supported travel services

|  Travel service | v3.1 | v3.2 | Key information |
|  --- | --- | --- | --- |
| `accommodations` | ✓ | ✓ | Includes reservation details, property information, guest counts, inventory type, and stay probability. |
| `cars` | ✓ | ✓ | Includes reservation information, pickup and drop-off locations, and payment timing. |
| `flights` | ✓ | ✓ | Includes reservation information and itinerary details, including departure and arrival airports and times. |
| `attractions` | ✗ | ✓ | Includes reservation information together with attraction name and location. |
| `taxis` | ✗ | ✓ | Taxi orders may contain multiple legs. |


#### Taxi orders

Taxi orders may contain multiple legs.

* The order-level `price`, `start`, `end`, and `status` are aggregated across all legs.
* All legs belonging to the same taxi order share the same `reservation` identifier.
* Each leg has its own `leg` identifier and lifecycle.
* If different legs have different statuses, the order-level status may be `unknown`.


For accurate tracking and reporting, always inspect `taxis[].status` and the individual taxi legs.

### Minimal response example

```json
{
  "request_id": "req_123",
  "data": [
    {
      "id": "880045112233",
      "affiliate": 111111,
      "status": "booked",
      "start": "2026-03-10T08:00:00Z",
      "end": "2026-03-12T10:00:00Z",
      "currencies": {
        "booker": "EUR",
        "product": "EUR"
      },
      "price": {
        "total_price": {
          "booker_currency": 420,
          "product_currency": 420
        }
      },
      "accommodations": {
          "reservation": "ABC123"
        }
    }
  ],
  "metadata": {
    "next_page": null,
    "total_results": 1
  }
}
```

### Example – Attraction reservation details (v3.2)

```json
{
  "order_id": "509430129718801",
  "attractions": {
    "reservation": 567890123,
    "name": "Eiffel Tower Guided Tour",
    "location": {"city": "Paris", "country": "fr"}
  },
  "affiliate": 111111,
  "booker": {
    "address": {"city": "Amsterdam", "country": "nl"},
    "email": "janedoe@booking.com",
    "name": {"first_name": "Jane", "last_name": "Doe"},
    "platform": "desktop",
    "telephone": "+100000001",
    "language": "en-gb",
    "travel_purpose": "leisure"
  },
  "commission": {"actual_commission_amount": {"booker_currency": 5.0, "product_currency": 6.0}},
  "currencies": {"booker": "EUR", "product": "EUR"},
  "price": {"commissionable_price": {"booker_currency": 50, "product_currency": 60}, "total_price": {"booker_currency": 55, "product_currency": 66}},
  "status": "booked",
  "start": "2026-07-10T09:00:00+00:00",
  "end": "2026-07-10T12:00:00+00:00",
  "created": "2025-11-28T02:00:00+00:00",
  "updated": "2025-11-28T02:00:00+00:00"
}
```

### Example – Taxi reservation details (v3.2)

```json
{
  "request_id": "03fr9fz702lmnop12w34x5y6z",
  "data": [
    {
      "id": "709430129718801",
      "affiliate": 333333,
      "taxis": [
        {
          "reservation": "TX987654321",
          "pickup_location": { "city": "Paris", "country": "fr" },
          "dropoff_location": { "city": "Lyon", "country": "fr" },
          "start": "2026-07-10T09:00:00+00:00",
          "end": "2026-07-10T14:00:00+00:00"
        },
        {
          "reservation": "TX987654322",
          "pickup_location": { "city": "Lyon", "country": "fr" },
          "dropoff_location": { "city": "Marseille", "country": "fr" },
          "start": "2026-07-12T10:00:00+00:00",
          "end": "2026-07-12T15:00:00+00:00"
        }
      ],
      "booker": {
        "name": { "first_name": "Bob", "last_name": "Brown" },
        "email": "bob.brown@example.com",
        "telephone": "+33123456789",
        "language": "fr",
        "platform": "mobile",
        "travel_purpose": "leisure",
        "address": { "city": "Paris", "country": "fr" }
      },
      "commission": {...},
      "currencies": { "booker": "EUR", "product": "EUR" },
      "price": {
        "commissionable_price": { "booker_currency": 375, "product_currency": 400 },
        "total_price": { "booker_currency": 400, "product_currency": 425 }
      },
      "start": "2026-07-10T09:00:00+00:00",
      "end": "2026-07-12T15:00:00+00:00",
      "status": "booked",
      "created": "2026-02-01T08:00:00+00:00",
      "updated": "2026-02-02T10:00:00+00:00"
    }
  ],
  "metadata": {...}
}
```

See all travel services examples in [Orders details - Use cases guide](/demand/docs/orders-api/order-details-examples).

## Error handling

While the /orders/details endpoint follows [general API error conventions](/demand/docs/support/error-handling/about-errors), there are several endpoint-specific conditions to be aware of:

| Scenario | Cause | Suggested resolution |
|  --- | --- | --- |
| **Empty 200 OK response** | No orders match the request filters. | Check that the date range, service types, and other filters correspond to existing data. |
| **400 – Invalid date filters** | Illogical or malformed dates (e.g., `start_date` > `end_date`) | Ensure dates are in ISO 8601 format and logically ordered. |
| **400 – Incompatible service types** | Mixed or unsupported service types in a single request. | Limit to supported service type combinations or query them separately. |
| **403 – Restricted PII data** | Expecting guest data without proper authorisation. | Confirm PII access has been granted and the proper scopes are used. |
| **404 – Order not found** | Order ID doesn’t exist or isn’t accessible to the account. | Make sure the order belongs to your account. |
| **Performance issues** | Large reporting windows. | Use pagination and segment queries into smaller date intervals. |


## When to use service-specific endpoints

Use /orders/details for reporting, reconciliation, and synchronisation.

Use /orders/details/{service} endpoints instead, when you need travel-service-specific functionality, including:

* Managing cancellations.
* Processing modifications.
* Retrieving detailed booking information.
* Supporting customer service workflows.
* Performing service-specific post-booking operations.


These endpoints provide additional information specific to each travel vertical and are recommended for operational booking management.

### Travel service details guides

Curious to know more?
* See the [Order details use cases](/demand/docs/orders-api/order-details-examples) for advanced scenarios.
* Learn how to track attribution with the [Labels and attribution guide](/demand/docs/orders-api/labels-attributions).
* See the [Pagination guide](/demand/docs/development-guide/pagination) for best practices handling large results sets.