# Create Property Charges

This endpoint allows partners to submit charges associated with properties. This API endpoint validates the provided charge information and returns appropriate responses based on the success or failure of the operation.

***

### <mark style="color:yellow;">Endpoint</mark>

<mark style="color:green;background-color:green;">**`POST`**</mark>&#x20;

<div align="left"><figure><img src="https://958347541-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM9bn2UcBkeqtqixkl5eF%2Fuploads%2FpsybX0n39kUB8Z8WOk4X%2FSandbox%20image.png?alt=media&#x26;token=4ae73d0f-0d1a-4d73-a4e2-673dbc081d6a" alt="" width="56"><figcaption></figcaption></figure></div>

{% code overflow="wrap" %}
```url
https://connect-sandbox.su-api.com/SUAPI/jservice/bdc/property/charges/set
```
{% endcode %}

#### <mark style="color:yellow;">Header</mark>

```xml
-app-id: YOUR_APP_ID
Authorization: YOUR_API_KEY
Content-Type:application/json
```

<table><thead><tr><th width="185">Header</th><th width="85">Type</th><th width="101">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>app-id</code></td><td>string</td><td>Yes</td><td>Your application ID. Required for authentication.</td></tr><tr><td><code>Authorization</code></td><td>string</td><td>Yes</td><td>Your API key. for authorization. Required for authentication.</td></tr><tr><td><code>Content-Type</code></td><td>string</td><td>Yes</td><td>Must be set to <code>application/json</code>.</td></tr></tbody></table>

***

#### <mark style="color:yellow;">Attributes</mark>

`hotel_id` <mark style="color:orange;">**string (Required)**</mark>

The unique property ID as assigned by the provider upon creation of the property.

***

`channel_hotel_id` <mark style="color:orange;">**string (Required)**</mark>

The unique id for the hotel on the specific channel.

***

`property_charges` <mark style="color:orange;">**array (Required)**</mark>

Charges that apply across the property. Update requests must contain at least one charge between property and room arrays.

`charge_key` <mark style="color:orange;">**object (Required)**</mark>

Contains the attributes that uniquely identify a charge.

{% hint style="info" %}
If you change an attribute in the charge key, you are modifying a different charge with its own charge periods.
{% endhint %}

`type` <mark style="color:orange;">**string (Required)**</mark>

The type of charge. For a mapping between OTA/legacy and the new codes please use the meta endpoint.

{% hint style="info" %}
**Enum:**

* `SERVICECHARGE_ASIA`
* `SERVICECHARGE`
* `RESORTFEE`
* `CLEANINGFEE`
* `TOWELFEE`
* `ELECTRICITYFEE`
* `BEDLINEN`
* `GASFEE`
* `OILFEE`
* `WOODFEE`
* `WATERFEE`
* `TRANSFERFEE`
* `LAST_SERVICECHARGE`
* `LINENPACKAGEFEE`
* `HEATINGFEE`
* `AIRCONDITIONINGFEE`
* `KITCHENLINNENFEE`
* `HOUSEKEEPINGFEE`
* `AIRPORTSHUTTLEFEE`
* `SHUTTLEBOATFEE`
* `GALADINNERFEE`
* `SEAPLANEFEE`
* `SKIPASS`
* `WRISTBANDFEE`
* `VISASUPPORTFEE`
* `WATERPARKFEE`
* `CLUBCARDFEE`
* `CONSERVATIONFEE`
* `CREDITCARDFEE`
* `PETFEE`
* `INTERNETFEE`
* `PARKINGFEE`
* `VAT`
* `TAX`
* `GOODSSERVICESTAX`
* `GOODSSERVICESFLOODTAX`
* `GOVERNMENTCHARGE`
* `ENVIRONMENTFEE`
* `SPATAX`
* `CITYTAX`
* `HOTSPRINGTAX`
* `MUNICIPALITYFEE`
* `TOURISMFEE`
* `RESIDENTIALTAX`
* `CITYTICKET`
* `HERITAGECHARGE`
* `FITNESSTAX`
* `GOVERNMENTTAX`
* `LOCALCOUNCILTAX`
* `SUSTAINABILITYFEE`
* `LOCALITYCONSERVATIONFEE`
* `SPA`
* `HOTSPRINGBATH`
* `POOL`
* `LOUNGE`
* `DESTINATIONCHARGE`
* `DESTINATIONTAX`
{% endhint %}



`guest_origin` <mark style="color:orange;">**string (Required)**</mark>

The guest origin as specified when they make the booking.

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.

{% hint style="info" %}
**Enum:**

* `ANY`
* `DOMESTIC`
* `INTERNATIONAL`
{% endhint %}

`travel_purpose` <mark style="color:orange;">**string (Required)**</mark>

