Skip to main content
A commission rate is the cut the marketplace takes from a sale, and rules decide which lines it applies to. Every marketplace has one global rate that covers everything, and you add scoped rates on top of it for specific sellers or parts of the catalog. Getting this model right decides what every seller is paid.

​
A rate is a type and a value

A rate is a CommissionRate record (id prefix comrate). Its type says how to read its value, and two flags change the base amount the value applies to. The base amount is the line’s subtotal. A rate changes it with these flags:
  • include_tax: adds the line’s tax_total to the base before the rate applies
  • include_shipping: lets the rate commission shipping methods, and only takes effect on the global rate
  • is_enabled: disabled rates are skipped during resolution
A fixed rate applies once per line item, not once per unit. A line with a quantity of 3 still gets one fixed amount. The system provider doesn’t cap a fixed amount at the line total.
Each rate also has a name and a unique code. When you create a rate without a code, the module builds one from the name plus a random suffix, so "Standard" becomes something like standard-k3x9qa.
The example creates a 10% rate with no rules, which matches every line until a more specific rate wins.

​
Per-currency amounts for fixed rates

A fixed rate holds one amount per currency in CommissionRateValue records (id prefix comval). During resolution, Mercur picks the value whose currency_code equals the order’s currency. When none matches, it uses the rate’s own value. Percentage rates ignore values, because a percent is the same in every currency. A rate’s own currency_code field is separate: when it’s set, the rate only applies to orders in that currency.

​
Rules scope a rate

A rule is a CommissionRule record (id prefix comrule) that belongs to one rate. It’s a reference naming a dimension and a reference_id naming the record, for example seller and sel_01JD8Q1234567. A rate without rules matches every line. A rate with rules matches only the lines that satisfy them. The five dimensions are:
  • product: a master product id
  • product_type: a product type id
  • product_collection: a collection id
  • product_category: a category id
  • seller: the seller of the offer on the order line
Rule matching explains how rules combine and which rate wins when several match.

​
The global commission

The global commission is the rate with is_default: true. The module seeds it on boot when none exists, as a 0% percentage rate named Default with the code default. You raise it to set the marketplace’s baseline cut. The global rate has rules that set it apart:
  • Always present: deleteCommissionRatesWorkflow throws NOT_ALLOWED if you try to delete it
  • Fallback for items: it has no rules, so it matches every line and loses to any scoped rate that also matches
  • Only shipping rate: its include_shipping flag is the only one that produces shipping commission lines
Nothing stops you from setting include_shipping on a scoped rate, but the flag has no effect there. Shipping is resolved from the global rate alone.