Skip to main content
Use Mercur to decide what share of each sale the marketplace keeps and what each seller earns. Commission is the marketplace’s cut of a seller order. You define rates as a percentage or a fixed amount and scope them with rules to sellers, products, types, collections, or categories. When an order is placed, Mercur picks the most specific matching rate for every line item and writes a commission line with the amount. The payout for that order is the order total minus the sum of its commission lines. Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate. Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.
The Commission module owns four data models: CommissionRate (comrate), CommissionRule (comrule), CommissionRateValue (comval), and CommissionLine (comline). Resolve its service with MercurModules.COMMISSION from @mercurjs/types.

​
Key features

The Commission module covers configuration, resolution, and the per-order record:
  • Percentage or fixed rates: a percent of the line subtotal, or a flat amount per line
  • Per-currency amounts: a fixed rate holds one amount per currency and falls back to its value
  • Five scoping dimensions: rules match on product, product_type, product_collection, product_category, and seller
  • Most specific wins: the matching rate scoped on the most dimensions wins, and ties go to the oldest rate
  • Global commission: a seeded is_default rate that can’t be deleted and is the only rate that commissions shipping
  • Lines that follow the order: lines are written at checkout and recomputed on order edits, returns, claims, and exchanges
  • Exact arithmetic: amounts are computed with Medusa’s MathBN and stored as big numbers
  • Pluggable calculation: swap the built-in system provider for your own ICommissionProvider

​
How it works

Commission runs as part of checkout and again whenever the order changes:
  1. completeCartWithSplitOrdersWorkflow splits the cart into one order per seller.
  2. It runs refreshOrderCommissionLinesWorkflow for the new orders as a nested step.
  3. The workflow builds one calculation context per order and passes them to the active provider in one batch.
  4. The system provider loads the enabled rates once and picks the winning rate for each item.
  5. The module replaces the order’s commission lines with the new set.
  6. When a payout is created, Mercur subtracts the sum of the order’s commission lines from the order total.

​
Get started

Learn how rates, rules, and commission lines fit together.

Rules & rates

Percentage and fixed rates, per-currency amounts, and the global commission.

Rule matching

How Mercur picks one rate for each line, and how shipping is handled.

Order commission lines

What a commission line records and when it’s recomputed.

​
Examples

Build against commission in your own server code.

Create a rate

Create percentage and fixed rates with createCommissionRatesWorkflow.

Batch-update rules

Add, change, and remove a rate’s rules in one workflow run.

Refresh order lines

Recompute commission for orders and extend the calculation context.

​
Resources

The data models, links, workflows, service methods, and events behind commission.

Data models

Every field of the four commission models.

Links

How commission records point at the catalog, sellers, and orders.

Workflows

Rate, rule, and order-line workflows with their inputs and hooks.

Service

Generated and custom service methods, and commission providers.

Events

The order events that trigger a recompute.