The travel purpose as specified by the guest when they make the booking.

When determining which charge to use at checkout, the narrowest/most specific charge key is used. For example if an 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.

{% hint style="info" %}
**Enum:**

* `ANY`
* `LEISURE`
* `BUSINESS`
{% endhint %}

`charge_periods` <mark style="color:orange;">**array (Required)**</mark>

Contains the timeline of various configurations for the charge through time.

`applicable` <mark style="color:orange;">**object (Required)**</mark>

The date range for this charge period. Dates are inclusive and must not overlap.

`from` <mark style="color:orange;">**string (Required)**</mark>

The start date for this charge period. The date is relative to the timezone of the property. If you are modifying an existing active charge, this date may be in the past if it matches the active charge's date.

{% hint style="info" %}
Format: ISO 8601 date (YYYY-MM-DD)
{% endhint %}

`to` <mark style="color:orange;">**string (Required)**</mark>

The end date for this charge period (inclusive). The date is relative to the timezone of the property. If null or undefined the current charge period extends forever.

{% hint style="info" %}
Format: ISO 8601 date (YYYY-MM-DD)
{% endhint %}

`configuration` <mark style="color:orange;">**object (Optional)**</mark>

The charge configuration for this period.

{% hint style="info" %}
If specified as `null` it clears the charge for the specific period. This field cannot be omitted.
{% endhint %}

`amount` <mark style="color:orange;">**object (Required)**</mark>

Contains details about the charge price.

`value` <mark style="color:orange;">**number (Required)**</mark>

Value of the charge.

{% hint style="info" %}
Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency.
{% endhint %}

`base` <mark style="color:orange;">**array (Optional)**</mark>

Specifies what value the percentage applies to. For example, 10% of NET\_ROOM\_PRICE + PROPERTY\_CHARGES.

{% hint style="info" %}
Required when mode is PERCENTAGE (otherwise rejected).

To know what charge types fall into each base category please use the meta endpoint.

**Items Enum:**&#x20;

* `NET_ROOM_PRICE`
* `TAXES`
* `LOCALITY_CHARGES`
* `PROPERTY_CHARGES`
* `FACILITY_CHARGES`
{% endhint %}

`mode` <mark style="color:orange;">**string (Required)**</mark>

The mode used for this charge.

{% hint style="info" %}
**Enum:**

* `PER_NIGHT`
* `PER_STAY`
* `PER_PERSON_PER_NIGHT`
* `PER_PERSON_PER_STAY`
* `PERCENTAGE`
* `INCALCULABLE`
{% endhint %}



`excluded` <mark style="color:orange;">**boolean (Required)**</mark>

Specifies if the charge is included or excluded from the calendar rate.

{% hint style="info" %}
For example, let's assume the calendar rate is set to 100 euros. If there is a 10 euro excluded charge the net price would be 110 euros and our price breakdown would show 100 + 10. If the 10 euro charge is not excluded the net price would be 100 and our price breakdown would show 90 + 10.

This corresponds to the similarly named field in extranet, but is separate from the included/excluded within Reservations API.
{% endhint %}

***

`room_charges` <mark style="color:orange;">**array (Required)**</mark>

Room specific charges. Will override the same charge specified at the property level. Update requests must contain at least one charge between property and room arrays.

***

`room_id` <mark style="color:orange;">**integer (Required)**</mark>

The Room ID the charges apply to.

***

`charges` <mark style="color:orange;">**array (Required)**</mark>

List of charges for the room.

***

`charge_key` <mark style="color:orange;">**object (Required)**</mark>

Contains the attributes that uniquely identify a charge.

{% hint style="info" %}
If you change an attribute in the charge key, you are modifying a different charge with its own charge periods.
{% endhint %}

`type` <mark style="color:orange;">**string (Required)**</mark>

The type of charge. For a mapping between OTA/legacy and the new codes please use the meta endpoint.

{% hint style="info" %}
**Enum:**&#x20;

