Managing Charges

Use the Charges API to:

• Add or update taxes and fees
• Delete taxes and fees
• Retrieve taxes and fees

Add or update taxes and fees

POST
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Before creating or updating a charge, you must identify the charge_key corresponding to the charge you want to create or update.

Use the Charges meta endpoint to retrieve the list of supported charge types and their details.

To create or modify a charge, you must first identify it by the attributes within the charge_key. This includes:

• Charge type
• Guest origin
• Travel purpose

Then for each charge_key you must define the charge periods. These charge periods will contain configuration details for the charge.

Understanding Charge Periods

With the new Charges API, each charge has a timeline of charge periods that have their own configuration.

In the simplest scenario, a charge could be configured with one period that starts today and continues indefinitely. Assuming today is November 1st, 2024 that would look like:

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-11-01"
          },
          "configuration": {
            "amount": {
              "value": 5.00,
              "base": [],
              "mode": "PER_PERSON_PER_NIGHT"
            },
            "excluded": true
          }
        }
      ]
     }
   ], 
  ...
  ...
}       

If you need to support upcoming or seasonal charges, you can specify a charge period with the date range you are interested in. For example the below charge is only configured to apply from December 1st to January 31st.

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-12-01",
            "to": "2025-01-31"
          },
          "configuration": {
            "amount": {
              "value": 5.00,
              "base": [],
              "mode": "PER_PERSON_PER_NIGHT"
            },
            "excluded": true
          }
        }
      ]
    }
   ], 
   ...
   ...
}    

Finally, when you make updates to a charge, the API behaves as follows:

To learn more about the charge periods, see the Charges API specification.

Understanding charge modes

For each charge configuration you can specify one of the following charge modes:

• PER_NIGHT: Applies a charge that is effective per night. For example, for a 2-person on a 3-night stay, the charge is applied three times.
• PER_STAY: Applies a charge that is effective per stay. For example, for a 2-person on a 3-night stay, the charge is applied once.
• PER_PERSON_PER_NIGHT: Applies a charge that is effective per person per night. For example, for a 2-person on a 3-night stay, the charge is applied 5 times.
• PER_PERSON_PER_STAY: Applies a charge that is effective per person per stay. For example, for a 2-person on a 3-night stay, the charge is applied 2 times.
• PERCENTAGE: Applies a percentage of the specified price(s). For example, a 5% city tax of room rate.
• INCALCULABLE: For charges that can only be determined after the stay based on guest's usage of a property facility.

The following sections provide more information on PERCENTAGE and INCALCULABLE charges with examples.

Percentage charges

Use the PERCENTAGE mode to specify a percentage of a base price. Commonly used for taxes.

The PERCENTAGE mode lets you specify:

• The percentage amount (For example, 5%)
• What to apply it to (room rate, tax and/or other charges)

This flexibility is important because tax rules vary by location. Some places tax only the room rate, while others include property charges too.

Let's look at an example. The below charge will apply a 5% charge on the sum of the room price and any existing property charges, but it does not include locality charges.

{
  "value": 5.0,
  "base": [
    "NET_ROOM_PRICE",
    "PROPERTY_CHARGES"
  ],
  "mode": "PERCENTAGE"
}

Notice that when creating a PERCENTAGE charge you must include what the charge is based on in the configuration.amount.base field. The following combinations of charge bases are allowed:

• NET_ROOM_PRICE
• NET_ROOM_PRICE + PROPERTY_CHARGES
• NET_ROOM_PRICE + LOCALITY_CHARGES
• NET_ROOM_PRICE + PROPERTY_CHARGES + LOCALITY_CHARGES

Finally, to understand the specific charges that can be included when you add PROPERTY_CHARGES or LOCALITY_CHARGES to the charge base, see the Charges API meta endpoint and find the charge types with the charge_category of PROPERTY_CHARGES or LOCALITY_CHARGES.

Incalculable charges

Use the INCALCULABLE charge mode to represent charges that are not calculable prior to the stay. For example, a gas fee which is based on usage. Only a small subset of charge types can use the INCALCULABLE charge mode. To check which charge types can use INCALCULABLE, see the Charges API meta endpoint and reference the allowed_charge_modes field.

When creating an INCALCULABLE charge, configuration.amount.value is not required and is ignored if included in the update or create request.

API validations

In addition to the validations mentioned in the Request body parameters table below and OTA Specification, here are some additional validations to be aware of:

