# Hotel price structure The guide provides information on the hotel price structure used on the Spotnana platform. ## Price components A hotel price is broken down into four components: - **Base:** The room rate before any taxes or fees are applied. - **Tax:** The sum of all taxes configured based on the location and the local government regulations (e.g., VAT, GST, occupancy tax, etc). - **Fees:** Additional mandatory charges, such as destination fees, resort fees, or city taxes that are not part of the base rate. For example, hotels located in Kyoto, Japan often charge an additional accommodation tax at the property. - **Commission:** The percentage or flat fee collected by the supplier for the booking (usually paid by the hotel). The traveler may not have to pay this as part of the total rate. However, in some cases, the commission is also added as part of the total rate and charged to the traveler. The `includesCommission` field is used to identify if the commission is part of the total rate. **Total rate:** The final price, calculated as Base + Tax + Fees + Commission (if applicable). In the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) endpoint response, the `rooms` > `rateOptions` > `rateInfo` > `totalRate` object contains all the components mentioned above. Here's a sample API response of the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) endpoint that contains the components of the `totalRate` object: ```json /v2/hotel/details // ... payload truncated for focus { "totalRate": { "base": { "amount": 510.00, "currencyCode": "USD", "convertedAmount": 469.20, "convertedCurrency": "EUR" }, "tax": { "amount": 90.00, "currencyCode": "USD" }, "roomFees": [ { "amount": { "amount": 25.00, "currencyCode": "USD" }, "feeType": "RESORT_FEE", "displayFee": true } ], "commission": { "amount": { "amount": 38.25, "currencyCode": "USD" }, "commissionPercent": 7.5 }, "taxBreakdown": [ { "amount": { "amount": 75.00, "currencyCode": "USD" }, "taxCode": "OCCUPANCY_TAX", "percentage": 9.0 }, { "amount": { "amount": 15.00, "currencyCode": "USD" }, "taxCode": "STATE_TAX", "percentage": 2.0 } ], "includesCommission": false } } ``` In the example above, the price details are structured as follows: - The base price is USD 510. - The tax is charged at USD 90. - The resort fee is charged at USD 25. The `totalRate` of the room for one night is calculated by adding all the above charges (base + tax + resort fee). The `taxBreakdown` object explains the different types of taxes charged for this room. In this example, the supplier charges an occupancy tax of USD 75 and a state tax of USD 15. This adds up to USD 90 as listed on the `tax` > `amount` field. The `includesCommission` is a boolean field that indicates if any commission is included as part of the total rate (i.e., does the traveler have to pay the commission as part of the total rate?). In this scenario, the `includesCommission` is `false`, indicating the total price doesn't include the amount mentioned in the `commission` field. So, the `totalRate` the traveler will be paying is USD 625 (base rate + tax + resort fee). The hotel may pay the commission separately to the platform provider but the amount will be present in the JSON payload for tracking and accounting purposes. ## Nightly rate The nightly rate indicates the price of the hotel room per night. This price is set by the supplier and it may vary on different nights (e.g., weekend rate, festive season rate, etc). In the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) endpoint response, the `rooms` > `rateOptions` > `rateInfo` > `nightlyRate` object contains the nightly rate information for the selected hotel room. Here's a sample response from the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) endpoint containing the `nightlyRate` for two nights: ```json /v2/hotel/details // ... payload truncated for focus "nightlyRate": [ { "base": { "currencyCode": "USD", "amount": 153.0 }, "tax": { "currencyCode": "USD", "amount": 17.98 } }, { "base": { "currencyCode": "USD", "amount": 153.0 }, "tax": { "currencyCode": "USD", "amount": 17.98 } } ] // ... payload truncated for focus ``` ## Average nightly rate The average nightly rate is the average cost per night for a multi-night hotel booking. It's calculated by dividing the total rate by the number of nights. It's useful when hotels have dynamic pricing (different rates for different nights). ```json /v2/hotel/details // ... payload truncated for focus { "nightlyRate": [ { "base": { "currencyCode": "USD", "amount": 329 } }, { "base": { "currencyCode": "USD", "amount": 329 } }, { "base": { "currencyCode": "USD", "amount": 400 } } ], "averageNightlyRate": { "base": { "currencyCode": "USD", "amount": 353 } } } ``` ## Understanding the difference between total rate and published rate The published rate is the actual rate of the room as set by the supplier. The total rate is the price paid by the traveler to book the hotel room. In specific bookings where corporate discounts are applied, the total rate might be lower than the published rate. However, in most cases both these rates will be the same indicating that the traveler has to pay full price for the room. In certain cases, some suppliers may provide weekly discounts that are applied when a booking is made for 7 nights or more. In those scenarios, the total rate will be lower than the published rate. In the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) API, use the `publishedRate` and `publishedNightlyRate` to view the actual published rate and the published nightly rate of the hotel room. Also, use the `rateDifference` field to view the amount of difference between the published rate and total rate. This field is useful when you want to display the total savings when booking a discounted hotel room. ## Tax inclusion In many locations (e.g., Europe, Asia), the government regulations often dictate that the total price of a product sold must include the taxes and fees. For example, in Europe the price you see on a hotel listing includes the Value Added Tax (VAT) and other fees (e.g., occupancy tax). In the [get hotel details](/openapi/hotelapi/hotel/hoteldetails) API, you can set the `showOnlyBaseFare` field as `false` to display the total rate including taxes and fees. The default setting is based on the traveler's legal entity address (which can be found using the [get legal entity](/openapi/companyapi/legal-entities/getlegalentity) API). If the traveler's legal entity address is based in the U.S.A., then the `showOnlyBaseFare` field is set to `true` by default. For every other location, it's set as `false`. Tax inclusion sample image ***Fig:** The price displayed when `showOnlyBaseFare` is `false`.* br Tax exclusion sample image ***Fig:** The price displayed when `showOnlyBaseFare` is `true`.* br > **Note:** Whether the `showOnlyBaseFare` field is set to `true` or `false`, the total rate of the booking will always be displayed below the fare. As an administrator, when you're [updating your company policy](/openapi/policyapi/company-policies/updatepolicy) to set the maximum allowed budget for travelers, you can use the `isTaxIncluded` field to define if the budget also includes the taxes and fees. For example, if the maximum price allowed for a hotel booking is set as $500 and the `isTaxIncluded` field is set as `true`, then the total price paid by the traveler shouldn't exceed $500 including taxes and fees. In this scenario, a hotel listing with a base rate of $500 and a tax of $50 would be displayed as **Out of Policy**.