* `SERVICECHARGE_ASIA`
* `SERVICECHARGE`
* `RESORTFEE`
* `CLEANINGFEE`
* `TOWELFEE`
* `ELECTRICITYFEE`
* `BEDLINEN`
* `GASFEE`
* `OILFEE`
* `WOODFEE`
* `WATERFEE`
* `TRANSFERFEE`
* `LAST_SERVICECHARGE`
* `LINENPACKAGEFEE`
* `HEATINGFEE`
* `AIRCONDITIONINGFEE`
* `KITCHENLINNENFEE`
* `HOUSEKEEPINGFEE`
* `AIRPORTSHUTTLEFEE`
* `SHUTTLEBOATFEE`
* `GALADINNERFEE`
* `SEAPLANEFEE`
* `SKIPASS`
* `WRISTBANDFEE`
* `VISASUPPORTFEE`
* `WATERPARKFEE`
* `CLUBCARDFEE`
* `CONSERVATIONFEE`
* `CREDITCARDFEE`
* `PETFEE`
* `INTERNETFEE`
* `PARKINGFEE`
* `VAT`
* `TAX`
* `GOODSSERVICESTAX`
* `GOODSSERVICESFLOODTAX`
* `GOVERNMENTCHARGE`
* `ENVIRONMENTFEE`
* `SPATAX`
* `CITYTAX`
* `HOTSPRINGTAX`
* `MUNICIPALITYFEE`
* `TOURISMFEE`
* `RESIDENTIALTAX`
* `CITYTICKET`
* `HERITAGECHARGE`
* `FITNESSTAX`
* `GOVERNMENTTAX`
* `LOCALCOUNCILTAX`
* `SUSTAINABILITYFEE`
* `LOCALITYCONSERVATIONFEE`
* `SPA`
* `HOTSPRINGBATH`
* `POOL`
* `LOUNGE`
* `DESTINATIONCHARGE`
* `DESTINATIONTAX`
{% endhint %}

`guest_origin` <mark style="color:orange;">**string (Required)**</mark>

The guest origin as specified when they make the booking.

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.

{% hint style="info" %}
**Enum:**&#x20;

* `ANY`
* `DOMESTIC`
* `INTERNATIONAL`
{% endhint %}

`travel_purpose` <mark style="color:orange;">**string (Required)**</mark>

The travel purpose as specified by the guest when they make the booking.

When determining which charge to use at checkout, the narrowest/most specific charge key is used. For example if an 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.

{% hint style="info" %}
**Enum:**

* `ANY`
* `LEISURE`
* `BUSINESS`
{% endhint %}

***

`charge_periods` <mark style="color:orange;">**array (Required)**</mark>

Contains the timeline of various configurations for the charge through time.

`applicable` <mark style="color:orange;">**object (Required)**</mark>

The date range for this charge period. Dates are inclusive and must not overlap.

`from` <mark style="color:orange;">**string (Required)**</mark>

The start date for this charge period. The date is relative to the timezone of the property. If you are modifying an existing active charge, this date may be in the past if it matches the active charge's date.

{% hint style="info" %}
Format: ISO 8601 date (YYYY-MM-DD)
{% endhint %}

`to` <mark style="color:orange;">**string (Required)**</mark>

The end date for this charge period (inclusive). The date is relative to the timezone of the property. If null or undefined the current charge period extends forever.

{% hint style="info" %}
Format: ISO 8601 date (YYYY-MM-DD)
{% endhint %}

***

`configuration` <mark style="color:orange;">**object (Required)**</mark>

The charge configuration for this period.

{% hint style="info" %}
If specified as `null` it clears the charge for the specific period. This field cannot be omitted.
{% endhint %}

***

`amount` <mark style="color:orange;">**object (Required)**</mark>

Contains details about the charge price.\


`value` <mark style="color:orange;">**number (Required)**</mark>

Value of the charge.

{% hint style="info" %}
Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency.
{% endhint %}

`base` <mark style="color:orange;">**array (Required)**</mark>

Specifies what value the percentage applies to. For example, 10% of NET\_ROOM\_PRICE + PROPERTY\_CHARGES.

{% hint style="info" %}
Required when mode is PERCENTAGE (otherwise rejected).

To know what charge types fall into each base category please use the meta endpoint.

**Items Enum:**

* `NET_ROOM_PRICE`
* `TAXES`
* `LOCALITY_CHARGES`
* `PROPERTY_CHARGES`
* `FACILITY_CHARGES`
{% endhint %}



`mode` <mark style="color:orange;">**string (Required)**</mark>

The mode used for this charge.

{% hint style="info" %}
**Enum:**

* `PER_NIGHT`
* `PER_STAY`
* `PER_PERSON_PER_NIGHT`
* `PER_PERSON_PER_STAY`
* `PERCENTAGE`
* `INCALCULABLE`
{% endhint %}

`excluded` <mark style="color:orange;">**boolean (Required)**</mark>

Specifies if the charge is included or excluded from the calendar rate.

{% hint style="info" %}
For example, let's assume the calendar rate is set to 100 euros. If there is a 10 euro excluded charge the net price would be 110 euros and our price breakdown would show 100 + 10. If the 10 euro charge is not excluded the net price would be 100 and our price breakdown would show 90 + 10.

This corresponds to the similarly named field in extranet, but is separate from the included/excluded within Reservations API.
{% endhint %}

***

## <mark style="color:yellow;">**Sample Request**</mark>

