/orders/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.

Example of created request

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

Example of start request

In this example, this request returns the orders associated the trip 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 its unique id and affiliate id, when it was created, and when it was last updated.

• The address, email, name and telephone fields in the booker object contain Personally Identifiable Information (PII).

  Note

  The PII fields are only returned if the calling partner is authorised to see this information.

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

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

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

You can use the affiliate id, booker details, commission_details, loyalty_reward, price, and status to perform different post booking tasks.

/orders/details/accommodations

Use this endpoint to retrieve details of the accommodations 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 or cancel 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, using the /orders/create endpoint.

  • A breakdown of the price.

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

Use case - How to 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
}

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

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