Overview

The Retrieve Unit Taxes endpoint returns the tax rules currently configured for one or more units in the inventory. These tax rules represent what the supplier (property manager) has configured to be collected on reservations for the unit’s assigned tax location, and are a key input for producing accurate, transparent totals during quoting and booking.

Taxes in CiiRUS are location-driven: each unit is assigned a tax location, and that location determines which tax types apply (often 2–3 taxes depending on jurisdiction) and what percentage rates should be collected. Partners should treat this endpoint as the authoritative “configured tax rate set” for the unit, and use it to ensure your UI and financial breakdowns match supplier expectations.

This endpoint is commonly used to:

Display estimated tax totals and tax line-items in partner checkout flows
Validate whether a unit has a tax location assigned before allowing booking
Reconcile tax-related discrepancies between partner totals and supplier expectations
Support debugging when taxes appear missing due to misconfiguration or unassigned tax location

By design, this endpoint returns the supplier’s configured tax definitions. The actual tax amounts charged to a guest depend on the taxable base used during quoting (nightly rent, extras, fees, etc.), and on which line-items are configured as taxable.

Related Supplier Configuration (Optional Context)

Tax type and location configuration
- Set up tax types and tax locations
Tax location assignment at the unit level
- Assign tax locations

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/unit_taxes	Retrieve tax configurations for units in the inventory.
GET	v2024.07.31/unit_taxes/{unit_id}	Retrieve tax configuration for a specific unit in the inventory.

Path Parameters

Path Parameter	Required / Optional	Description
{unit_id}	Required	Unique Identifier for the unit in the inventory.

Query String Parameters

Parameter	Required / Optional	Description	Data Type
page	Optional	The page to be shown (defaults to 1).	int
page_size	Optional	Limits the number of returned results (defaults to 25).	int
last_unit_update_date	Optional	Only return units that have been modified after the specified date.	date-time
last_reservation_update_date	Optional	Only return units that have received a booking (their own or a calendar sync) after the specified date.	date-time
last_agent_module_property_update_date	Optional	Only return units that have had their agent module property configuration modified after the specified date.	date-time
last_agent_module_agent_update_date	Optional	Only return units that have had their agent module agent configuration modified after the specified date.	date-time
unit_id	Optional	Unique identifier for a unit in the inventory.	int
unit_ids	Optional	Unique identifiers for multiple units in the inventory.	array
management_company_user_id	Optional	Unique identifier for a specific supplier of inventory.	int
management_company_user_ids	Optional	Unique identifiers for multiple suppliers of inventory.	array
enabled	Optional	Use only enabled or disabled units.	boolean
deleted	Optional	Only show properties that are deleted or not deleted.	boolean
display_on_website	Optional	Only show properties that are enabled for the management company's website.	boolean
allocation_on_arrival	Optional	Return the allocation on arrival object.	boolean
allocation_on_arrival_unit	Optional	Return units which are the representative unit in their group.	boolean
channel	Optional	Restrict results to a specific channel’s configuration context. Leave empty for the default/general data.	string
listing_id	Optional	Lookup a unit by its channel-specific listing ID.	string

Allowed values for channel:
- all
- bdc
- vrbo
- airbnb

Response Definition

Response Item	Description	Data Type
`"unit_taxes"`	The primary result set. Each array element represents a single unit’s configured tax definition set (which taxes apply and the configured rates).	array
`"paging"`	Paging metadata used to navigate through large result sets when multiple units are returned.	object

`"unit_taxes"` Object

Response Item	Description	Data Type
`"unit_id"`	The unique unit identifier these tax settings belong to. This is the same `"unit_id"` used across the platform (`/units`, `/unit_details`, `/unit_quotes`, etc.) and should be treated as the canonical key for joining tax configuration to other unit resources.	int
`"management_company_user_id"`	The supplier (property manager) identifier that owns/manages the unit. This is important in multi-supplier inventories because tax rules and locations are supplier-defined and may vary between suppliers even within the same region.	int
`"taxes"`	An array of tax definitions that currently apply to the unit based on its assigned tax location. This may be empty if the unit has no tax location assigned, taxes are not configured for that location, or the unit is not eligible under the current integration context.	array
`"tax_rate_id"`	Internal identifier representing the unit’s underlying tax rate configuration group. If populated, this can be used for detecting when a unit’s tax configuration has changed. A value of 0 commonly indicates no resolvable tax rate group under the current context.	_int
`"location"`	Supplier-defined tax location label associated with the unit (often a county/city/region label used in the CiiRUS UI). This may be blank if the unit does not have a tax location assigned or if the location cannot be resolved under the current integration context.	string
`"error"`*	Optional error object returned when tax data cannot be provided for the unit under the current request context (for example: supplier connection disabled, unit deleted). When present, partners should treat taxes as non-actionable for booking/financial flows unless/until the underlying issue is resolved.	object

