Sign in
commission-rules

Create Commission Rule

post/api/v1/commission-rules

Request body

property_codestring nullable
channel'voice_agent' | 'text_agent' | 'hotel_agent' | 'ota' | 'website' | 'direct_pms' | 'unknown'

Where a canonical booking originated (normalized channel attribution).

NULL on BookingRecord means "not yet derived" (legacy rows before the PR 3 backfill); UNKNOWN means "derived but undeterminable" — the two are deliberately distinct (Direct Bookings ontology §6).

providerstring nullable
cost_type'ota_commission' | 'payment_fee' | 'channel_manager_fee' | 'marketing_fee'

The kinds of charge a CommissionRule can express (PR 17 §4).

Distinct cost types STACK (one cost component each) while two rules of the same cost type compete on scope specificity. A free-form string therefore lets a user double-charge themselves by inventing "commission" alongside "ota_commission" — so the API constrains new writes to this vocabulary. The column stays a String(50): existing rows are not rewritten and no migration is needed.

OTA_COMMISSION is the default for the one-line entry path (the hotelier typing "Booking.com 18%" never chooses a cost type).

contract_basis'commissionable' | 'net_rate' | 'metasearch' | 'own_cost'

What kind of commercial arrangement a CommissionRule records (PR 19).

A rate is not a contract. "18% of gross" and "we are paid a contracted net amount" are different economics, and applying the first shape to the second produces a confident €0.00 rather than a missing number — the most expensive channel in the portfolio rendered as free.

  • COMMISSIONABLE — the hotel sets the rate and the provider invoices a percentage (or a flat fee). The PR 12 behaviour, and the default so every pre-PR-19 row keeps exactly the meaning it had.
  • NET_RATE — the hotel is paid a contracted net amount; the provider's margin is not a cost the hotel pays. No commission is computed, and the reported value (when present) already IS the net.
  • METASEARCH — billed per click or per campaign, never per booking. The rule records the arrangement so the source does not read as free; CPC spend has no per-booking home and this PR does not invent one.
  • OWN_COST — the hotel's own per-booking costs on direct business (payment gateway, booking engine). Computes exactly like COMMISSIONABLE; kept separate so "distribution cost" and "cost of taking a direct booking" never render as the same line.

NET_RATE and METASEARCH carry NO charge (a CHECK enforces it): a percentage on a net-rate rule is a configuration error that would otherwise price silently.

fixed_currencystring nullable
effective_fromstring date nullable
effective_tostring date nullable
contract_versionstring nullable

Response

Successful Response

idstring uuid required
property_codestring nullable required
channel'voice_agent' | 'text_agent' | 'hotel_agent' | 'ota' | 'website' | 'direct_pms' | 'unknown' required

Where a canonical booking originated (normalized channel attribution).

NULL on BookingRecord means "not yet derived" (legacy rows before the PR 3 backfill); UNKNOWN means "derived but undeterminable" — the two are deliberately distinct (Direct Bookings ontology §6).

providerstring nullable required
cost_typestring required
contract_basis'commissionable' | 'net_rate' | 'metasearch' | 'own_cost' required

What kind of commercial arrangement a CommissionRule records (PR 19).

A rate is not a contract. "18% of gross" and "we are paid a contracted net amount" are different economics, and applying the first shape to the second produces a confident €0.00 rather than a missing number — the most expensive channel in the portfolio rendered as free.

  • COMMISSIONABLE — the hotel sets the rate and the provider invoices a percentage (or a flat fee). The PR 12 behaviour, and the default so every pre-PR-19 row keeps exactly the meaning it had.
  • NET_RATE — the hotel is paid a contracted net amount; the provider's margin is not a cost the hotel pays. No commission is computed, and the reported value (when present) already IS the net.
  • METASEARCH — billed per click or per campaign, never per booking. The rule records the arrangement so the source does not read as free; CPC spend has no per-booking home and this PR does not invent one.
  • OWN_COST — the hotel's own per-booking costs on direct business (payment gateway, booking engine). Computes exactly like COMMISSIONABLE; kept separate so "distribution cost" and "cost of taking a direct booking" never render as the same line.

NET_RATE and METASEARCH carry NO charge (a CHECK enforces it): a percentage on a net-rate rule is a configuration error that would otherwise price silently.

ratestring nullable required
fixed_amountstring nullable required
fixed_currencystring nullable required
effective_fromstring date required
effective_tostring date nullable required
contract_versionstring required
tenant_idstring uuid required

Changes

No recorded changes to this endpoint across all 1 revision of this API.