Channels & merchant of record
The same room, the same city, the same dates — but who sells it changes who collects the tax, sometimes which tax applies, and how the invoice is framed. This page covers the booking channel, the merchant-of-record routing, and channel-scoped rates.
The booking channel
A stay reaches a guest through one of three channels, and the engine resolves the channel from the fields you send:
- Direct — the property sells to the guest (a hotel's own site, the front desk). The default when no platform fields are set.
- OTA / agency — an online travel agency intermediates but the property remains the merchant of record. Set
merchant_of_record="property". - Marketplace / platform — the platform is the merchant of record (or a marketplace facilitator). Set
merchant_of_record="platform"(andis_marketplace/platform_typeas relevant).
The channel matters because the tax answer can genuinely differ by who sells — both in who remits and, in some cities, in which rate applies at all.
Merchant of record & collection routing
The merchant of record (MoR) is whoever is legally on the hook to collect and remit. It does not usually change the amount of tax — it changes the routing: which party collects which component. The response carries a collection_info block that splits every component into who collects it.
| Field | Type | Description |
|---|---|---|
| merchant_of_record | "property" | "platform" | "none" | Who is the merchant of record. property → OTA agency model; platform → platform/marketplace MoR. Drives the collection split. |
| collection_info.platform_collected_components | string[] | Component categories the platform collects under this MoR. |
| collection_info.property_collected_components | string[] | Component categories that remain the property's to collect. |
/v1/tax/calculate once per channel with the appropriate MoR — each call returns that channel's collection routing.Channel-scoped rates
Sometimes the channel changes which rate applies, not just who collects. A rate can be scoped to specific channels via applies_to_channels (["direct"], ["platform"], ["marketplace"]); a NULL scope means all channels. The engine drops any rate whose channel scope doesn't match the booking before additive stacking, and treats channel-scoped rates as distinct layers.
Mexico City illustrates the shape: Article 162 (direct) and Article 162-bis (platform) are two separate rates, each scoped to its channel — not one rate plus a hand-authored mutual-exemption rule. A direct booking draws 162; a platform booking draws 162-bis; never both.
// Mexico City — Art. 162 (direct sales)
{ "tax_category": "occ_pct", "rate_value": 0.035,
"applies_to_channels": ["direct"] }
// Mexico City — Art. 162-bis (platform sales)
{ "tax_category": "tourism_pct", "rate_value": 0.05,
"applies_to_channels": ["platform", "marketplace"] }applies_to_channels is an engine capability; the Mexico City snippet above is illustrative of how a channel-scoped rate would be authored, not the live data configuration today. No live rate currently sets applies_to_channels (it is NULL on the MX-CMX rates), and the engine still returns the correct direct-vs-platform answer for those bookings through the other channel-aware paths above.Commission line items
On an agency booking the OTA's commission can itself be taxable where the law applies. That commission is modeled as its own line_items entry of type commission, taxed by a dedicated commission VAT rate (base_type=commission_amount) — separate from the room. This is also where cross-border B2B reverse charge lands: never on the room, always on the commission line. See Cross-border B2B & reverse charge.
What this means for you
For your direct bookings you usually send nothing extra — the default is direct, property-collected, and you remit every component. When you sell the same room through an OTA on an agency model, set merchant_of_record="property" so collection_info shows what the OTA collects on your behalf vs. what you still owe.
See Hotels for the end-to-end direct flow.
Where to go next
The full scenario → field map lives in Scenario fields. Reverse charge on the commission line is in Cross-border B2B & reverse charge, and a self-billed invoice in the supplier's name is in Self-billing.