Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

3.7 KB
Raw Blame
---
title: "Commission data models"
sidebarTitle: "Data models"
description: "Every field of CommissionRate, CommissionRule, CommissionRateValue, and CommissionLine."
---

The Commission module owns four data models, defined in `packages/core/src/modules/commission/models`. Every model also has `created_at`, `updated_at`, and a nullable `deleted_at`, which Medusa adds and the tables below leave out.

## CommissionRate

The rate the marketplace takes from a sale. Table `commission_rate`, id prefix `comrate`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
| `name` | text | Display name, searchable |
| `code` | text | Unique among non-deleted rates and searchable. Generated from `name` when omitted on create |
| `type` | enum | `CommissionRateType`: `fixed` or `percentage` |
| `value` | bigNumber | The percent for `percentage`, the fallback amount for `fixed` |
| `currency_code` | text, nullable | When set, the rate applies only to orders in this currency |
| `include_tax` | boolean | Default `false`. Adds the line’s `tax_total` to the base amount |
| `include_shipping` | boolean | Default `false`. Produces shipping lines, on the `is_default` rate only |
| `is_enabled` | boolean | Default `true`. Disabled rates are skipped |
| `is_default` | boolean | Default `false`. Marks the global commission, which can’t be deleted |

Relations:

- **`rules`**: has many `CommissionRule`
- **`values`**: has many `CommissionRateValue`

## CommissionRule

Scopes a rate to one record in one dimension. Table `commission_rule`, id prefix `comrule`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
| `reference` | text | The dimension: `product`, `product_type`, `product_collection`, `product_category`, or `seller` |
| `reference_id` | text | The id of the record in that dimension |
| `commission_rate_id` | text | Foreign key to the owning rate |

Relations:

- **`commission_rate`**: belongs to `CommissionRate`

The table has an index on `(reference, reference_id)` for non-deleted rows.

## CommissionRateValue

A per-currency amount for a fixed rate. Table `commission_rate_value`, id prefix `comval`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
| `currency_code` | text | The currency this amount applies to, such as `usd` |
| `amount` | bigNumber | The fixed commission per line item in that currency |
| `commission_rate_id` | text | Foreign key to the owning rate |

Relations:

- **`commission_rate`**: belongs to `CommissionRate`

## CommissionLine

The resolved commission for one order line item or shipping method. Table `commission_line`, id prefix `comline`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
| `item_id` | text, nullable | The order line item this line commissions |
| `shipping_method_id` | text, nullable | The order shipping method this line commissions |
| `commission_rate_id` | text, nullable | The rate that produced the line. Plain text, not a relation |
| `provider_id` | text | Default `system`. The provider that computed the line |
| `code` | text | The code of the rate that produced the line |
| `rate` | float | The percent, or the fixed amount, that was applied |
| `amount` | bigNumber | The commission amount |
| `description` | text, nullable | `Shipping Commission` on shipping lines from the `system` provider |
| `data` | json, nullable | Free data from the provider |

The table has indexes on `item_id` and on `shipping_method_id` for non-deleted rows. A line sets one of the two anchors and leaves the other `null`.

## Enums

`CommissionRateType` is exported from `@mercurjs/types`.

| Member | Value |
| --- | --- |
| `CommissionRateType.FIXED` | `fixed` |
| `CommissionRateType.PERCENTAGE` | `percentage` |