`taxes` Object

Response Item	Description	Data Type
`"name"`	Display name of the tax as configured by the supplier (for example: “Sales Tax”, “Tourist Tax”). Partners may display this label directly to users for transparency, but should not assume the label is standardized across suppliers or jurisdictions.	string
`"value"`	The configured tax rate or fixed amount in 10⁸ fixed-point format. For percentage taxes, this represents the percentage rate (for example: 750000000 = 7.5%). Partners should convert this to a human-readable decimal/percentage for display and should use it consistently when estimating tax totals.	int
`"value_type"`	Indicates how the tax should be interpreted. Most commonly `"percentage"`, meaning the tax is computed as a percent of a taxable subtotal. Partners should not assume all suppliers use percentage-only taxes forever—this field exists so the integration can handle non-percentage tax models if configured in the future. See valid value_type values.	string
`"tax_type"`	A normalized classification identifier for the tax bucket. This is the stable value you should use for mapping and reconciliation across supplier inventories. Do not rely on `"name"` for classification, as it is supplier-editable. See valid tax_type values.	string

`"error"` Object

Response Item	Description	Data Type
`"message"`	Informational error message explaining why tax data could not be produced for this unit under the current request. Common cases include: the unit being deleted, the supplier not enabling the property connection, or neither party enabling the connection. When present, partners should generally exclude the unit from booking/quote flows until corrected.	string

`"paging"` Object

Response Item	Description	Data Type
`"next_page_url"`	A URL that can be used to retrieve the next page of supplier results, if additional pages exist.	string
`"previous_page_url"`	A URL that can be used to retrieve the previous page of supplier results, if applicable.	string
`"total_page_count"`	The total number of available pages for the current request.	int
`"page"`	The current page number being returned.	int
`"page_size"`	The number of records being included per page.	int

Sample Request

curl --location 'https://api.ciiruspartners.com/v2024.07.31/unit_taxes?page=1&page_size=25' \
--header 'Authorization: Basic {APIUsername:APIPassword}'

Sample Response

{
    "unit_taxes": [
        {
            "unit_id": 219264,
            "management_company_user_id": 42330,
            "taxes": [
                {
                    "name": "Sales Tax",
                    "value": 750000000,
                    "value_type": "percentage",
                    "tax_type": "tax_one"
                },
                {
                    "name": "Tourist Tax",
                    "value": 600000000,
                    "value_type": "percentage",
                    "tax_type": "tax_two"
                }
            ]
        },
        {
            "unit_id": 219265,
            "management_company_user_id": 42330,
            "taxes": [
                {
                    "name": "Sales Tax",
                    "value": 700000000,
                    "value_type": "percentage",
                    "tax_type": "tax_one"
                },
                {
                    "name": "Tourist Tax",
                    "value": 500000000,
                    "value_type": "percentage",
                    "tax_type": "tax_two"
                }
            ]
        },
        {
            "unit_id": 219266,
            "management_company_user_id": 42330,
            "taxes": [
                {
                    "name": "Sales Tax",
                    "value": 650000000,
                    "value_type": "percentage",
                    "tax_type": "tax_one"
                },
                {
                    "name": "Tourist Tax",
                    "value": 600000000,
                    "value_type": "percentage",
                    "tax_type": "tax_two"
                }
            ]
        },
        {
            "unit_id": 219267,
            "management_company_user_id": 42330,
            "taxes": [
                {
                    "name": "Sales Tax",
                    "value": 650000000,
                    "value_type": "percentage",
                    "tax_type": "tax_one"
                },
                {
                    "name": "Tourist Tax",
                    "value": 600000000,
                    "value_type": "percentage",
                    "tax_type": "tax_two"
                }
            ]
        },
        {
            "unit_id": 219268,
            "management_company_user_id": 42330,
            "taxes": [
                {
                    "name": "Sales Tax",
                    "value": 650000000,
                    "value_type": "percentage",
                    "tax_type": "tax_one"
                },
                {
                    "name": "Tourist Tax",
                    "value": 600000000,
                    "value_type": "percentage",
                    "tax_type": "tax_two"
                }
            ]
        }
    ],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_taxes?page=2&page_size=25",
        "total_page_count": 6,
        "page": 1,
        "page_size": 25
    }
}