@mercurjs/docs 2.2.0-canary.40

package/content/references/api/vendor/sellers/upsert-payment-details.mdx

@@ -0,0 +1,74 @@
+---
+title: "Upsert Payment Details"
+api: "POST /vendor/sellers/{id}/payment-details"
+description: "Create or update the seller's bank account details."
+---
+
+Upserts the seller's payment details and returns the full seller object.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The seller's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="country_code" type="string">Bank country code.</ParamField>
+<ParamField body="holder_name" type="string">Account holder name.</ParamField>
+<ParamField body="bank_name" type="string">Bank name.</ParamField>
+<ParamField body="iban" type="string">IBAN.</ParamField>
+<ParamField body="bic" type="string">BIC / SWIFT code.</ParamField>
+<ParamField body="routing_number" type="string">Routing number.</ParamField>
+<ParamField body="account_number" type="string">Account number.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed to workflow hooks.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller's ID.</ResponseField>
+    <ResponseField name="payment_details" type="object">The updated payment details.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/sellers/sel_01HXYZ/payment-details' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"holder_name": "Acme Inc.", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX"}'
+```
+
+```ts JS Client
+const { seller } = await client.vendor.sellers.$id.paymentDetails.mutate({
+  $id: "sel_01HXYZ",
+  holder_name: "Acme Inc.",
+  iban: "DE89370400440532013000",
+  bic: "COBADEFFXXX",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "seller": {
+    "id": "sel_01HXYZ",
+    "name": "Acme Store",
+    "payment_details": {
+      "holder_name": "Acme Inc.",
+      "iban": "DE89370400440532013000",
+      "bic": "COBADEFFXXX"
+    }
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/sellers/upsert-professional-details.mdx

@@ -0,0 +1,70 @@
+---
+title: "Upsert Professional Details"
+api: "POST /vendor/sellers/{id}/professional-details"
+description: "Create or update the seller's business registration details."
+---
+
+Upserts the seller's professional details and returns the full seller object.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The seller's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="corporate_name" type="string">Registered corporate name.</ParamField>
+<ParamField body="registration_number" type="string">Business registration number.</ParamField>
+<ParamField body="tax_id" type="string">Tax identification number.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed to workflow hooks.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller's ID.</ResponseField>
+    <ResponseField name="professional_details" type="object">The updated professional details.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/sellers/sel_01HXYZ/professional-details' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"corporate_name": "Acme Inc.", "registration_number": "HRB 12345", "tax_id": "DE123456789"}'
+```
+
+```ts JS Client
+const { seller } = await client.vendor.sellers.$id.professionalDetails.mutate({
+  $id: "sel_01HXYZ",
+  corporate_name: "Acme Inc.",
+  registration_number: "HRB 12345",
+  tax_id: "DE123456789",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "seller": {
+    "id": "sel_01HXYZ",
+    "name": "Acme Store",
+    "professional_details": {
+      "corporate_name": "Acme Inc.",
+      "registration_number": "HRB 12345",
+      "tax_id": "DE123456789"
+    }
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/sellers/upsert-seller-address.mdx

@@ -0,0 +1,81 @@
+---
+title: "Upsert Seller Address"
+api: "POST /vendor/sellers/{id}/address"
+description: "Create or update the seller's address."
+---
+
+Upserts the seller's address and returns the full seller object.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The seller's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="name" type="string">Address label.</ParamField>
+<ParamField body="company" type="string">Company name.</ParamField>
+<ParamField body="first_name" type="string">Contact first name.</ParamField>
+<ParamField body="last_name" type="string">Contact last name.</ParamField>
+<ParamField body="address_1" type="string">Street address.</ParamField>
+<ParamField body="address_2" type="string">Apartment, suite, etc.</ParamField>
+<ParamField body="city" type="string">City.</ParamField>
+<ParamField body="country_code" type="string">Two-letter country code.</ParamField>
+<ParamField body="province" type="string">Province or state.</ParamField>
+<ParamField body="postal_code" type="string">Postal code.</ParamField>
+<ParamField body="phone" type="string">Phone number.</ParamField>
+<ParamField body="metadata" type="object">Custom key-value pairs.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed to workflow hooks.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller's ID.</ResponseField>
+    <ResponseField name="address" type="object">The updated address.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/sellers/sel_01HXYZ/address' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"address_1": "123 Main St", "city": "New York", "country_code": "us", "postal_code": "10001"}'
+```
+
+```ts JS Client
+const { seller } = await client.vendor.sellers.$id.address.mutate({
+  $id: "sel_01HXYZ",
+  address_1: "123 Main St",
+  city: "New York",
+  country_code: "us",
+  postal_code: "10001",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "seller": {
+    "id": "sel_01HXYZ",
+    "name": "Acme Store",
+    "address": {
+      "address_1": "123 Main St",
+      "city": "New York",
+      "country_code": "us",
+      "postal_code": "10001"
+    }
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor.mdx

@@ -0,0 +1,150 @@
+---
+title: "Vendor API"
+description: "Seller-scoped routes under /vendor/* — every request operates on the authenticated member's selected seller."
+---
+
+The Vendor API is the seller's surface. Every route is scoped to one seller through the member authentication and `x-seller-id` mechanism described in [API conventions](/rc/references/api/conventions#vendor) — a seller can never read or mutate another seller's data.
+
+## Account and team
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/sellers` | Registration lookup / create a seller account (**public**) |
+| `POST` | `/vendor/sellers/select` | Select the active seller for the session |
+| `GET` `POST` | `/vendor/sellers/me` | Retrieve / update the current seller |
+| `POST` | `/vendor/sellers/:id/address` | Upsert the seller address |
+| `POST` | `/vendor/sellers/:id/payment-details` | Upsert payment details |
+| `POST` `DELETE` | `/vendor/sellers/:id/professional-details` | Upsert / remove professional details |
+| `GET` `POST` | `/vendor/sellers/:id/members` | List / manage members |
+| `POST` `DELETE` | `/vendor/sellers/:id/members/:member_id` | Update role / remove a member |
+| `GET` | `/vendor/sellers/:id/members/me` | The current member within this seller |
+| `GET` | `/vendor/sellers/:id/members/invites` | List pending invites |
+| `GET` `POST` | `/vendor/members/me` | Retrieve / update the current member profile |
+| `POST` | `/vendor/members/invites/accept` | Accept an invite (**public**) |
+
+## Products and offers
+
+Products are shared master records: updates stage a [change request](/rc/references/modules/product-edit) rather than writing directly, and the list shows products the seller created plus published, unrestricted products.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/products` | List / create a product (created as `proposed`) |
+| `GET` `POST` `DELETE` | `/vendor/products/:id` | Retrieve / request an update / request deletion |
+| `GET` | `/vendor/products/:id/preview` | Preview with pending changes applied |
+| `POST` | `/vendor/products/:id/cancel` | Withdraw the pending change request |
+| `POST` | `/vendor/products/:id/attributes/batch` | Batch add / update / remove attributes |
+| `GET` `POST` | `/vendor/products/:id/variants` | List / create variants |
+| `GET` `POST` `DELETE` | `/vendor/products/:id/variants/:variant_id` | Retrieve / update / delete a variant |
+| `GET` | `/vendor/product-variants` | List variants across products |
+| `GET` `POST` | `/vendor/offers` | List / create offers |
+| `GET` `POST` `DELETE` | `/vendor/offers/:id` | Retrieve / update / delete an offer |
+| `POST` | `/vendor/offers/batch` | Batch create offers |
+| `POST` | `/vendor/offers/:id/inventory-items/batch` | Link inventory items to an offer |
+
+### Catalog taxonomy (read-only)
+
+`GET /vendor/product-categories[/:id]`, `/vendor/product-tags[/:id]`, `/vendor/product-types[/:id]`, `/vendor/product-attributes[/:id]`, `/vendor/collections[/:id]` — plus `POST /vendor/product-categories/:id/products` and `POST /vendor/collections/:id/products` to place own products.
+
+## Orders and fulfillment
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/vendor/orders` | List the seller's orders |
+| `GET` | `/vendor/orders/:id` | Retrieve an order |
+| `GET` | `/vendor/orders/:id/preview` | Preview with pending edits |
+| `GET` | `/vendor/orders/:id/changes` | List order changes |
+| `GET` | `/vendor/orders/:id/commission-lines` | Commission charged on the order |
+| `POST` | `/vendor/orders/:id/complete` | Complete the order |
+| `POST` | `/vendor/orders/:id/cancel` | Cancel the order |
+| `POST` | `/vendor/orders/:id/fulfillments` | Create a fulfillment |
+| `POST` | `/vendor/orders/:id/fulfillments/:fulfillment_id/cancel` | Cancel a fulfillment |
+| `POST` | `/vendor/orders/:id/fulfillments/:fulfillment_id/mark-as-delivered` | Mark delivered |
+| `POST` | `/vendor/orders/:id/fulfillments/:fulfillment_id/shipments` | Create a shipment |
+
+### Order edits, returns, claims, exchanges
+
+Full RMA suites exist per domain, following the same action pattern Medusa uses (begin → stage item/shipping actions → request → confirm):
+
+- `POST /vendor/order-edits` + `/:id/request|confirm|items|shipping-method` sub-routes
+- `GET/POST /vendor/returns` + `/:id/request-items|dismiss-items|receive-items|receive|shipping-method` sub-routes
+- `GET/POST /vendor/claims` + `/:id/claim-items|inbound|outbound` sub-routes
+- `GET/POST /vendor/exchanges` + `/:id/inbound|outbound` sub-routes
+- `GET /vendor/return-reasons[/:id]`, `GET /vendor/refund-reasons[/:id]`
+
+### Payments
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/vendor/payments[/:id]` | List / retrieve payments |
+| `POST` | `/vendor/payments/:id/capture` | Capture a payment |
+| `POST` | `/vendor/payments/:id/refund` | Refund a payment |
+| `GET` | `/vendor/payments/payment-providers` | List payment providers |
+
+## Payouts
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/vendor/payouts[/:id]` | Payout history |
+| `GET` `POST` | `/vendor/payout-accounts` | Retrieve / create the payout account |
+| `POST` | `/vendor/payout-accounts/:id/onboarding` | Start or refresh provider onboarding |
+
+## Inventory and stock locations
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/inventory-items` | List / create inventory items |
+| `GET` `POST` `DELETE` | `/vendor/inventory-items/:id` | Retrieve / update / delete an item |
+| `GET` `POST` | `/vendor/inventory-items/:id/location-levels` | List / create location levels |
+| `POST` `DELETE` | `/vendor/inventory-items/:id/location-levels/:location_id` | Update / delete a level |
+| `POST` | `/vendor/inventory-items/location-levels/batch` | Batch update levels |
+| `GET` `POST` | `/vendor/reservations[/:id]` | Manage reservations |
+| `GET` `POST` | `/vendor/stock-locations` | List / create stock locations |
+| `GET` `POST` `DELETE` | `/vendor/stock-locations/:id` | Retrieve / update / delete a location |
+| `POST` | `/vendor/stock-locations/:id/fulfillment-sets` | Create a fulfillment set |
+| `POST` | `/vendor/stock-locations/:id/fulfillment-providers` | Link fulfillment providers |
+| `POST` | `/vendor/stock-locations/:id/sales-channels` | Link sales channels |
+
+## Shipping
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/shipping-options` | List / create shipping options |
+| `GET` `POST` `DELETE` | `/vendor/shipping-options/:id` | Retrieve / update / delete an option |
+| `POST` | `/vendor/shipping-options/:id/rules/batch` | Batch manage option rules |
+| `GET` | `/vendor/shipping-option-types[/:id]` | List option types |
+| `GET` `POST` | `/vendor/shipping-profiles` | List / create profiles |
+| `GET` `POST` `DELETE` | `/vendor/shipping-profiles/:id` | Retrieve / update / delete a profile |
+| `DELETE` | `/vendor/fulfillment-sets/:id` | Delete a fulfillment set |
+| `POST` | `/vendor/fulfillment-sets/:id/service-zones` | Create a service zone |
+| `GET` `POST` `DELETE` | `/vendor/fulfillment-sets/:id/service-zones/:zone_id` | Manage a service zone |
+| `GET` | `/vendor/fulfillment-providers` | List fulfillment providers |
+
+## Pricing, promotions, customers
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/price-lists[/:id]` | Manage price lists (+ `/:id/prices`, `/:id/prices/batch`, `/:id/products`) |
+| `GET` | `/vendor/price-preferences[/:id]` | Read price preferences |
+| `GET` `POST` | `/vendor/promotions[/:id]` | Manage promotions (+ rule batch sub-routes and rule option lookups) |
+| `GET` `POST` | `/vendor/campaigns[/:id]` | Manage campaigns (+ `/:id/promotions`) |
+| `GET` | `/vendor/customers[/:id]` | The seller's customers |
+| `POST` | `/vendor/customers/:id/customer-groups` | Manage a customer's groups |
+| `GET` `POST` | `/vendor/customer-groups[/:id]` | Manage customer groups (+ `/:id/customers`) |
+
+## Configuration and misc
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` `POST` | `/vendor/sales-channels[/:id]` | Manage sales channels (+ `/:id/products`) |
+| `GET` | `/vendor/regions[/:id]` | Read regions |
+| `GET` | `/vendor/currencies[/:code]` | Read currencies |
+| `GET` | `/vendor/stores` | List stores (**public**) |
+| `GET` | `/vendor/feature-flags` | Feature flags (**public**) |
+| `POST` | `/vendor/uploads` | Upload files |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Store API" href="/rc/references/api/store" />
+  <Card title="API Client" href="/rc/tools/api-client" />
+</CardGroup>

package/content/references/configuration.mdx

@@ -0,0 +1,155 @@
+---
+title: "Configuration"
+description: "withMercur() options, environment variables, and provider configuration."
+---
+
+Mercur is configured through the standard Medusa config file. `withMercur()` wraps `defineConfig()` and wires the marketplace layer in — you pass it the same shape you would pass to Medusa, plus one Mercur-specific field.
+
+## withMercur()
+
+```ts medusa-config.ts
+import { loadEnv } from "@medusajs/framework/utils"
+import { withMercur } from "@mercurjs/core"
+
+loadEnv(process.env.NODE_ENV || "development", process.cwd())
+
+module.exports = withMercur({
+  projectConfig: {
+    databaseUrl: process.env.DATABASE_URL,
+    redisUrl: process.env.REDIS_URL,
+    http: {
+      storeCors: process.env.STORE_CORS!,
+      adminCors: process.env.ADMIN_CORS!,
+      vendorCors: process.env.VENDOR_CORS!, // Mercur-specific
+      authCors: process.env.AUTH_CORS!,
+      jwtSecret: process.env.JWT_SECRET,
+      cookieSecret: process.env.COOKIE_SECRET,
+    },
+  },
+  featureFlags: {
+    seller_registration: true,
+  },
+  modules: [
+    // your modules and providers
+  ],
+})
+```
+
+The option surface is Medusa's `InputConfigWithArrayModules` extended with:
+
+| Option | Type | Purpose |
+| --- | --- | --- |
+| `projectConfig.http.vendorCors` | `string` | CORS origins for the Vendor API (`/vendor/*`) — the only Mercur-specific option |
+
+### What withMercur applies
+
+| Behavior | Detail |
+| --- | --- |
+| Registers the core plugin | Appends `@mercurjs/core` to `plugins` unless already present |
+| Registers RBAC | Appends the `@medusajs/medusa/rbac` module and forces `featureFlags.rbac = true`, so vendor role scoping works out of the box |
+| Disables the Medusa admin | `admin.disable` defaults to `true` — Mercur ships its own dashboards |
+| Adjusts core middlewares | Replaces the Medusa middlewares that Mercur overrides (e.g. collections with media) |
+
+Everything you pass is otherwise forwarded to `defineConfig()` unchanged, so any valid Medusa configuration remains valid here.
+
+## Environment variables
+
+The starter (`apps/api` and projects created with `create-mercur-app`) reads:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `DATABASE_URL` | Postgres connection string | — (required) |
+| `REDIS_URL` | Redis for cache, event bus, workflow engine, locking | `redis://localhost:6379` |
+| `STORE_CORS` | Storefront CORS origins | — (required) |
+| `ADMIN_CORS` | Admin panel CORS origins | — (required) |
+| `VENDOR_CORS` | Vendor panel CORS origins | — (required) |
+| `AUTH_CORS` | Auth endpoint CORS origins | — (required) |
+| `JWT_SECRET` | JWT signing secret | `supersecret` (change in production) |
+| `COOKIE_SECRET` | Cookie signing secret | `supersecret` (change in production) |
+| `FILE_BACKEND_URL` | Public origin baked into uploaded file URLs | `http://localhost:9000/static` |
+| `MERCUR_VENDOR_URL` | Vendor dashboard base URL used in member invite links | `""` — can also be set via the seller module's `vendor_url` option |
+| `NODE_ENV` | Environment selection | `development` |
+
+## Dashboard modules
+
+The admin and vendor dashboards are served by two UI modules:
+
+```ts
+modules: [
+  {
+    resolve: "@mercurjs/core/modules/admin-ui",
+    options: { appDir: "./admin", path: "/dashboard" },
+  },
+  {
+    resolve: "@mercurjs/core/modules/vendor-ui",
+    options: { appDir: "./vendor", path: "/seller" },
+  },
+]
+```
+
+| Option | Type | Purpose |
+| --- | --- | --- |
+| `disable` | `boolean` | Skip serving this dashboard from the API process |
+| `path` | `string` | Mount path (e.g. `/dashboard`, `/seller`) |
+| `appDir` | `string` | Directory of the dashboard Vite app |
+| `viteDevServerPort` / `viteDevServerHost` | `number` / `string` | Dev-mode proxy target (host defaults to `localhost`) |
+
+## Stripe Connect payout provider
+
+Register `@mercurjs/payout-stripe-connect` as a provider of the payout module:
+
+```ts
+{
+  resolve: "@mercurjs/core/modules/payout",
+  options: {
+    providers: [
+      {
+        resolve: "@mercurjs/payout-stripe-connect",
+        id: "stripe-connect",
+        options: {
+          apiKey: process.env.STRIPE_SECRET_KEY,
+          webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+        },
+      },
+    ],
+  },
+}
+```
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | — (required) | Stripe secret key |
+| `webhookSecret` | `string` | — (required) | Verifies incoming Stripe webhook signatures |
+| `accountValidation.detailsSubmitted` | `boolean` | `true` | Require onboarding details submitted before the account is active |
+| `accountValidation.chargesEnabled` | `boolean` | `true` | Require charges enabled |
+| `accountValidation.payoutsEnabled` | `boolean` | `true` | Require payouts enabled |
+| `accountValidation.noOutstandingRequirements` | `boolean` | `true` | Treat pending Stripe requirements as `restricted` |
+| `accountValidation.requiredCapabilities` | `string[]` | `[]` | Stripe capabilities that must be `active` |
+
+The payout module itself also accepts scheduling options (`authorizationWindowMs`, `sellerActionWindowMs`, `captureSafetyBufferMs`, `requiredFulfillmentStatus`) — see the [Payout module reference](/rc/references/modules/payout#module-options).
+
+## Search provider
+
+The search module needs no configuration — when no provider is given, the built-in in-memory Orama provider registers automatically. To use a custom provider:
+
+```ts
+{
+  resolve: "@mercurjs/core/modules/search",
+  options: {
+    provider: {
+      resolve: "./src/providers/my-search-provider",
+      id: "my-search",
+      options: { /* provider options */ },
+    },
+  },
+}
+```
+
+The provider must extend `AbstractSearchProvider` — see the [Search module reference](/rc/references/modules/search#provider-contract).
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Installation" href="/rc/learn/installation" />
+  <Card title="Stripe Connect integration" href="/rc/resources/integrations/stripe-connect" />
+</CardGroup>

package/content/references/modules/commission.mdx

@@ -0,0 +1,106 @@
+---
+title: "Commission module"
+description: "Data models and service methods for the Commission module."
+---
+
+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](/rc/learn/commissions).
+
+## Data models
+
+### `CommissionRate`
+
+Table `commission_rate`, ID prefix `comrate`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | text | Searchable |
+| `code` | text | Unique; auto-generated from `name` when omitted |
+| `type` | enum | `fixed` or `percentage` |
+| `value` | bigNumber | The percentage or the fixed amount |
+| `is_enabled` | boolean | Default `true` |
+| `is_default` | boolean | Default `false`; the platform fallback rate |
+| `currency_code` | text | Nullable; restricts the rate to one currency |
+| `include_tax` | boolean | Default `false`; commission is computed on the tax-inclusive amount |
+| `include_shipping` | boolean | Default `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:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `reference` | text | One of `product`, `product_type`, `product_collection`, `product_category`, `seller` |
+| `reference_id` | text | The referenced entity's ID |
+
+### `CommissionRateValue`
+
+Table `commission_rate_value`, ID prefix `comval`. Per-currency amounts for `fixed` rates:
+
+| Field | Type |
+| --- | --- |
+| `currency_code` | text |
+| `amount` | bigNumber |
+
+### `CommissionLine`
+
+Table `commission_line`, ID prefix `comline`. The persisted result of a calculation, anchored to an order item or shipping method:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `item_id` | text | Nullable; the order line item |
+| `shipping_method_id` | text | Nullable; set for shipping commission lines |
+| `commission_rate_id` | text | Nullable; the rate that produced this line |
+| `code` | text | Rate code snapshot |
+| `rate` | float | Rate value snapshot |
+| `amount` | bigNumber | Computed commission |
+| `description` | text | Nullable |
+
+## Enums
+
+```ts
+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:
+
+| Method | Behavior |
+| --- | --- |
+| `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` / `listAndCountCommissionRates` | Apply the virtual `scope_type` filter |
+
+A loader seeds a default commission rate on first boot.
+
+## Related endpoints
+
+- `GET/POST /admin/commission-rates`, `POST /admin/commission-rates/:id/rules` — see [Admin API](/rc/references/api/admin)
+- `GET /admin/orders/:id/commission-lines` and `GET /vendor/orders/:id/commission-lines` expose the computed lines per order.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Seller module" href="/rc/references/modules/seller" />
+  <Card title="Payout module" href="/rc/references/modules/payout" />
+</CardGroup>