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 |
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 |
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 |
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.
Next steps
Payouts
How seller earnings settle after commission.
Order Groups
The per-seller orders commissions are calculated on.
