Pricing in /orders endpoints

Discover how to retrieve and display product pricing information on orders pages effectively.

Pricing details in the order/preview

Use the /orders/preview endpoint to check the detailed pricing information for the products included in the response, before proceeding the order.

Your application must present this information to travellers in a clear and consistent manner, adhering to all relevant laws and regulations, enabling them to make informed decisions before placing their orders.

Key fields

The product.price object in the /orders/preview response includes the following key components:

Currency representation

All prices and amounts are displayed in both the accommodation_currency and the booker_currency.

• If currency is not included in the request, the booker_currency value is null.

In the following example, the user is located in England, hence the booker currency defaults to Pounds (GBR).

The accommodation is priced in Euros (EUR) as this is located in Spain so the accommodation currency presents the amount in Euros (EUR).

{
...
"accommodation": {
            "id": xxxxxxxx,
            "currency": {
                "accommodation": "EUR",
                "booker": "GBP"
            },
            "price": {
                "base": {
                    "accommodation_currency": 82.57,
                    "booker_currency": 70.85
                },
                "extra_charges": {
                    "conditional": [],
                    "non_conditional": [
                        {
                            "charge": 21,
                            "total_amount": {
                                "accommodation_currency": 7.43,
                                "booker_currency": 6.38
                            }
                        },
                        {
                            "charge": 22,
                            "total_amount": {
                                "accommodation_currency": 2.00,
                                "booker_currency": 1.72
                            }
                        }
                    ]
                },
                "total": {
                    "accommodation_currency": 92.00,
                    "booker_currency": 78.95
                }

Extra charges

The products.price object offers similar pricing details for each product within the order, including a detailed breakdown of extra charges (including conditional and non conditional)

Charge type ID

All extra charges are grouped by charge type, that is identified by an ID. Examples of extra charges are: VAT, City Tax, etc.

In the following example the extra charge types are identified with these ids: 3, 142, 21 and 22.

          "id": "1000420_95127794_2_0_0",
          "policies": {
            "cancellation": [
              {
                "from": "now",
                "price": {
                  "accommodation_currency": 170,
                  "booker_currency": null
                }
              }
            ],
            "meal_plan": {
              "meals": [],
              "plan": "no_plan"
            }
          },
          "price": {
            "base": {
              "accommodation_currency": 162.98,
              "booker_currency": null
            },
            "extra_charges": {
              "conditional": [
                {
                  "charge": 3,
                  "condition": 30,
                  "mode": "per_stay",
                  "percentage": null,
                  "total_amount": {
                    "accommodation_currency": 10,
                    "booker_currency": null
                  },
                  "unit_amount": null
                }
              ],
              "non_conditional": [
                {
                  "charge": 142,
                  "chargeable_online": false,
                  "mode": "per_person_per_night",
                  "percentage": null,
                  "total_amount": {
                    "accommodation_currency": 6,
                    "booker_currency": null
                  },
                  "unit_amount": {
                    "accommodation_currency": 3,
                    "booker_currency": null
                  }
                },
                {
                  "charge": 21,
                  "chargeable_online": true,
                  "mode": "percentage",
                  "percentage": 9,
                  "total_amount": {
                    "accommodation_currency": 14.67,
                    "booker_currency": null
                  },
                  "unit_amount": null
                },
                {
                  "charge": 22,
                  "chargeable_online": false,
                  "mode": "percentage",
                  "percentage": 7,
                  "total_amount": {
                    "accommodation_currency": 11.41,
                    "booker_currency": null
                  },
                  "unit_amount": null
                }
              ]
            },
            "total": {
              "accommodation_currency": 195.06,
              "booker_currency": null
            }
          },

→ Call the accommodations/constants endpoint to see the full list of charge type IDs so you can identify each one.

For the given example, the accommodations/constants response retrieves:

{
      "id": 3,
      "name": {
        "en-gb": "Restaurant"
      },

        },
    {
      "id": 21,
      "name": {
        "en-gb": "Babysitting/child services"
      },

       {
      "id": 22,
      "name": {
        "en-gb": "Laundry"
      },

      {
      "id": 142,
      "name": {
        "en-gb": "Child safety socket covers"
      },

Best practice:

• Since accommodations/constants endpoint returns static data, we recommend caching the response and refreshing the cache daily.
• This will help reduce traffic to the endpoint and improve response times, ensuring more efficient use of resources.

Chargeable online

The chargeable_online field, located under extra_charges.non_conditional, is present in both the accommodation price summary and the product list price.

• This field indicates whether a specific extra charge, which must be paid unconditionally and included in the total price, is chargeable by Booking.com.

  • Chargeable refers to charges that Booking.com is responsible to process.

• When this field is set to "true", the chargeable amount is included in the response, provided in both the booker and accommodation currencies.

Example - chargeable price

In this example:

• The first non_conditional extra charge with ID 22 (Laundry) is not chargeable online by Booking.com, as it is marked as "false".

• The second non_conditional extra charge with ID 21 (Babysitting/child services) is chargeable online by Booking.com, as is set to "true".

  • The price to be charged online for this extra charge is 11.00.

  • The total amount that Booking.com will charge online is 121.03, out of 125.53.

            },  
                  "price": {  
                      "base": {  
                          "accommodation_currency": 110.03,  
                          "booker_currency": 110.03  
                      },  
                      "extra_charges": {  
                          "conditional": [],  
                          "non_conditional": [  
                              {  
                                  "charge": 22,  
                                  "chargeable_online": false,  
                                  "mode": "per_person_per_night",  
                                  "percentage": null,  
                                  "total_amount": {  
                                      "accommodation_currency": 4.50,  
                                      "booker_currency": 4.50  
                                  },  
                                  "unit_amount": {  
                                      "accommodation_currency": 4.50,  
                                      "booker_currency": 4.50  
                                  }  
                              },  
                              {  
                                  "charge": 21,  
                                  "chargeable_online": true,  
                                  "mode": "percentage",  
                                  "percentage": 10.00,  
                                  "total_amount": {  
                                      "accommodation_currency": 11.00,  
                                      "booker_currency": 11.00  
                                  },  
                                  "unit_amount": {  
                                      "accommodation_currency": null,  
                                      "booker_currency": null  
                                  }  
                              }  
                          ]  
                      },  
                      "chargeable_online": {  
                          "accommodation_currency": 121.03,  
                          "booker_currency": 121.03  
                      },  
                      "total": {  
                          "accommodation_currency": 125.53,  
                          "booker_currency": 125.53  
                      }  
                  },  
                  "room": 438312701  
              }  
  

Important considerations

This field is only relevant when Booking.com is managing the payments using online payment timings such as pay_online_later or pay_online_now.

• For these timings, certain charges will be marked as chargeable, while others will not.
• The non-chargeable charges must be paid directly at the property.

How to display price information

On an order preview page

Prices, charges and currency

• Display the price of the order using the price.total price.

• Clearly indicate whether the price includes taxes and charges, and whether any additional charges may apply.

• Display details of each non_conditional charge that applies to the order (using the data from the prices.extra_charges.non-conditional object). Do not combine charges into your own categories.

• If the booker_currency and accommodation_currency are different:

  • Show the price clearly in both currencies.
  • Clearly state that if the exchange rate changes before the traveller completes the booking, they will pay a different price to the one shown.

For example:

Deals

If you display a price that is discounted because a deal is available, you must show details of the deal. For example:

Conditional or incalculable charges

If the order includes either conditional charges, or incalculable non_conditional charges:

• Show each charge explicitly with an appropriate explanation.
• Indicate clearly that the price is not the total price.

For example:

On an order details page

Commissionable price

Price over which Booking.com would calculate Managed affiliate partner commission. This price is the sum of net_price and all commissionable extra charges.

• This price is not the total price as it may not contains all the extra charges.
• There are no simple rule to explain which charges are commissionable.

Example:

Different pricing information across endpoints

The pricing information returned by the /orders/preview endpoint differs slightly from that provided by the /accommodation/ endpoints in the following ways:

Price variations

There may be slight discrepancies between the pricing presented in the /accommodations/availability response and that included in preview/order endpoint.

When discrepancies occur:

• The price returned by the preview response should be the one utilised during the booking process.
• It is advisable to notify travellers about these variations.

Example of price discrepancy

Below are examples of two responses with minor price differences:

                "price": {  
                    "base": 8485200.18,  
                    "book": 9622217.00,  
                    "extra_charges": {  
                        "conditional": [],  
                        "excluded": [],  
                        "included": [  
                            {  
                                "charge": 1,  
                                "mode": "percentage",  
                                "percentage": 5.00,  
                                "total_amount": 424260.01,  
                                "unit_amount": null  
                            },  
                            {  
                                "charge": 21,  
                                "mode": "percentage",  
                                "percentage": 8.00,  
                                "total_amount": 712756.81,  
                                "unit_amount": null  
                            }  
                        ]  
                    },  
                    "total": 9622217.00

In this case, the price discrepancy between the two endpoints is 0.20 cents.