Commission

Commissions are how the marketplace earns revenue. Rather than storing a single commission percentage, Mercur uses a rule-based system where commission rates are matched to order line items based on configurable conditions, with a global default as the fallback.

Commission rates

A CommissionRate defines how much commission the marketplace takes and when it applies.

Field	Description
`name`	Human-readable name (e.g. “Electronics Commission”)
`code`	Unique system identifier
`type`	`fixed` (flat amount) or `percentage`
`value`	The percentage, or the flat amount used when no per-currency value matches
`values`	Per-currency amounts for `fixed` rates (`currency_code` + `amount`)
`include_tax`	Include tax in the base amount for calculation
`include_shipping`	Whether shipping methods are also commissioned (global rate only)
`is_default`	Marks the global commission — the fallback applied when no scoped rate matches
`is_enabled`	Disabled rates are skipped entirely

percentage rates use the scalar value. fixed rates read the per-currency values list and fall back to value when the order’s currency has no entry.

Commission rules

Rules determine when a rate applies. Each rule has a reference (the dimension) and a reference_id (the value to match):

Reference	Matches items whose product…
`product`	is that specific product
`product_type`	has that product type
`product_collection`	belongs to that collection
`product_category`	belongs to that category
`seller`	is sold by that seller

A rate with no rules matches everything — that’s what makes the default rate a catch-all.

The matching algorithm

For each line item:

Group the rate’s rules by dimension (reference).
A rate matches when every dimension group has at least one matching rule — AND across dimensions, OR within a dimension. Example: a rate with rules seller: A and product_category: electronics matches only electronics sold by seller A; a rate with two product_category rules matches either category.
Among all matching rates, the most specific wins — the rate scoping on the largest number of distinct dimensions.
Ties break deterministically to the oldest rate.

Example configuration:

Rate	Rules	Type	Value	Matches
Premium seller electronics	`seller: slr_abc` + `product_category: electronics`	Percentage	8%	Electronics from that seller (2 dimensions — most specific)
Electronics commission	`product_category: electronics`	Percentage	12%	Other sellers’ electronics (1 dimension)
Global commission	(none, `is_default`)	Percentage	15%	Everything else

An electronics item from seller slr_abc gets 8% — the two-dimension rate beats the one-dimension category rate, regardless of creation order.

The calculation pipeline

The getCommissionLines step calculates commissions when an order is placed:

Load all enabled rates with their rules and per-currency values. Rates pinned to a currency_code apply only to orders in that currency.
Match items — for each line item, find matching rates and pick the most specific (see above).
Calculate — the base amount is the item subtotal, plus tax when include_tax is on. Percentage: (base × value) / 100. Fixed: the per-currency amount.
Shipping — governed solely by the global commission: when its include_shipping flag is on, each shipping method gets a commission line calculated from the global rate.
Output — one CommissionLine per commissioned item and shipping method.

All commission calculations use BigNumber arithmetic for precision. This is critical for financial accuracy — standard floating-point math can introduce rounding errors.

API examples

Set up the global commission (Admin API)

curl -X POST http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Global Commission",
    "code": "global",
    "type": "percentage",
    "value": 15,
    "is_default": true,
    "include_shipping": true
  }'

Create a scoped rate with rules (Admin API)

curl -X POST http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electronics Commission",
    "code": "electronics",
    "type": "percentage",
    "value": 12,
    "rules": [
      { "reference": "product_category", "reference_id": "pcat_electronics" }
    ]
  }'

Create a fixed rate with per-currency amounts

curl -X POST http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Flat Listing Fee",
    "code": "flat-fee",
    "type": "fixed",
    "value": 2,
    "values": [
      { "currency_code": "usd", "amount": 2 },
      { "currency_code": "eur", "amount": 1.8 }
    ],
    "rules": [
      { "reference": "seller", "reference_id": "slr_abc123" }
    ]
  }'

List commission rates

curl http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>"

Commission lines

A CommissionLine is the calculated commission for a single line item or shipping method:

Field	Description
`item_id`	The order line item (null for shipping lines)
`shipping_method_id`	The shipping method (null for item lines)
`commission_rate_id`	The rate that was applied
`code`	Code of the applied rate
`rate`	The rate value used
`amount`	The calculated commission amount

Commission lines are linked to order line items via a read-only link, so an order’s items can be queried together with their commission data in a single request.

How commission connects to payouts

Commission lines are the bridge between orders and seller earnings:

An order is completed → commission lines are calculated for each item
When the order is credited to the seller’s payout account, the total commission is subtracted:
seller_earnings = order.total - sum(commission_line.amount)
The marketplace retains the commission amount

This separation means commission rates can be changed at any time without affecting already-calculated orders — the CommissionLine records serve as a permanent audit trail.

Welcome

Legal

Commission rates

Commission rules

The matching algorithm

The calculation pipeline

API examples

Set up the global commission (Admin API)

Create a scoped rate with rules (Admin API)

Create a fixed rate with per-currency amounts

List commission rates

Commission lines

How commission connects to payouts

Next steps

Payouts

Order Groups

​Commission rates

​Commission rules

​The matching algorithm

​The calculation pipeline

​API examples

​Set up the global commission (Admin API)

​Create a scoped rate with rules (Admin API)

​Create a fixed rate with per-currency amounts

​List commission rates

​Commission lines

​How commission connects to payouts

​Next steps

Payouts

Order Groups

Commission rates

Commission rules

The matching algorithm

The calculation pipeline

API examples

Set up the global commission (Admin API)

Create a scoped rate with rules (Admin API)

Create a fixed rate with per-currency amounts

List commission rates

Commission lines

How commission connects to payouts

Next steps