Commissions module — JetSetGo MCP reference

The commissions module defines how agents and affiliates are paid on bookings. A commission profile is a named container referenced by agent-type clients; it holds dated versions (non-overlapping date ranges); each version holds rules of escalating priority, each carrying a commission_percent. Commission is computed at sale time from this configuration.

What the operator uses it for

Operators maintain a three-level hierarchy per partner arrangement: create a profile for an agency or affiliate scheme; cut dated versions of that arrangement (e.g. one version per contract year) with guaranteed gap-free-or-gapped but never overlapping windows; and populate each version with rate rules. Within a version, rules target either a specific resource (highest priority), a product sub-type, a product type, or nothing at all — the default fallback rule that applies when no targeted rule matches. Supporting tools cover pre-save validation reads, copying a full rule set from one version to another, and bulk-creating rules.

Where it sits

Upstream: clients — an agent-type client points at a profile via its commission-profile reference — plus the catalogues that supply rule targets (resources, product types, product sub-types; exposed here as lookup reads though owned by their own apps). Downstream: bookings compute commission at sale using the active version for the sale date, and accounting consumes the results.

Key concepts

Commission profile — the named container an agent-type client references.
Version — a dated slice of a profile; ranges within a profile must not overlap.
Rule priority ladder — resource > product_sub_type > product_type > default; each rule sets one commission_percent.
Target id — polymorphic by rule type: a resource, product-sub-type, or product-type id; null only for default rules.
Default-rule invariant — at most one default rule per version.
Soft delete — profiles, versions, and rules are retired with deleted=true; reversible.

Tools

All writes are guarded preview→confirm and require an explicit tenant.

Tool	Class	Purpose
`commissions_list_profiles`	Read	List non-deleted profiles.
`commissions_get_profile`	Read	Fetch one profile by id.
`commissions_list_versions`	Read	List a profile's versions ordered by start date.
`commissions_check_version_overlap`	Read	Test a candidate date range against sibling versions.
`commissions_list_rules`	Read	List a version's rules ordered by type.
`commissions_has_default_rule`	Read	Whether a version already has a default rule.
`commissions_list_resources`	Read	Active resource ids/names (rule-target candidates).
`commissions_list_product_types`	Read	Product-type rule-target candidates.
`commissions_list_product_sub_types`	Read	Product-sub-type rule-target candidates.
`commissions_save_profile`	Guarded write	Create or update a profile name.
`commissions_delete_profile`	Guarded write (destructive)	Soft-delete a profile.
`commissions_save_version`	Guarded write	Create or update a version with overlap enforcement.
`commissions_delete_version`	Guarded write (destructive)	Soft-delete a version (rules untouched).
`commissions_save_rule`	Guarded write	Create or update one rule with full validation.
`commissions_delete_rule`	Guarded write (destructive)	Soft-delete a rule.
`commissions_copy_rules`	Guarded write	Copy all non-deleted rules between versions.
`commissions_bulk_create_rules`	Guarded write	Insert N validated rules in one call.

Rules worth knowing

Rules attach to versions, not profiles. The foreign key is the version id — a common integration mistake carried over from stale field aliases in older frontend code.
Overlap is enforced twice. commissions_save_version checks overlap at preview and re-checks at confirm; if a sibling appeared in between, confirm fails with a re-preview request rather than writing.
The default-rule invariant is enforced at preview and confirm on create and on update-to-default, and respected by commissions_copy_rules (a second default cannot be copied into a target that has one). It is not pre-checked across a commissions_bulk_create_rules batch — check commissions_has_default_rule first.
Percent validation: commission_percent must be 0–100 with at most two decimal places; target_id is required for every non-default rule type and must be null for default.
Profile names are unique across all rows including soft-deleted ones. Deleting a profile does not free its name — rename before deleting or pick a new name.
Deleting a version leaves its rules alone. They remain attached to the soft-deleted version and are simply out of use.
Copies read the live source. commissions_copy_rules snapshots the source's current non-deleted rules into new rows; the source is unchanged.

Clients — agent-type clients reference commission profiles.
Resources — highest-priority rule targets.
Passenger & vehicle types — fare categories underpin product sub-type targeting.
Pricing — the base fares commission is calculated against at sale time.