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.

---

Endpoint

POST

https://connect-sandbox.su-api.com/SUAPI/jservice/bdc/property/charges/set

Header

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

Header	Type	Required	Description
app-id	string	Yes	Your application ID. Required for authentication.
Authorization	string	Yes	Your API key. for authorization. Required for authentication.
Content-Type	string	Yes	Must be set to application/json.

---

Attributes

hotel_id string (Required)

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

---

channel_hotel_id string (Required)

The unique id for the hotel on the specific channel.

---

property_charges array (Required)

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

charge_key object (Required)

Contains the attributes that uniquely identify a charge.

If you change an attribute in the charge key, you are modifying a different charge with its own charge periods.

type string (Required)

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

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

guest_origin string (Required)

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.

Enum:

• ANY

• DOMESTIC

• INTERNATIONAL

travel_purpose string (Required)

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.

Enum:

• ANY

• LEISURE

• BUSINESS

charge_periods array (Required)

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

applicable object (Required)

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

from string (Required)

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.

Format: ISO 8601 date (YYYY-MM-DD)

to string (Required)

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.

Format: ISO 8601 date (YYYY-MM-DD)

configuration object (Optional)

The charge configuration for this period.

If specified as null it clears the charge for the specific period. This field cannot be omitted.

amount object (Required)

Contains details about the charge price.

value number (Required)

Value of the charge.

Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency.

base array (Optional)

Specifies what value the percentage applies to. For example, 10% of NET_ROOM_PRICE + PROPERTY_CHARGES.

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

mode string (Required)

The mode used for this charge.

Enum:

• PER_NIGHT

• PER_STAY

• PER_PERSON_PER_NIGHT

• PER_PERSON_PER_STAY

• PERCENTAGE

• INCALCULABLE

excluded boolean (Required)

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

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.

---

room_charges array (Required)

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 integer (Required)

The Room ID the charges apply to.

---

charges array (Required)

List of charges for the room.

---

charge_key object (Required)

Contains the attributes that uniquely identify a charge.

If you change an attribute in the charge key, you are modifying a different charge with its own charge periods.

type string (Required)

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

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

guest_origin string (Required)

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.

Enum:

• ANY

• DOMESTIC

• INTERNATIONAL

travel_purpose string (Required)

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.

Enum:

• ANY

• LEISURE

• BUSINESS

---

charge_periods array (Required)

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

applicable object (Required)

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

from string (Required)

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.

Format: ISO 8601 date (YYYY-MM-DD)

to string (Required)

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.

Format: ISO 8601 date (YYYY-MM-DD)

---

configuration object (Required)

The charge configuration for this period.

If specified as null it clears the charge for the specific period. This field cannot be omitted.

---

amount object (Required)

Contains details about the charge price.

value number (Required)

Value of the charge.

Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency.

base array (Required)

Specifies what value the percentage applies to. For example, 10% of NET_ROOM_PRICE + PROPERTY_CHARGES.

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

mode string (Required)

The mode used for this charge.

Enum:

• PER_NIGHT

• PER_STAY

• PER_PERSON_PER_NIGHT

• PER_PERSON_PER_STAY

• PERCENTAGE

• INCALCULABLE

excluded boolean (Required)

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

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.

---

Sample Request

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

---

Response

Sample Success Response

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

Success Response Body Elements

Status string

Indicates the result of the API call.

Will be "Success" for successful operations.

---

Message string

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

---

Ruid string

Specifies the unique request ID.

You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

---

Data array

An array containing data related to the successful response.

Errors

Sample Error Response 1

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

Sample Error Response 2

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

Sample Error Response 3

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

Sample Error Response 4

{
   "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": {}
}

---

Error Response Body Elements

Status string

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

---

Error array

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

Code string

Specific error code that helps identify the type of error.

For example: "400" indicates a bad request.

ShortText string

A short description of the error.

---

Message string

A message providing more information about the error.

---

Ruid string

Specifies the unique request ID.

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.