Extra charges calculation and conditions

Understand the extra charges such as city tax, cleaning fees, or VAT and when they apply,how charges are calculated based on charge modes and conditions.

Overview

This guide complements the Accommodation pricing guide, focusing on how extra charges are calculated using the charge_mode field and when conditional charges apply.

This guide helps you:

• Identify when extra charges apply (included, excluded, conditional, or non_conditional).
• Understand how the total amount is calculated using the charge_mode
• Use condition IDs to handle dynamic guest-dependent charges.
• Properly display or disclose charges across your booking flow.

What are extra charges?

Extra charges are additional costs applied to the base accommodation price.

These can include mandatory fees like VAT and city taxes, or optional and conditional charges like cleaning fees, pet fees, or usage-based charges (e.g., spa or internet usage).

These charges can appear differently depending on endpoint context:

Key concepts

Each additional charge is defined in the appropriate category under extra_charges.

These are the fields used to describe each extra charge category, including its purpose, amount, and calculation method.

Example: Accommodations/availability response with extra charges

        "price": {
          "base": 6166.67,
          "book": 7640,
          "extra_charges": {
            "conditional": [
              {
                "charge": 3,
                "condition": 28,
                "mode": "per_stay",
                "percentage": null,
                "total_amount": 200.00,
                "unit_amount": 200.00
              }
            ],
            "excluded": [],
            "included": [
              {
                "charge": 1,
                "mode": "per_stay",
                "percentage": null,
                "total_amount": 40,
                "unit_amount": null
              },
              {
                "charge": 21,
                "mode": "percentage",
                "percentage": 20,
                "total_amount": 1233.33,
                "unit_amount": null
              }
            ]
          },
          "total": 7640
        },

Conditional charges

Conditional charges only apply if specific guest actions or property conditions are met.

When there is a conditional charge, the condition field is displayed under the charge breakdown and identifies the type of condition.

Example:

{
  "extra_charges": {
    "conditional": [
      {
        "charge": 3,
        "condition": 28,
        "mode": "per_stay",
        "percentage": null,
        "total_amount": 25.00,
        "unit_amount": 25.00
      }
    ]
  }
}

Using the Condition ID reference:

• 3 = "Cleaning fee"
• 28 = "A cleaning fee will be charged if you don’t clean before checkout"

The cleaning fee (total_amount) in this example is 25, only paid at the accommodation when checking out if the traveller does not clean the room.

Common conditional charges

• Pet fee - Applied if the guest brings a pet to the stay.

• Smoking fee - Charged if the guest smokes in a non-smoking room.

• Late checkout fee - Applied if the guest checks out later than the agreed time.

• Cleaning fee – If the guest doesn’t clean before leaving.

Condition id reference

Each conditional charge is associated with a condition ID. Use this table to interpret them:

Charge calculation mode

The charge_mode determines how the total of the charge (total_amount) is derived.

Included, and excluded charges

Depending on the user’s country and local tax laws, a charge on a product may appear as included or excluded from the book price.

• included - This value must be part of the displayed price (book price)
• excluded - This charge can be left out of the book price displayed to the the user in pre-booking stages.

Therefore, the book price for the same product, with the same request criteria, may vary depending on the origin of the request.

• The book price represent our (strong) recommendation on how to display a price and the extra charges, for a given booker, based on a mix of the property preferences, overiden by country laws etc.

Non-conditional charges in /orders

When using the /orders/preview and /orders/create endpoints, included and excluded extra charges are consolidated into non_conditional charges.

• The distinction between included and excluded charges is no longer needed in the booking phase, as all extra charges that are mandatory and must be paid regardless of any conditions are grouped under the non_conditional category.
• non_conditional represents the fees that are always applicable to the booking and included in the total price.

(Exemption: incalculable charges are excluded from the total price).

Example: Preview response with extra charges

In the following orders/preview response the extra charge types are identified with these ids: 3, 142, 21 and 22.

{
  "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, // City tax
          "chargeable_online": false,
          "mode": "percentage",  // Applied as % of base price
          "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 get the name of each charge type ID (e.g., charge: 22 = City Tax).

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

Included vs. excluded vs. conditional

Display tips

• Show non_conditional charges before checkout.
• For accurate charge names, map charge IDs using /accommodations/constants endpoint.
  • Cache /accommodations/constants once per day to avoid redundant traffic.
• Conditional charges should be labelled as “might apply” and never added to totals.
• For fluctuating totals (due to currency or rounding), authorise a buffer (e.g. +1%) when processing payments.

Next steps

Looking to implement or optimise pricing display and booking flows? Here are some helpful resources: