Create or update property-level and product-scoped tax configuration. Requires hotels and products to exist first.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Taxes
POST /push/taxes
Configure taxes for a property. A payload can carry property-level taxes, product-scoped taxes, or both. Requires the hotel to exist, and any referenced roomId or rateId to have been created via Hotel rooms & rates.
Try it (curl)
curl -sS -X POST "https://ari-dev.thehotelplanet.com/v1/push/taxes" \
-H "x-api-key: YOUR_SANDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hotelId":"TEST001","taxes":[{"type":"VAT","valueType":"%","value":20,"appliedOn":"net","appliedPer":"per_room_per_stay","included":true,"payNow":true}]}'Request
| Field | Type | Description |
|---|---|---|
hotelId | string | Your property code |
taxes | array | Optional. Property-level taxes |
products | array | Optional. Product-scoped taxes |
At least one of taxes or products is required.
Product scoping
Each products entry needs at least one of roomId / rateId, giving three scopes:
| Sent | Applies to |
|---|---|
roomId only | That room, with any rate |
rateId only | That rate, with any room |
| both | That specific room-rate pairing |
Tax object
| Field | Type | Description |
|---|---|---|
type | string | VAT, CITY_TAX, LOCAL_TAX, GOV_TAX, OTHER_TAX |
valueType | string | % or fixed |
value | number | Percentage or flat amount in property currency. Must be ≥ 0 |
appliedOn | string | net or net+vat. net+vat is not permitted for VAT |
appliedPer | string | per_room_per_night, per_person_per_night, per_room_per_stay, per_person_per_stay |
included | boolean | Whether the tax is already in the pushed price. true implies payNow: true |
payNow | boolean | Whether Nuitee Cloud charges the tax now |
startDate | string | Optional. YYYY-MM-DD — required together with endDate |
endDate | string | Optional. YYYY-MM-DD — required together with startDate |
Example
{
"hotelId": "HOTEL_001",
"taxes": [
{
"type": "VAT",
"valueType": "%",
"value": 20,
"appliedOn": "net",
"appliedPer": "per_room_per_stay",
"included": true,
"payNow": true,
"startDate": "2026-01-01",
"endDate": "2026-12-31"
}
],
"products": [
{
"roomId": "ROOM_001",
"taxes": [
{
"type": "CITY_TAX",
"valueType": "fixed",
"value": 5,
"appliedOn": "net",
"appliedPer": "per_person_per_night",
"included": false,
"payNow": false
}
]
},
{
"rateId": "RATE_001",
"taxes": [
{
"type": "GOV_TAX",
"valueType": "fixed",
"value": 3,
"appliedOn": "net",
"appliedPer": "per_room_per_stay",
"included": false,
"payNow": true
}
]
},
{
"roomId": "ROOM_001",
"rateId": "RATE_001",
"taxes": [
{
"type": "LOCAL_TAX",
"valueType": "%",
"value": 2,
"appliedOn": "net",
"appliedPer": "per_room_per_night",
"included": false,
"payNow": false
}
]
}
]
}Replacement behaviour
A write replaces the taxes for exactly the scopes present in the payload and leaves everything else alone. Updating a room-rate tax doesn't disturb a room-only tax on the same room. Omitting taxes leaves property-level taxes untouched; omitting products leaves all product-scoped taxes untouched.
Success response
{ "code": "200", "message": "Taxes saved successfully" }Common errors
| Message | Cause | Fix |
|---|---|---|
hotelId is required | Missing hotelId | Include your property code |
at least one of taxes or products is required | Empty payload | Send at least one |
each product entry requires at least one of roomId or rateId | Unscoped product entry | Add a room or rate code |
room id not found | Room hasn't been pushed | Send Hotel rooms & rates first |
rate id not found | Rate plan hasn't been pushed | Send Hotel rooms & rates first |
Hotel not found | Unknown hotelId | Send Hotels list first |
Notes
- Read your configuration back with Get Taxes.
- Fees sent via
cancelPolicies[].feeson Hotel rooms & rates are separate and unaffected by this endpoint.