Cancellation policies module — JetSetGo MCP reference

The policies module maintains the cancellation rulebook applied automatically when a booking is cancelled. It manages three data surfaces: cancellation policy definitions (refundability flags and change allowances), fee tiers (time-before-departure windows mapped to a fee), and the tenant-wide default policy pointer used when no specific policy applies.

What the operator uses it for

Operators author named policies that encode their refund terms, then attach them to products elsewhere. A policy states whether it is refundable at all, a refund deadline in hours before departure, how many free changes are allowed and by what cutoff hour, an apply mode (always, or if_reduction for date-change reductions only), and whether it is applied automatically by the system. Beneath each policy sit fee tiers: one tier per time window, each declaring either a percentage or a fixed fee. At cancellation time the flow finds the tier whose hours-before-departure window matches and charges accordingly. One policy can also be designated the tenant-wide fallback.

Where it sits

Downstream of product setup: resources and product variations reference these policies so bookings inherit terms at quote time; the cancel flow is the consumer of record at execution time. The default pointer lives in a generic settings row and applies wherever nothing more specific is attached. Fee outcomes interact with pricing and refunds but this module stores rules, not transactions.

Key concepts

Policy — the named rulebook: refundable flag, refund deadline, free-change allowance, apply mode.
Fee tier — a [min_hours_before, max_hours_before] window plus fee type (percent or fixed) and value.
Half-open windows — null bounds are unbounded; a tier with min_hours_before null applies even after departure has passed.
Fee semantics — the fee is what the operator keeps: 0% means full refund, 100% means none.
Apply mode — always vs if_reduction (only when a change reduces the booking's value).
Tenant default — the single fallback policy applied when a resource/variation has none.

Tools

Tool	Class	Purpose
`policies_list_policies`	Read	List policies with tier counts; filters: name contains, active.
`policies_get_policy`	Read	Fetch one policy by id with its fields.
`policies_list_tiers`	Read	List a policy's fee tiers ordered by window.
`policies_get_default`	Read	Read the current tenant default policy id and name.
`policies_save_policy`	Guarded write	Create or update a policy; create requires name + description.
`policies_deactivate_policy`	Guarded write (destructive)	Retire a policy (`active=false`) — never a hard delete.
`policies_save_tier`	Guarded write	Create or update a fee tier on a policy.
`policies_delete_tier`	Guarded write (destructive)	Hard-delete a fee tier row.
`policies_set_default`	Guarded write	Point the tenant default at a policy id.

Rules worth knowing

Retirement, not deletion, for policies. The only removal path is active=false; rows persist. Fee tiers are the opposite: they are hard-deleted rows with no soft state.
Window bounds are half-open and independently nullable. Both bounds set requires max_hours_before > min_hours_before; min_hours_before null means the tier still matches after departure; max_hours_before null means open-ended far out.
Fee values are validated by type: percent must be 0–100, fixed must be ≥ 0. Because the fee is retained revenue, a 0-value percent tier is functionally a full-refund band.
Create-time defaults are applied server-side: new policies get active=true, refundable=true, a 24-hour refund deadline, apply_mode='always', automatic application on, zero free changes, and a 48-hour free-change cutoff unless overridden. New tiers default to min_hours_before=0.
Refund deadlines are capped at 168 hours (one week) by tool validation.
The default pointer is validated before writing. policies_set_default reads the target policy during preview, so a nonexistent id fails validation instead of silently storing a dangling pointer.
Drift detection quirks. Policy rows expose no reliable last-updated timestamp and tier timestamps are not auto-bumped, so concurrent-modification checks compare full row content.
Tier ids have no separately addressable surface beyond the tools above — tiers are always managed relative to their parent policy.

Pricing — the quoted amounts these fee tiers act on at cancellation.
Clients — agent/channel arrangements whose bookings carry these terms.
Schedule — departure times that anchor every hours-before window.