Skip to main content
Commissions are how your marketplace earns. Mercur matches a commission rate to every order line item through rules, with one global commission as the catch-all. In this tutorial you’ll set up a realistic three-tier configuration and verify which rate wins on a real order.
The most specific rate wins. Rules combine with AND across dimensions and OR within a dimension, and among matching rates the one scoping the most dimensions applies. You never order rates by priority — specificity is the priority. The full algorithm is in Commission.

​
What you’ll build

  • A global commission of 15% that also commissions shipping.
  • A 12% rate for the Electronics category.
  • An 8% rate for Electronics sold by one specific premium seller.
An electronics order from the premium seller should produce commission lines at 8% — not 12%, not 15%.

​
Set up the rates

1

Set the global commission

Every marketplace needs exactly one default rate — the fallback when nothing more specific matches. Create it with is_default:
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
  }'
include_shipping only has an effect on the global commission — shipping methods are always commissioned from the global rate, never from scoped rates. In the Admin Panel this lives on the Global Commission card under Settings → Commissions.
2

Add a category-scoped rate

A rate becomes scoped by attaching rules. Each rule names a dimension (reference) and a value (reference_id):
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" }
    ]
  }'
Available dimensions: product, product_type, product_collection, product_category, and seller.
3

Add a two-dimension rate for the premium seller

Combining a seller rule with a product_category rule means both must match — this rate applies only to that seller’s electronics:
curl -X POST http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium seller electronics",
    "code": "premium-electronics",
    "type": "percentage",
    "value": 8,
    "rules": [
      { "reference": "seller", "reference_id": "slr_premium" },
      { "reference": "product_category", "reference_id": "pcat_electronics" }
    ]
  }'
Because it scopes two dimensions, it beats the one-dimension Electronics rate whenever both match — regardless of which rate was created first.
4

Place a test order

Commission lines are calculated when an order is placed — rates are never applied retroactively. Place an order containing an electronics item from the premium seller (via your storefront or the Store API), then inspect the order’s commission lines.

​
Verify

  1. List the rates and confirm all three exist and are enabled: 
    curl http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>"
  2. On the placed order, each electronics line item from the premium seller has a commission line with code: "premium-electronics" and rate: 8.
  3. The order’s shipping method has a commission line from the global rate (because include_shipping is on).
  4. Change a rate now and confirm the existing order’s commission lines are untouched — CommissionLine records are a permanent audit trail.

​
FAQ

Use "type": "fixed" with per-currency values: [{ "currency_code": "usd", "amount": 2 }, { "currency_code": "eur", "amount": 1.8 }]. The scalar value is the fallback for currencies without an entry.
Ties break deterministically to the oldest rate. But if you find yourself relying on tie-breaking, prefer making one rate more specific — it reads better in the Admin Panel and survives audits.
No. Commission is snapshotted into CommissionLine records at order placement. Changing or disabling a rate only affects future orders — the lines on past orders are a permanent audit trail that payouts read from.
Yes — rules within the same dimension are OR’d. A rate with two product_category rules matches items in either category, and still counts as one dimension for specificity.

​
Next steps

Commission

The full matching algorithm, calculation pipeline, and data model.

Set up seller payouts

Where commission is deducted — the settlement side of the marketplace.