# 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


```http
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](/connectivity/docs/charges-api/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:


```json
{
  "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.

How dates are applied to reservations
These dates are inclusive and will be applied to guest reservations based on the checkout date
of a guest's reservation. That is to say if a charge period ends during a guest's stay, the charge
will not be applied. If a charge begins during a guest's stay it will be applied to the full reservation.


```json
{
  "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:

| Existing charge status | API action |
|  --- | --- |
| There are no charge periods for this  `charge_key` | The API creates the charge. |
| There are existing charge periods for this `charge_key`, but they do not overlap with the new `applicable` time window | The API creates the charge and leaves the existing periods unmodified. |
| There are existing charge periods for this `charge_key` and the `applicable` time windows are identical. | The API overwrites the existing configuration with the new configuration provided. |
| There are existing charge periods for this `charge_key` and the `applicable` time windows overlap. | - If the new period fully overlaps the existing period, the API entirely overwrites the existing charge period.  - If only a portion of the dates overlap, splice the existing period. This will leave charge periods before and/or after the updated charge period with the old configuration.  - Leave any non-overlapping charge period unaffected. |


Merging of duplicate charge periods
When consecutive charge periods have identical configurations, the system may consolidate them into a single
continuous period to optimize performance. This merging process happens automatically and does not affect
how the charges are applied to reservations.

To learn more about the charge periods, see the [Charges API specification](/connectivity/docs/openapispecs/charges-api/charges-api-specification/charges-endpoint).

## 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 6 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.


### Read Only Charge Modes

In addition to the Charge Modes described above, there are some read-only charge modes. These may be in use on properties and can appear in the GET response, but their creation and modification is not supported via Charges API.

- `PER_DAY`: Applies a charge that is effective per day. For example, for a 2-person on a 3-night stay, the charge is applied four times (days = number of nights + 1).
- `PER_PERSON_PER_DAY`: Applies a charge that is effective per person per day. For example, for a 2-person on a 3-night stay, the charge is applied 8 times (days = number of nights + 1).
- `VARIABLE`: Applies a charge that is computed dynamically from context. For example, progressive VAT or formula that depend on other computed charges.
- `PERCENTAGE_WITH_CEIL`: Applies a charge that is computed as the minimum of a percentage of a base and a ceiling based cap.


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.


```json
{
  "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](/connectivity/docs/charges-api/charges-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](/connectivity/docs/charges-api/charges-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.

## Additional charge configuration

This section introduces additional configuration options for charges.

### Age-based charge configuration

Charges API allows you to configure modifications to the charge amount based on the age of child travelers. This can be useful to manage age-specific taxes or to discount a charge for children.

#### Age configuration processing

To support backwards compatibility, the age configuration is completely optional and follows these rules:

- **If not provided anywhere in the request or explicitly set to null**: Existing age configurations are preserved. For existing Charges API users, this is the existing behaviour, before age configuration was introduced.
- **If provided for at least one charge in the request**: Updates the age configuration, replacing any existing settings. In the case of an empty array, the configuration is deleted.


This logic operates at the request level, not per individual charge. If you include age configuration data for one charge in the request, but omit it for other charges, the charges without age configurations will have any existing values cleared.

### Using age configuration

Each age configuration entry must specify:

- `multiplier`: The multiplier to apply to the base charge amount
- `lte`: Upper bound of the age range (inclusive) - "less than or equal to"


Age configurations only apply to children
While ages 18 and over are accepted, Booking.com only collects age information for child travelers. An age configuration for an adult will be ignored during the booking process.

See [the API validation section](#api-validations) details on when age configuration can be used.

If there are multiple age configurations, only one multiplier is applied. The configuration with the lowest `child_ages[].le` that includes the child will be used. For example, in the below configuration, only the a 3-year-old child would only receive the 0.2 multiplier.

**Example 1: Children 5 and under pay 20% of the adult charge, Children ages 6-12 pay 50% of the adult charge**


```json
{
  "configuration": {
    "amount": {
      "value": 20.0,
      "mode": "PER_PERSON_PER_NIGHT"
    },
    "child_ages": [
      {
        "multiplier": 0.2,
        "lte": 5
      },
      {
        "multiplier": 0.5,
        "lte": 12
      }
    ],
    "excluded": false
  }
}
```

**Example 2: Children 15 and under do not pay the charge**


```json
{
  "configuration": {
    "amount": {
      "value": 15.0,
      "mode": "PER_PERSON_PER_STAY"
    },
    "child_ages": [
      {
        "multiplier": 0,
        "lte": 15
      }
    ],
    "excluded": false
  }
}
```

**Example 3: Clear existing age configuration**


```json
{
  "configuration": {
    "amount": {
      "value": 10.0,
      "mode": "PER_STAY"
    },
    "child_ages": [],
    "excluded": true
  }
}
```

## 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 specify an age configuration the following conditions applies:
  * The charge mode must be `PER_PERSON_PER_STAY` or `PER_PERSON_PER_NIGHT`
  * The charge type must **not** be classified as `PROPERTY_CHARGES` according to meta response's charge category, with the only exception of the `TRANSFERFEE` charge type (which is a `PROPERTY_CHARGES`).


To view the open API specification to help create, update or delete taxes and fees, see [the Charges endpoint.](/connectivity/docs/openapispecs/charges-api/charges-api-specification/charges-endpoint/updatechargesforproperty)

### Header parameter

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Content-Type: application/json` | Specifies the expected content type. | string | required |  |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | The only supported API version currently is 1.0. |


### 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:

| Element | Description | Type | Required/Optional | Notes | Root parameter in HDCN |
|  --- | --- | --- | --- | --- | --- |
| `property_charges` | Charges that apply across the property. | array | required | At least one charge must be present between `property_charges` and `room_charges`. |  |
| **>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | required | 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. | enumerated string | required | For a list of supported charge types, see the [meta endpoint.](/connectivity/docs/charges-api/charges-meta-endpoint) | `FeePolicy > Code`. |
| **>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`. |  |
| **>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `LEISURE`, `BUSINESS`. |  |
| **>** `charge_periods` | Contains the various configurations for the charge through time. | array of objects | required |  |  |
| **>>** `applicable` | Contains the date range for this charge period. | object | required | Dates are inclusive and must not overlap. |  |
| **>>>** `from` | Specifies the start date for this charge period. | string | required | 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.  Charge periods with a start date more than 10 years in the future will be ignored. |  |
| **>>>** `to` | Specifies the end date for this charge period (inclusive). | string | optional | 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`). Charge periods with an end date more than 10 years in the future will be created without an end date, effectively making the charge extend indefinitely. |  |
| **>>** `configuration` | Contains the charge configuration for this period. | object | optional | If specified as null it clears the charge for the specific period. |  |
| **>>>** `amount` | Contains details about the charge price. | object | required |  |  |
| **>>>>** `value` | Specifies the value of the charge. | number | 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. | `FeePolicy  > Amount` and `FeePolicy > Percent`. |
| **>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected). | See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |  |
| **>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | required | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) | `FeePolicy > ChargeFrequency` and `FeePolicy > Percent` in the case of `PERCENTAGE`. |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional | If the field isn't passed (or is passed as null), existing age values are preserved. If passed, it updates the values, including clearing with an empty array. While specifying ages greater than 18 are valid, because Booking currently supports collecting ages for child travelers, age configurations with ages 18 and above are ignored. |  |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |  |  |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | required | Abbreviation for "less than or equal to". Can be used to define age ranges. |  |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | required | This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API. | `FeePolicy > Type`. |
| `room_charges` | Contains the room specific charges. Overrides the same charge specified at the property level. | array | required | 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. | integer | required |  | `FeePolicy >InvCode` |
| **>** `charges` | Contains the attributes charges apply to. | array | required |  |  |
| **>>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | required | 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. | enumerated string | required |  | `FeePolicy > Code` |
| **>>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`   When determining which charges to apply at checkout, the narrowest/most specific charge key is used. For example, if an `INTERNATIONAL` guest books at a property that has both an `INTERNATIONAL` and `ANY` charge key (with the same charge type), only the `INTERNATIONAL` charge is applied. |  |
| **>>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | required | 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. | array of objects | required |  |  |
| **>>>** `applicable` | Contains the date range for this charge period. | object | required | Dates are inclusive and must not overlap. |  |
| **>>>>** `from` | Specifies the start date for this charge period. | string | required | 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` | Specifies the end date for this charge period (inclusive). | string | optional | 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` | Contains the charge configuration for this period. | object | optional | If specified as null, it clears the charge for the specific period. |  |
| **>>>>** `amount` | Contains details about the charge price. | object | required |  |  |
| **>>>>>** `value` | Specifies the value of the charge. | number | 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. | `FeePolicy  > Amount` and `FeePolicy > Percent` |
| **>>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected). | See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |  |
| **>>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | required | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) | `FeePolicy > ChargeFrequency` and `FeePolicy > Percent` in the case of `PERCENTAGE`. |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional | If the field isn't passed (or is passed as null), existing age values are preserved. If passed, it updates the values, including clearing with an empty array. While specifying ages greater than 18 are valid, because Booking currently supports collecting ages for child travelers, age configurations with ages 18 and above are ignored. |  |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |  |  |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | optional | Abbreviation for "less than or equal to". Can be used to define age ranges. |  |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | required | This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API. | `FeePolicy > Type`. |


### Request body

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


```json
{
  "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


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

### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Root element | object |  |
| **>** `success` | Specifies whether the request was a success. | boolean | - |
| `warnings` | Contains any warnings in the response. | object | - |
| `errors` | Contains any errors in the response. | object | - |
| `meta` | Contains metadata information about the response. | object | - |
| **>** `ruid` | Specifies the unique request ID. | string | You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong. |


## 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`.


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

### Header parameter

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Content-Type: application/json` | Specifies the expected content type. | string | required |  |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | The only supported API version currently is 1.0. |


### 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:

| Element | Description | Type | Required/Optional | Notes | Root parameter in HDCN |
|  --- | --- | --- | --- | --- | --- |
| `property_charges` | Charges that apply across the property. | array | required | At least one charge must be present between `property_charges` and `room_charges`. |  |
| **>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | required | 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. | enumerated string | required | For a list of supported charge types, see the [meta endpoint.](/connectivity/docs/charges-api/charges-meta-endpoint) | `FeePolicy > Code`. |
| **>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`. |  |
| **>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `LEISURE`, `BUSINESS`. |  |
| **>** `charge_periods` | Contains the various configurations for the charge through time. | array of objects | required |  |  |
| **>>** `applicable` | Contains the date range for this charge period. | object | required | Dates are inclusive and must not overlap. |  |
| **>>>** `from` | Specifies the start date for this charge period. | string | required | 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.  Charge periods with a start date more than 10 years in the future will be ignored. |  |
| **>>>** `to` | Specifies the end date for this charge period (inclusive). | string | optional | 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`). Charge periods with an end date more than 10 years in the future will be created without an end date, effectively making the charge extend indefinitely. |  |
| **>>** `configuration` | Contains the charge configuration for this period. | object | optional | If specified as null it clears the charge for the specific period. |  |
| **>>>** `amount` | Contains details about the charge price. | object | required |  |  |
| **>>>>** `value` | Specifies the value of the charge. | number | 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. | `FeePolicy  > Amount` and `FeePolicy > Percent`. |
| **>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected). | See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |  |
| **>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | required | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) | `FeePolicy > ChargeFrequency` and `FeePolicy > Percent` in the case of `PERCENTAGE`. |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional | If the field isn't passed (or is passed as null), existing age values are preserved. If passed, it updates the values, including clearing with an empty array. While specifying ages greater than 18 are valid, because Booking currently supports collecting ages for child travelers, age configurations with ages 18 and above are ignored. |  |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |  |  |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | required | Abbreviation for "less than or equal to". Can be used to define age ranges. |  |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | required | This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API. | `FeePolicy > Type`. |
| `room_charges` | Contains the room specific charges. Overrides the same charge specified at the property level. | array | required | 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. | integer | required |  | `FeePolicy >InvCode` |
| **>** `charges` | Contains the attributes charges apply to. | array | required |  |  |
| **>>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | required | 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. | enumerated string | required |  | `FeePolicy > Code` |
| **>>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | required | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`   When determining which charges to apply at checkout, the narrowest/most specific charge key is used. For example, if an `INTERNATIONAL` guest books at a property that has both an `INTERNATIONAL` and `ANY` charge key (with the same charge type), only the `INTERNATIONAL` charge is applied. |  |
| **>>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | required | 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. | array of objects | required |  |  |
| **>>>** `applicable` | Contains the date range for this charge period. | object | required | Dates are inclusive and must not overlap. |  |
| **>>>>** `from` | Specifies the start date for this charge period. | string | required | 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` | Specifies the end date for this charge period (inclusive). | string | optional | 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` | Contains the charge configuration for this period. | object | optional | If specified as null, it clears the charge for the specific period. |  |
| **>>>>** `amount` | Contains details about the charge price. | object | required |  |  |
| **>>>>>** `value` | Specifies the value of the charge. | number | 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. | `FeePolicy  > Amount` and `FeePolicy > Percent` |
| **>>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected). | See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |  |
| **>>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | required | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) | `FeePolicy > ChargeFrequency` and `FeePolicy > Percent` in the case of `PERCENTAGE`. |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional | If the field isn't passed (or is passed as null), existing age values are preserved. If passed, it updates the values, including clearing with an empty array. While specifying ages greater than 18 are valid, because Booking currently supports collecting ages for child travelers, age configurations with ages 18 and above are ignored. |  |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |  |  |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | optional | Abbreviation for "less than or equal to". Can be used to define age ranges. |  |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | required | This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API. | `FeePolicy > Type`. |