```json
{
   "hotel_id": "AWSTEST",
   "channel_hotel_id": "12837615",
   "property_charges": [
       {
           "charge_key": {
               "type": "SERVICECHARGE_ASIA",
               "guest_origin": "ANY",
               "travel_purpose": "ANY"
           },
           "charge_periods": [
               {
                   "applicable": {
                       "from": "2024-10-17",
                       "to": "2024-10-17"
                   },
                   "configuration": {
                       "amount": {
                           "value": 0,
                           "base": [
                               "NET_ROOM_PRICE"
                           ],
                           "mode": "PER_NIGHT"
                       },
                       "excluded": true
                   }
               }
           ]
       }
   ],
   "room_charges": [
       {
           "room_id": 4294967295,
           "charges": [
               {
                   "charge_key": {
                       "type": "SERVICECHARGE_ASIA",
                       "guest_origin": "ANY",
                       "travel_purpose": "ANY"
                   },
                   "charge_periods": [
                       {
                           "applicable": {
                               "from": "2024-10-17",
                               "to": "2024-10-17"
                           },
                           "configuration": {
                               "amount": {
                                   "value": 0,
                                   "base": [
                                       "NET_ROOM_PRICE"
                                   ],
                                   "mode": "PER_NIGHT"
                               },
                               "excluded": true
                           }
                       }
                   ]
               }
           ]
       }
   ]
}
```

***

## <mark style="color:yellow;">Response</mark>

#### <mark style="color:green;">**Sample Success Response**</mark>

```json
{
   "Status": "Success",
   "Message": "Successfully done",
   "Ruid": "e527c45a-f23a-4ee4-beb2-7d21f7699b1b",
   "Data": {}
}
```

#### <mark style="color:yellow;">Success Response Body Elements</mark>

`Status` <mark style="color:orange;">**string**</mark>

Indicates the result of the API call.&#x20;

{% hint style="info" %}
Will be `"Success"` for successful operations.
{% endhint %}

***

`Message` <mark style="color:orange;">**string**</mark>

A message receives within the response body. This will generally be an empty string if no additional information is needed.

***

`Ruid` <mark style="color:orange;">**string**</mark>&#x20;

Specifies the unique request ID.&#x20;

{% hint style="info" %}
You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.
{% endhint %}

***

`Data` <mark style="color:orange;">**array**</mark>

An array containing data related to the successful response.

#### <mark style="color:red;">Errors</mark>

<mark style="color:red;">**Sample Error Response 1**</mark>

```json
{
   "Errors": [
       {
           "Code": "400",
           "ShortText": "HotelCode: Invalid HotelCode ('AWSTEST')"
       }
   ],
   "Status": "Fail"
}
```

<mark style="color:red;">**Sample Error Response 2**</mark>

```json
{
   "Errors": [
       {
           "Code": "573",
           "ShortText": "channel-mapping not found for this property!"
       }
   ],
   "Status": "Fail"
}
```

<mark style="color:red;">**Sample Error Response 3**</mark>

```json
{
   "Errors": [
       {
           "Code": "611",
           "ShortText": "property_settings - require_cvc is invalid or not found!"
       }
   ],
   "Status": "Fail"
}
```

<mark style="color:red;">**Sample Error Response 4**</mark>

```json
{
   "Status": "Fail",
   "Errors": [],
   "Message": "Invalid value: $.property_charges[0].charge_periods[0].configuration.amount.value - must be greater than 0, Invalid value: $.room_charges[0].charges[0].charge_periods[0].configuration.amount.value - must be greater than 0",
   "Ruid": "e996d833-d9bd-4a93-beae-8b893fc073b2",
   "Data": {}
}
```

***

<mark style="color:yellow;">**Error Response Body Elements**</mark>

`Status` <mark style="color:orange;">**string**</mark>

Indicates the result of the API call, which will be always `"Fail"` in case of an error response.

***

`Error` <mark style="color:orange;">**array**</mark>

Array that contains details about any errors that occurred during the API call. Each object in the `Errors` array contains the following properties:

`Code` <mark style="color:orange;">**string**</mark>

Specific error code that helps identify the type of error.

{% hint style="info" %}
For example: `"400"` indicates a bad request.
{% endhint %}

`ShortText` <mark style="color:orange;">**string**</mark>

A short description of the error.

***

`Message` <mark style="color:orange;">**string**</mark>

A message providing more information about the error.

***

`Ruid` <mark style="color:orange;">**string**</mark>&#x20;

Specifies the unique request ID.&#x20;

{% hint style="info" %}
You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

In the case where a **RUID** (Request Unique Identifier) is provided by Booking.com, it will be displayed in the response. If no RUID is received, the field will be left blank.
{% endhint %}
