The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Commission module service"
sidebarTitle: "Service"
description: "Resolve the Commission module service, its generated and custom methods, and the commission provider interface."
---
The Commission module service reads and writes commission records without a workflow. Use it in steps, subscribers, and scheduled jobs, and use the [workflows](/platform/commission/reference/workflows) when you need rollback or the global-rate delete guard.
## Resolve the service
Resolve the service from the container with `MercurModules.COMMISSION`.
```ts
import { MercurModules } from "@mercurjs/types"
const commission = container.resolve(MercurModules.COMMISSION)
const [rates, count] = await commission.listAndCountCommissionRates(
{ is_enabled: true },
{ relations: ["rules", "values"] }
)
```
The call returns enabled rates with their rules and per-currency values, plus the total count.
## Generated methods
The service extends `MedusaService`, so every model gets the standard methods. For `CommissionRate` they are:
| Method | Description |
| --- | --- |
| `retrieveCommissionRate(id, config?)` | Retrieve one rate |
| `listCommissionRates(filters?, config?)` | List rates |
| `listAndCountCommissionRates(filters?, config?)` | List rates with a count |
| `createCommissionRates(data)` | Create one rate or an array of rates |
| `updateCommissionRates(data)` | Update rates |
| `deleteCommissionRates(ids)` | Hard-delete rates |
| `softDeleteCommissionRates(ids)` | Soft-delete rates |
| `restoreCommissionRates(ids)` | Restore soft-deleted rates |
The same set exists for `CommissionRule`, `CommissionRateValue`, and `CommissionLine`, for example `listCommissionRules`, `createCommissionRateValues`, and `retrieveCommissionLine`.
<Warning>
`deleteCommissionRates` doesn’t check for the global rate. Use `deleteCommissionRatesWorkflow` to keep the `is_default` rate safe.
</Warning>
## Custom methods
The service overrides or adds these methods:
| Method | Description |
| --- | --- |
| `createCommissionRates(data)` | Fills a missing `code` from `name` plus a random suffix, then creates. Returns one rate for one input, an array for an array |
| `listCommissionRates(filters?, config?)` | Accepts a virtual `scope_type` filter |
| `listAndCountCommissionRates(filters?, config?)` | Accepts the same `scope_type` filter |
| `getCommissionLines(context)` | Computes lines for one context with the default provider. Doesn’t persist |
| `getCommissionLinesBatch(contexts)` | Computes lines for several contexts, one array per context in order. Doesn’t persist |
| `upsertCommissionLines(lines)` | Deletes existing lines with the same `item_id` or `shipping_method_id`, then inserts `lines` |
`getCommissionLines` and `getCommissionLinesBatch` stamp the default provider’s id on any line without a `provider_id`. `getCommissionLinesBatch` falls back to one `getCommissionLines` call per context when the provider has no batch method.
## Filter rates by scope type
`scope_type` filters rates by the dimensions their rules use, computed in the database. Pass one value, an array, or a comma-separated string. Several values are combined with OR, and an unknown value matches nothing.
| `scope_type` | Rates whose rules use |
| --- | --- |
| `store` | `seller` only, without `product_type` or `product_category` |
| `product_type` | `product_type`, without `seller` or `product_category` |
| `category` | `product_category`, without `seller` or `product_type` |
| `store_product_type` | `seller` and `product_type` |
| `store_category` | `seller` and `product_category`, without `product_type` |
## Commission providers
A provider computes the lines from a calculation context. The module always registers the built-in `system` provider, which implements the [rule matching](/platform/commission/concepts/rule-matching) algorithm, and uses it unless you configure another one.
```ts title="src/modules/tiered-commission/service.ts"
import { MathBN } from "@medusajs/framework/utils"
import type {
CommissionCalculationContext,
CreateCommissionLineDTO,
ICommissionProvider,
} from "@mercurjs/types"
export default class TieredCommissionProvider
implements ICommissionProvider
{
static identifier = "tiered"
async getCommissionLines(
context: CommissionCalculationContext
): Promise<CreateCommissionLineDTO[]> {
const percent = context.additional_context?.tier === "gold" ? 8 : 12
return (context.items ?? []).map((item) => ({
item_id: item.id,
code: "tiered",
rate: percent,
amount: MathBN.div(MathBN.mult(item.subtotal, percent), 100).toNumber(),
}))
}
}
```
A provider class needs a static `identifier` and `getCommissionLines`. It can add `getCommissionLinesBatch(contexts)` to load its data once per batch. The module doesn’t cap `amount`, so keep it within the item’s `total` yourself.
Export the class as a module provider so the commission module can register it.
```ts title="src/modules/tiered-commission/index.ts"
import { ModuleProvider } from "@medusajs/framework/utils"
import { MercurModules } from "@mercurjs/types"
import TieredCommissionProvider from "./service"
export default ModuleProvider(MercurModules.COMMISSION, {
services: [TieredCommissionProvider],
})
```
The module takes these options, typed as `CommissionModuleOptions`:
| Option | Description |
| --- | --- |
| `providers` | Array of `{ resolve, id, options?, is_default? }` registered next to `system` |
| `default_provider` | Provider id used for every calculation. Overrides `is_default` |
A single configured provider becomes the default without `is_default`.