• Updating or deleting charges for specific countries might be restricted due to statutory regulations. If your update attempts to modify one of these charges, the API processes any other charges in the request, but ignores the overwrite-protected charges. The request will still be considered successful (HTTP 200) even if some or all of the charges were ignored due to the overwrite protection. We will notify you via an entry in the warnings array of the response when an update is ignored.
• Some charge types are marked as discontinued in the meta endpoint. Once a charge type is discontinued, it cannot be created or updated, only deleted.
• As a best practice, a charge period's start date (applicable.from) should not be set to before today. If today's date is in the middle of an existing charge period, an update request can use the period's original start date or today's date.
• When creating a charge with a PERCENTAGE configuration, the charge bases should not create a circular reference. A circular reference is when the charge (or a sequence of charges) introduces an infinite loop of percentages. For example, a RESORTFEE is categorized as PROPERTY_CHARGES, so it cannot have a charge base that includes PROPERTY_CHARGES.

To view the open API specification to help create, update or delete taxes and fees, see the Charges endpoint.

Header parameter

Path parameters

The following table describes the elements you must specify in the path:

Request body parameters

The following table describes the elements you can add in the request body:

Request body

The following request body example adds several property charges and one room charge.

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-10-01",
            "to": "2024-11-28"
          },
          "configuration": {
            "amount": {
              "value": 20.00,
              "base": [],
              "mode": "PER_STAY"
            },
            "excluded": true
          }
        }
      ]
    }
  ],
  "room_charges": [
    {
      "room_id": "801185511",
      "charges": [
        {
          "charge_key": {
            "type": "DESTINATIONCHARGE",
            "guest_origin": "ANY",
            "travel_purpose": "LEISURE"
          },
          "charge_periods": [
            {
              "applicable": {
                "from": "2024-09-09"
              },
              "configuration": {
                "amount": {
                  "value": 1.98,
                  "base": [],
                  "mode": "PER_PERSON_PER_NIGHT"
                },
                "excluded": false
              }
            }
          ]
        }
      ]
    }
  ]
}

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Response body elements

The following table describes the response elements:

Removing taxes and fees

Delete a charge for a specific applicable time window or remove it entirely. You can use the same format as creating or updating a charge to identify the charge by the values in the charge_key.

To remove a charge, populate the charge period with a time window specified in applicable, but instead of passing the configuration object, explicitly pass the configuration as null. To delete a charge across all charge periods, pass the null configuration with applicable.from set to today's date and omit applicable.to.

POST
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Header parameter

Path parameters

The following table describes the elements you must specify in the path:

Request body parameters

The following table describes the elements you can add in the request body:

Request body

The following request body example removes the pet fee charge.

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-08-09"
          },
          "configuration": null
        }
      ]
    }
  ],
  "room_charges": []
}

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Response body elements

The following table describes the response elements:

Retrieving charge details

Retrieve the current charges for a property. The API returns the response in the format consistent with the create/update charges request payload.

GET
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Path parameters

The following table describes the elements you must specify in the path:

Response body

{
  "data": {
    "property_charges": [
      {
        "charge_key": {
          "type": "CLEANINGFEE",
          "guest_origin": "ANY",
          "travel_purpose": "ANY"
        },
        "charge_periods": [
          {
            "applicable": {
              "from": "2024-09-09",
              "to": "2024-09-30"
            },
            "configuration": {
              "amount": {
                "value": 18.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          },
          {
            "applicable": {
              "from": "2024-10-01",
              "to": "2024-11-28"
            },
            "configuration": {
              "amount": {
                "value": 20.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          },
          {
            "applicable": {
              "from": "2024-11-29"
            },
            "configuration": {
              "amount": {
                "value": 18.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          }
        ]
      },
      ...
      ...
      ...
      {
        "charge_key": {
          "type": "PETFEE",
          "guest_origin": "ANY",
          "travel_purpose": "ANY"
        },
        "charge_periods": [
          {
            "applicable": {
              "from": "2024-09-09"
            },
            "configuration": {
              "amount": {
                "value": 5.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          }
        ]
      }
    ],
    "room_charges": [
      {
        "room_id": 801185511,
        "charges": [
          {
            "charge_key": {
              "type": "DESTINATIONCHARGE",
              "guest_origin": "ANY",
              "travel_purpose": "LEISURE"
            },
            "charge_periods": [
              {
                "applicable": {
                  "from": "2024-09-09"
                },
                "configuration": {
                  "amount": {
                    "value": 1.98,
                    "base": [],
                    "mode": "PER_PERSON_PER_NIGHT"
                  },
                  "excluded": false
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Response body elements

The following table describes the response elements: