> ## 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.

# Refresh order commission lines

> Recompute commission lines for existing orders, and pass extra data to the commission provider with workflow hooks.

Recompute the commission lines of existing orders, for example after you change rates or when you change an order outside Mercur’s own workflows. Mercur already refreshes lines at checkout and on order edits, returns, claims, and exchanges.

**1. Run the workflow**

Pass the ids of the orders to `refreshOrderCommissionLinesWorkflow`. This route refreshes one order.

```ts title="src/api/admin/orders/[id]/recompute-commission/route.ts" theme={null}
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await refreshOrderCommissionLinesWorkflow(
    req.scope
  ).run({
    input: { order_ids: [req.params.id] },
  })

  res.json({ commission_lines: result })
}
```

The workflow returns the lines it wrote for all the orders. It throws if any id doesn’t belong to an order.

**2. Check the result**

Read the lines back through `query.graph`, filtering by the order’s item ids.

```ts theme={null}
const { data: lines } = await query.graph({
  entity: "commission_line",
  fields: ["item_id", "shipping_method_id", "code", "rate", "amount"],
  filters: { item_id: ["ordli_01JD8Q1234567"] },
})
```

Item lines carry `item_id`. Shipping lines carry `shipping_method_id` and the description `Shipping Commission`.

## Backfill existing orders

The workflow takes any number of order ids and resolves them in one batch, so the rates load once per run. For a backfill, page through orders and refresh each page.

```ts title="src/scripts/backfill-commission.ts" theme={null}
import type { ExecArgs } from "@medusajs/framework/types"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"

export default async function backfill({ container }: ExecArgs) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const take = 100

  for (let skip = 0; ; skip += take) {
    const { data } = await query.graph({
      entity: "order",
      fields: ["id"],
      pagination: { skip, take },
    })
    if (!data.length) break

    await refreshOrderCommissionLinesWorkflow(container).run({
      input: { order_ids: data.map((order) => order.id) },
    })
  }
}
```

Each page is one workflow run. A refresh replaces lines by item and shipping method, so you can re-run the script safely.

## Pass extra data with setCommissionContext

The `setCommissionContext` hook receives the calculation contexts before they reach the provider. Return a `StepResponse` with new contexts to fill `additional_context` for a custom provider, or return nothing to keep them.

```ts title="src/workflows/hooks/commission-context.ts" theme={null}
import { StepResponse } from "@medusajs/framework/workflows-sdk"
import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"

refreshOrderCommissionLinesWorkflow.hooks.setCommissionContext(
  ({ contexts }) =>
    new StepResponse(
      contexts.map((context) => ({
        ...context,
        additional_context: { tier: "gold" },
      }))
    )
)
```

Each context already has `order_id`, `seller_id`, `currency_code`, `items`, and `shipping_methods`. Items carry the product’s `tags` and `attribute_value_ids`, which the `system` provider ignores but your own provider can use.

## React with commissionLinesUpserted

The `commissionLinesUpserted` hook runs after the lines are written, as part of the same workflow run. If your handler throws, the run fails, and at checkout that fails the cart completion too.

```ts title="src/workflows/hooks/commission-written.ts" theme={null}
import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"

refreshOrderCommissionLinesWorkflow.hooks.commissionLinesUpserted(
  async ({ order_ids, commission_lines }, { container }) => {
    const logger = container.resolve("logger")
    logger.info(
      `${commission_lines.length} lines for ${order_ids.join(", ")}`
    )
  }
)
```

Use this hook to sync commission to an external ledger. Use the [order events](https://docs.mercurjs.com/platform/commission/reference/events.md) instead when your side effect shouldn’t be able to block the refresh.

## Next steps

* [What a commission line records](https://docs.mercurjs.com/platform/commission/concepts/order-commission-lines.md)
* [Write a custom commission provider](https://docs.mercurjs.com/platform/commission/reference/service.md)
* [Hooks of every commission workflow](https://docs.mercurjs.com/platform/commission/reference/workflows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.