Refresh order commission lines

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.

Run the workflow

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

src/api/admin/orders/[id]/recompute-commission/route.ts

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.

Check the result

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

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.

src/scripts/backfill-commission.ts

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.

src/workflows/hooks/commission-context.ts

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.

src/workflows/hooks/commission-written.ts

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 instead when your side effect shouldn’t be able to block the refresh.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Backfill existing orders

Pass extra data with setCommissionContext

React with commissionLinesUpserted

Next steps

​Backfill existing orders

​Pass extra data with setCommissionContext

​React with commissionLinesUpserted

​Next steps

Backfill existing orders

Pass extra data with setCommissionContext

React with commissionLinesUpserted

Next steps