### Request body

The following request body example removes the pet fee charge.


```json
{
  "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


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

### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Root element | object |  |
| **>** `success` | Specifies whether the request was a success. | boolean | - |
| `warnings` | Contains any warnings in the response. | object | - |
| `errors` | Contains any errors in the response. | object | - |
| `meta` | Contains metadata information about the response. | object | - |
| **>** `ruid` | Specifies the unique request ID. | string | You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong. |


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


```http
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:

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


### Response body


```json
{
  "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:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Root element | object |  |
| **>** `property_charges` | Charges that apply across the property. | array | At least one charge must be present between `property_charges` and `room_charges`. |
| **>>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | 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. | enumerated string | For a list of supported charge types, see the [meta endpoint.](/connectivity/docs/charges-api/charges-meta-endpoint) |
| **>>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`. |
| **>>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | Possible values are: `ANY`, `LEISURE`, `BUSINESS`. |
| **>>** `charge_periods` | Contains the various configurations for the charge through time. | array of objects |  |
| **>>>** `applicable` | Contains the date range for this charge period. | object | Dates are inclusive and must not overlap. |
| **>>>>** `from` | Specifies the start date for this charge period. | string | 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. Charge periods with a start date more than 10 years in the future will be ignored. |
| **>>>>** `to` | Specifies the end date for this charge period (inclusive). | string | 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`). Charge periods with an end date more than 10 years in the future will be created without an end date,  effectively making the charge extend indefinitely. |
| **>>>** `configuration` | Contains the charge configuration for this period. | object | If specified as null it clears the charge for the specific period. |
| **>>>>** `amount` | Contains details about the charge price. | object |  |
| **>>>>>** `value` | Specifies the value of the charge. | number | Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency. Omitted for `INCALCULABLE` charges. |
| **>>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected).  See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |
| **>>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | required |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | 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. | array | Can be an empty array. |
| **>>** `room_id` | Specifies the Room ID the charges apply to. | integer |  |
| **>>** `charges` | Contains the attributes charges apply to. | array |  |
| **>>>** `charge_key` | Contains the attributes that uniquely identifies a charge. | object | 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. | enumerated string |  |
| **>>>>** `guest_origin` | Specifies the guest origin as specified by guests when they make the booking. | enumerated string | Possible values are: `ANY`, `DOMESTIC`, `INTERNATIONAL`   When determining which charges to apply at checkout, the narrowest/most specific charge key is used. For example, if an `INTERNATIONAL` guest books at a property that has both an `INTERNATIONAL` and `ANY` charge key (with the same charge type), only the `INTERNATIONAL` charge is applied. |
| **>>>>** `travel_purpose` | Specifies the travel purpose as specified by guests when they make the booking. | enumerated string | 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 `INTERNATIONAL` 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. | array of objects |  |
| **>>>>** `applicable` | Contains the date range for this charge period. | object | Dates are inclusive and must not overlap. |
| **>>>>>** `from` | Specifies the start date for this charge period. | string | 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 property's timezone. |
| **>>>>>** `to` | Specifies the end date for this charge period (inclusive). | string | 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` | Contains the charge configuration for this period. | object | If specified as null it clears the charge for the specific period. |
| **>>>>** `amount` | Contains details about the charge price. | object |  |
| **>>>>>** `value` | Specifies the value of the charge. | number | Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency.Omitted for `INCALCULABLE` charges. |
| **>>>>>** `base` | Only applies when `mode` is `PERCENTAGE`. Specifies the value the percentage applies to. | enumerated array of strings | Required when mode is `PERCENTAGE` (otherwise rejected).  See the section on [Understanding Percentage charges.](/connectivity/docs/charges-api/manage-property-room-charges#percentage-charges) |
| **>>>>>** `mode` | Specifies the mode used for this charge. | enumerated string | For possible values, see [Understanding Charge modes.](#understanding-charge-modes) |
| **>>>>** `child_ages` | Contains modifiers for the charge amount based on children ages. | array of objects | optional |
| **>>>>>** `multiplier` | Multiplier to be applied to the amount of the charge if age condition matches. | number | required when including age configuration |
| **>>>>>** `lte` | Upper bound of the age range (inclusive). | integer | required |
| **>>>>** `excluded` | Specifies if the charge is included or excluded from the room rate. | boolean | This corresponds to the similarly named field in extranet. But is different from the `included`/`excluded` within the Reservations API. |
| `warnings` | Contains any warnings in the response. | object | - |
| `errors` | Contains any errors in the response. | object | - |
| `meta` | Contains metadata information about the response. | object | - |
| **>** `ruid` | Specifies the unique request ID. | string | You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong. |