Skip to main content
The Commission module owns commission configuration and calculation. Operators define commission rates (percentage or fixed, optionally per-currency) with a set of rules that scope where a rate applies. During checkout, the module resolves the most specific matching rate per order item and persists idempotent commission lines on the order. For the conceptual introduction, see Commissions.

​
Data models

​
CommissionRate

Table commission_rate, ID prefix comrate.
FieldTypeNotes
nametextSearchable
codetextUnique; auto-generated from name when omitted
typeenumfixed or percentage
valuebigNumberThe percentage or the fixed amount
is_enabledbooleanDefault true
is_defaultbooleanDefault false; the platform fallback rate
currency_codetextNullable; restricts the rate to one currency
include_taxbooleanDefault false; commission is computed on the tax-inclusive amount
include_shippingbooleanDefault false; adds shipping commission lines from the default rate
Relations: rules (one-to-many CommissionRule), values (one-to-many CommissionRateValue).

​
CommissionRule

Table commission_rule, ID prefix comrule. A rule scopes its rate to one reference:
FieldTypeNotes
referencetextOne of product, product_type, product_collection, product_category, seller
reference_idtextThe referenced entity’s ID

​
CommissionRateValue

Table commission_rate_value, ID prefix comval. Per-currency amounts for fixed rates:
FieldType
currency_codetext
amountbigNumber

​
CommissionLine

Table commission_line, ID prefix comline. The persisted result of a calculation, anchored to an order item or shipping method:
FieldTypeNotes
item_idtextNullable; the order line item
shipping_method_idtextNullable; set for shipping commission lines
commission_rate_idtextNullable; the rate that produced this line
codetextRate code snapshot
ratefloatRate value snapshot
amountbigNumberComputed commission
descriptiontextNullable

​
Enums

enum CommissionRateType {
  FIXED = "fixed",
  PERCENTAGE = "percentage",
}

​
Rate matching

When multiple rates match an order item, the module resolves them deterministically:
  1. Only enabled rates whose currency_code matches (or is unset) are considered.
  2. Rules combine AND across dimensions, OR within a dimension — a rate with a seller rule and a product_category rule matches only items that satisfy both.
  3. The most specific rate wins (the one matching on the most dimensions).
  4. Ties break to the oldest-created rate.
  5. If nothing matches, the rate flagged is_default applies.
List endpoints additionally accept a virtual scope_type filter (store, product_type, category, store_product_type, store_category) that the service translates into SQL predicates over the rules table.

​
Service

CommissionModuleService extends MedusaService with auto-generated CRUD for all models above, plus:
MethodBehavior
getCommissionLines(context)The core calculator — resolves the matching rate per item, computes amounts (percentage of the subtotal, or the per-currency fixed amount), and appends shipping lines when the winning rate has include_shipping
upsertCommissionLines(lines)Idempotent replace: deletes existing lines for the same item/shipping anchors, then inserts
createCommissionRates(data)Auto-generates a unique code from name when absent
listCommissionRates / listAndCountCommissionRatesApply the virtual scope_type filter
A loader seeds a default commission rate on first boot.
  • GET/POST /admin/commission-rates, POST /admin/commission-rates/:id/rules — see Admin API
  • GET /admin/orders/:id/commission-lines and GET /vendor/orders/:id/commission-lines expose the computed lines per order.

​
Next steps

Seller module

Payout module