Step 9 - Create charges

Use the Charges API to create and update taxes and fees that apply at the property level and room level, specify their configuration details, and set up different configurations for different dates.

Prerequisites

You must have the following:

A property ID by completing step 2 successfully.
A unit ID by completing step 3 successfully.

Create charges

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.

Path parameters

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

Element	Description	Type	Required/ Optional	Notes
`property_id`	Specifies the unique ID of the property.	integer	required

Request body parameters

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

All parameters are required unless otherwise noted.

Element	Description
`property_charges`	Charges that apply across the property. At least one charge must be present between `property_charges` and `room_charges`.
> `charge_key`	Contains the attributes that uniquely identifies a charge. If you change the value of a field within the charge key, you are not modifying an existing charge's value but creating a separate charge.
>> `type`	Specifies the charge type. For a list of supported charge types, see the meta endpoint.
>> `guest_origin`	Specifies the guest origin as specified by guests when they make the booking.
>> `travel_purpose`	Specifies the travel purpose as specified by guests when they make the booking. Possible values are: `ANY`, `LEISURE`, `BUSINESS`.
> `charge_periods`	Contains the various configurations for the charge through time.
>> `applicable`	Contains the date range for this charge period.
>>> `from`	Specifies the start date for this charge period. It may be in the past if it is the current active charge. Uses the ISO 8601 date format (`YYYY-MM-DD`) and is relative to the timezone of the property.
>>> `to`	[Optional] Specifies the end date for this charge period (inclusive). The date is relative to the property's timezone. If null or undefined, the current charge period extends forever. Uses the ISO 8601 date format (`YYYY-MM-DD`).
>> `configuration`	[Optional] Contains the charge configuration for this period. If specified as null, it clears the charge for the specific period.
>>> `amount`	Contains details about the charge price.
>>>> `value`	Specifies the value of the charge. Required unless mode is `INCALCULABLE` Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency. Any value set for an `INCALCULABLE` charge is ignored.
>>>> `base`	Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. Required when mode is `PERCENTAGE` (otherwise rejected). See the section on Understanding Percentage charges.
>>>> `mode`	Specifies the mode used for this charge. For possible values, see Understanding Charge modes.
>>>> `excluded`	Specifies if the charge is included or excluded from the room rate. This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API.
`room_charges`	Contains the room specific charges. Overrides the same charge specified at the property level. Can be an empty array. Note that `CITYTAX` / `VAT` / `TAX` should be applied at the property level and not at the room level. If specified, the API ignores setting these at the room level.
> `room_id`	Specifies the Room ID the charges apply to.
> `charges`	Contains the attributes charges apply to.
>> `charge_key`	Contains the attributes that uniquely identifies a charge. If you change the value of a field within the charge key, you are not modifying an existing charge's value but creating a separate charge.
>>> `type`	Specifies the type of charge.
>>> `guest_origin`	Specifies the guest origin as specified by guests when they make the booking.
>>> `travel_purpose`	Specifies the travel purpose as specified by guests when they make the booking. Possible values are: `ANY`, `LEISURE`, `BUSINESS` When determining which charge to use at checkout, the narrowest/most specific charge key is used. For example, if a `LEISURE` guest books at a property that has both an `LEISURE` and `ANY` charge key (with the same charge type), only the `LEISURE` charge is applied.
>> `charge_periods`	Contains the various configurations for the charge through time.
>>> `applicable`	Contains the date range for this charge period. Dates are inclusive and must not overlap.
>>>> `from`	Specifies the start date for this charge period. It may be in the past if it is the current active charge. Uses the ISO 8601 date format (`YYYY-MM-DD`) and is relative to the timezone of the property.
>>>> `to`	[Optional] Specifies the end date for this charge period (inclusive). The date is relative to the property's timezone. If null or undefined, the current charge period extends forever. Uses the ISO 8601 date format (`YYYY-MM-DD`).
>>> `configuration`	[Optional] Contains the charge configuration for this period. If specified as null, it clears the charge for the specific period.
>>>> `amount`	Contains details about the charge price.
>>>>> `value`	Specifies the value of the charge. Required unless mode is `INCALCULABLE`. Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency. Any value set for an `INCALCULABLE` charge is ignored.
>>>>> `base`	Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. Required when mode is `PERCENTAGE` (otherwise rejected). See the section on Understanding Percentage charges.
>>>>> `mode`	Specifies the mode used for this charge. For possible values, see Understanding Charge modes.
>>>> `excluded`	Specifies if the charge is included or excluded from the room rate. This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API.

Request body example

The following is a request body example:

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2025-09-10"
          },
          "configuration": {
            "amount": {
              "value": 20.00,
              "base": [],
              "mode": "PER_STAY"
            },
            "excluded": true
          }
        }
      ]
    },
    {
      "charge_key": {
        "type": "CITYTAX",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2025-09-10"
          },
          "configuration": {
            "amount": {
              "value": 20.00,
              "base": [],
              "mode": "PER_PERSON_PER_NIGHT"
            },
            "excluded": true
          }
        }
      ]
    }
  ],
 "room_charges": [
        {
            "room_id": "1479536101",
            "charges": [
                {
                    "charge_key": {
                        "type": "DESTINATIONTAX",
                        "guest_origin": "ANY",
                        "travel_purpose": "LEISURE"
                    },
                    "charge_periods": [
                        {
                            "applicable": {
                                "from": "2025-09-10"
                            },
                            "configuration": {
                                "amount": {
                                    "value": 1.99,
                                    "base": [],
                                    "mode": "PER_PERSON_PER_NIGHT"
                                },
                                "excluded": false
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Response body example

The following is a successful response body example:

{
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "XXXXXXXXXXXXXXXXXXXXX"
    }
}