openapi: 3.0.1 info: title: Charges API description: >- Create and update charges that apply at the property and room level, and setup up different configurations for different dates. contact: name: Connectivity Team url: https://connect.booking.com email: connectivity@booking.com version: '1.0' servers: - url: https://supply-xml.booking.com/ tags: - name: Charges endpoint description: >- Lists the details of the Charges endpoints to set and retrieve taxes and fees at the property and room level. - name: Charges meta endpoint description: >- Lists the details of the Charges meta endpoint to retrieve a full list of charge types supported by the Charges API. paths: /charges-api/properties/{propertyId}/charges: get: tags: - Charges endpoint summary: Get property and room charges description: >- Retrieve the current charges for a property in format consistent with the creation/update payload. operationId: getChargesForProperty parameters: - name: propertyId in: path required: true schema: type: integer format: int32 responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ApiResponseCharges' put: tags: - Charges endpoint summary: Create, update, and delete property and room charges description: Add or update taxes and fees at the property or room-level. operationId: updateChargesForProperty parameters: - name: propertyId in: path required: true schema: type: integer format: int32 requestBody: content: application/json: schema: $ref: '#/components/schemas/Charges' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ApiResponseObject' /charges-api/meta: get: tags: - Charges meta endpoint summary: Retrieve Charges meta information description: >- Retrieve a full list of charge types supported by the Charges API, their corresponding OTA codes, and which charge category they apply to. operationId: meta responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ApiResponseListChargeTypeMetaEntry' components: schemas: Amount: required: - mode - value type: object properties: value: type: number description: > Value of the charge. Interpreted as an absolute value or percentage depending on mode. Absolute values are in the property's configured currency. HDCN:FeePolicy->Amount AND FeePolicy->Percent base: type: array description: > 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. Currently we only accept the following combinations: - ["NET_ROOM_PRICE"] - ["NET_ROOM_PRICE", "PROPERTY_CHARGES"] - ["NET_ROOM_PRICE", "LOCALITY_CHARGES"] - ["NET_ROOM_PRICE", "LOCALITY_CHARGES", "PROPERTY_CHARGES"] HDCN: N/A items: type: string description: > 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. Currently we only accept the following combinations: - ["NET_ROOM_PRICE"] - ["NET_ROOM_PRICE", "PROPERTY_CHARGES"] - ["NET_ROOM_PRICE", "LOCALITY_CHARGES"] - ["NET_ROOM_PRICE", "LOCALITY_CHARGES", "PROPERTY_CHARGES"] HDCN: N/A enum: - NET_ROOM_PRICE - TAXES - LOCALITY_CHARGES - PROPERTY_CHARGES - FACILITY_CHARGES mode: type: string description: > The mode used for this charge. Reference the meta endpoint to understand which charge modes are supported for the charge type. HDCN:FeePolicy->ChargeFrequency AND FeePolicy->Percent in the case of `PERCENTAGE` enum: - PER_NIGHT - PER_STAY - PER_PERSON_PER_NIGHT - PER_PERSON_PER_STAY - PERCENTAGE - INCALCULABLE description: Contains details about the charge price. ApplicableWindow: required: - from type: object properties: from: type: string description: > 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) HDCN: N/A to: type: string description: > 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) HDCN: N/A description: >- The date range for this charge period. Dates are inclusive and must not overlap. Charge: required: - charge_key - charge_periods type: object properties: charge_key: $ref: '#/components/schemas/ChargeKey' charge_periods: type: array description: >- Contains the timeline of various configurations for the charge through time. items: $ref: '#/components/schemas/ChargePeriod' description: List of charges for the listing. ChargeConfiguration: required: - amount - excluded type: object properties: amount: $ref: '#/components/schemas/Amount' excluded: type: boolean description: > 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. HDCN: FeePolicy->Type description: >- The charge configuration for this period. If specified as `null` it clears the charge for the specific period. This field cannot be omitted. ChargeKey: required: - guest_origin - travel_purpose - type type: object properties: type: type: string description: > The type of charge. For a mapping between OTA/legacy and the new codes please use the meta endpoint. HDCN: FeePolicy->Code 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 - FINALCLEANINGFEE - WRISTBANDFEE - VISASUPPORTFEE - WATERPARKFEE - CLUBCARDFEE - CONSERVATIONFEE - CREDITCARDFEE - PETFEE - INTERNETFEE - PARKINGFEE - VAT - TAX - GOODSSERVICESTAX - GOODSSERVICESFLOODTAX - GOVERNMENTCHARGE - DAMAGEDEPOSIT - DESTINATIONFEE - ENVIRONMENTFEE - SPATAX - CITYTAX - HOTSPRINGTAX - MUNICIPALITYFEE - TOURISMFEE - RESIDENTIALTAX - CITYTICKET - HERITAGECHARGE - FITNESSTAX - GOVERNMENTTAX - LOCALCOUNCILTAX - SUSTAINABILITYFEE - LOCALITYCONSERVATIONFEE - SPA - HOTSPRINGBATH - POOL - LOUNGE - DESTINATIONCHARGE - DESTINATIONTAX guest_origin: type: string description: > 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. HDCN: N/A enum: - ANY - DOMESTIC - INTERNATIONAL travel_purpose: type: string description: > 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 LEISURE and ANY charge key (with the same charge type), only the LEISURE charge is applied. HDCN: N/A enum: - ANY - LEISURE - BUSINESS description: >- 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. ChargePeriod: required: - applicable type: object properties: applicable: $ref: '#/components/schemas/ApplicableWindow' configuration: $ref: '#/components/schemas/ChargeConfiguration' description: >- Contains the timeline of various configurations for the charge through time. Charges: type: object properties: property_charges: type: array description: >- Charges that apply across the property. Update requests must contain at least one charge between property and room arrays. items: $ref: '#/components/schemas/Charge' room_charges: type: array description: >- 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. items: $ref: '#/components/schemas/RoomCharges' RoomCharges: required: - charges - room_id type: object properties: room_id: maximum: 4294967295 type: integer description: | The Room ID the charges apply to. HDCN: FeePolicy->InvCode format: int64 charges: type: array description: List of charges for the listing. items: $ref: '#/components/schemas/Charge' description: >- 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. ApiError: type: object properties: message: type: string code: type: string details: type: object ApiResponseObject: type: object properties: ruid: type: string writeOnly: true data: type: object warnings: type: array items: $ref: '#/components/schemas/ApiError' errors: type: array items: $ref: '#/components/schemas/ApiError' meta: $ref: '#/components/schemas/ResponseMeta' ResponseMeta: type: object properties: ruid: type: string ApiResponseCharges: type: object properties: ruid: type: string writeOnly: true data: $ref: '#/components/schemas/Charges' warnings: type: array items: $ref: '#/components/schemas/ApiError' errors: type: array items: $ref: '#/components/schemas/ApiError' meta: $ref: '#/components/schemas/ResponseMeta' ApiResponseListChargeTypeMetaEntry: type: object properties: ruid: type: string writeOnly: true data: type: array items: $ref: '#/components/schemas/ChargeTypeMetaEntry' warnings: type: array items: $ref: '#/components/schemas/ApiError' errors: type: array items: $ref: '#/components/schemas/ApiError' meta: $ref: '#/components/schemas/ResponseMeta' ChargeTypeMetaEntry: type: object properties: charge_type_id: type: string description: Booking.com Charge Type ID enum: - SERVICECHARGE_ASIA - SERVICECHARGE - RESORTFEE - CLEANINGFEE - TOWELFEE - ELECTRICITYFEE - BEDLINEN - GASFEE - OILFEE - WOODFEE - WATERFEE - DESTINATIONFEE - ENVIRONMENTFEE - SPATAX - TRANSFERFEE - VAT - CITYTAX - TAX - DAMAGEDEPOSIT - LINENPACKAGEFEE - HEATINGFEE - AIRCONDITIONINGFEE - KITCHENLINNENFEE - HOUSEKEEPINGFEE - CLUBCARDFEE - PETFEE - INTERNETFEE - PARKINGFEE - HOTSPRINGTAX - MUNICIPALITYFEE - TOURISMFEE - RESIDENTIALTAX - GOODSSERVICESTAX - HERITAGECHARGE - GOVERNMENTTAX - LOCALCOUNCILTAX - GOVERNMENTCHARGE - LOCALITYCONSERVATIONFEE - LAST_SERVICECHARGE - AIRPORTSHUTTLEFEE - SHUTTLEBOATFEE - GALADINNERFEE - SEAPLANEFEE - SKIPASS - FINALCLEANINGFEE - WRISTBANDFEE - VISASUPPORTFEE - WATERPARKFEE - CONSERVATIONFEE - CREDITCARDFEE - CITYTICKET - FITNESSTAX - GOODSSERVICESFLOODTAX - SUSTAINABILITYFEE - SPA - HOTSPRINGBATH - POOL - LOUNGE - DESTINATIONCHARGE - DESTINATIONTAX ota_fee_tax_types: type: array description: >- Legacy OTA Fee Tax Type Codes (FTT). In rare cases there are two historical type codes for one modern type. items: type: integer description: >- Legacy OTA Fee Tax Type Codes (FTT). In rare cases there are two historical type codes for one modern type. format: int32 booking_extended_legacy_code: type: array description: Legacy Booking.com Extended Fee Tax Type Codes (FTT). items: type: integer description: Legacy Booking.com Extended Fee Tax Type Codes (FTT). format: int32 charge_category: type: string description: Charge category as used in the charge configuration base enum: - NET_ROOM_PRICE - TAXES - LOCALITY_CHARGES - PROPERTY_CHARGES - FACILITY_CHARGES discontinuation_notice: type: string description: > In the case that a charge type is discontinued, this will provide information about what to use instead or why it was discontinued. allowed_charge_modes: type: array description: | Lists the modes that this charge type supports. items: type: string description: | Lists the modes that this charge type supports. enum: - PER_NIGHT - PER_STAY - PER_PERSON_PER_NIGHT - PER_PERSON_PER_STAY - PERCENTAGE - INCALCULABLE discontinued: type: boolean