> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure commissions

> Set the global commission, add scoped rules for categories and sellers, and confirm the right rate lands on an order.

Commissions are how your marketplace earns. Mercur matches a **commission rate** to every order line item through rules, with one **global commission** as the catch-all. In this tutorial you'll set up a realistic three-tier configuration and verify which rate wins on a real order.

<Info>
  **The most specific rate wins.** Rules combine with AND across dimensions and OR within a dimension, and among matching rates the one scoping the most dimensions applies. You never order rates by priority — specificity is the priority. The full algorithm is in [Commission](/rc/learn/commissions).
</Info>

## What you'll build

* A global commission of 15% that also commissions shipping.
* A 12% rate for the Electronics category.
* An 8% rate for Electronics sold by one specific premium seller.

An electronics order from the premium seller should produce commission lines at 8% — not 12%, not 15%.

## Set up the rates

<Steps>
  <Step title="Set the global commission">
    Every marketplace needs exactly one default rate — the fallback when nothing more specific matches. Create it with `is_default`:

    ```bash theme={null}
    curl -X POST http://localhost:9000/admin/commission-rates \
      -H "Authorization: Bearer <admin-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Global Commission",
        "code": "global",
        "type": "percentage",
        "value": 15,
        "is_default": true,
        "include_shipping": true
      }'
    ```

    <Note>
      `include_shipping` only has an effect on the global commission — shipping methods are always commissioned from the global rate, never from scoped rates. In the Admin Panel this lives on the Global Commission card under **Settings → Commissions**.
    </Note>
  </Step>

  <Step title="Add a category-scoped rate">
    A rate becomes scoped by attaching **rules**. Each rule names a dimension (`reference`) and a value (`reference_id`):

    ```bash theme={null}
    curl -X POST http://localhost:9000/admin/commission-rates \
      -H "Authorization: Bearer <admin-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Electronics Commission",
        "code": "electronics",
        "type": "percentage",
        "value": 12,
        "rules": [
          { "reference": "product_category", "reference_id": "pcat_electronics" }
        ]
      }'
    ```

    Available dimensions: `product`, `product_type`, `product_collection`, `product_category`, and `seller`.
  </Step>

  <Step title="Add a two-dimension rate for the premium seller">
    Combining a `seller` rule with a `product_category` rule means *both* must match — this rate applies only to that seller's electronics:

    ```bash theme={null}
    curl -X POST http://localhost:9000/admin/commission-rates \
      -H "Authorization: Bearer <admin-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Premium seller electronics",
        "code": "premium-electronics",
        "type": "percentage",
        "value": 8,
        "rules": [
          { "reference": "seller", "reference_id": "slr_premium" },
          { "reference": "product_category", "reference_id": "pcat_electronics" }
        ]
      }'
    ```

    Because it scopes two dimensions, it beats the one-dimension Electronics rate whenever both match — regardless of which rate was created first.
  </Step>

  <Step title="Place a test order">
    Commission lines are calculated when an order is placed — rates are never applied retroactively. Place an order containing an electronics item from the premium seller (via your storefront or the Store API), then inspect the order's commission lines.
  </Step>
</Steps>

## Verify

1. List the rates and confirm all three exist and are enabled:
   ```bash theme={null}
   curl http://localhost:9000/admin/commission-rates \
     -H "Authorization: Bearer <admin-token>"
   ```
2. On the placed order, each electronics line item from the premium seller has a commission line with `code: "premium-electronics"` and `rate: 8`.
3. The order's shipping method has a commission line from the **global** rate (because `include_shipping` is on).
4. Change a rate now and confirm the existing order's commission lines are untouched — `CommissionLine` records are a permanent audit trail.

## FAQ

<AccordionGroup>
  <Accordion title="How do I charge a flat fee instead of a percentage?">
    Use `"type": "fixed"` with per-currency `values`: `[{ "currency_code": "usd", "amount": 2 }, { "currency_code": "eur", "amount": 1.8 }]`. The scalar `value` is the fallback for currencies without an entry.
  </Accordion>

  <Accordion title="What happens when two rates tie on specificity?">
    Ties break deterministically to the **oldest rate**. But if you find yourself relying on tie-breaking, prefer making one rate more specific — it reads better in the Admin Panel and survives audits.
  </Accordion>

  <Accordion title="Do rate changes affect existing orders?">
    No. Commission is snapshotted into `CommissionLine` records at order placement. Changing or disabling a rate only affects future orders — the lines on past orders are a permanent audit trail that payouts read from.
  </Accordion>

  <Accordion title="Can a rate match multiple values in one dimension?">
    Yes — rules within the same dimension are OR'd. A rate with two `product_category` rules matches items in either category, and still counts as one dimension for specificity.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Commission" href="/rc/learn/commissions">
    The full matching algorithm, calculation pipeline, and data model.
  </Card>

  <Card title="Set up seller payouts" href="/rc/resources/tutorials/seller-payouts-stripe">
    Where commission is deducted — the settlement side of the marketplace.
  </Card>
</CardGroup>