Stage a product edit from server code

Stage a product edit as a ProductChange instead of writing to the product, so it goes through the same review as an edit from the Vendor panel. Use this when you build your own edit surface, such as a bulk editor or an import.

Before you begin

You need the following in place:

A Mercur server with @mercurjs/core installed through withMercur()
A product id, and the id of the actor making the edit, such as a seller id (sel_…)

Stage a field edit

productEditUpdateProductWorkflow compares your update with the product and stages one action per field that differs.

Create the route

Add a route under /admin so Medusa authenticates the caller, and pass the update to the workflow. The workflow returns the staged change.

src/api/admin/custom/products/[id]/edit/route.ts

import type {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"

type Body = { title?: string; material?: string }

export async function POST(
  req: AuthenticatedMedusaRequest<Body>,
  res: MedusaResponse
) {
  const { result } = await productEditUpdateProductWorkflow(req.scope).run({
    input: {
      product_id: req.params.id,
      created_by: req.auth_context.actor_id,
      update: req.body,
    },
  })

  res.status(202).json({ product_change: result })
}

The route answers 202 because the edit isn’t on the product yet. With the default product_request flag on, result.status is pending.

Handle an open change

If the same created_by already has a pending change on the product, the workflow throws a NOT_ALLOWED error before it stages anything. Medusa’s error handler turns it into a 400 response. Cancel the open change with cancelProductChangeWorkflow, or wait for an operator to resolve it.

Read the staged actions

Load the change with its actions to show the seller what’s waiting for review.

const query = req.scope.resolve("query")

const { data: [change] } = await query.graph({
  entity: "product_change",
  fields: ["id", "status", "actions.action", "actions.details"],
  filters: { id: result.id },
})

Each UPDATE action carries field, value, and previous_value in details.

If no field differs, the workflow still stages a change, with no actions. Compare the input yourself first when an empty change would confuse your reviewers.

Stage variant and attribute edits

Variants and attributes have their own edit workflows, with the same pending check. productEditUpdateVariantsWorkflow takes a list of typed operations:

import { productEditUpdateVariantsWorkflow } from "@mercurjs/core/workflows"

await productEditUpdateVariantsWorkflow(container).run({
  input: {
    product_id: "prod_01JD8Q1234567",
    created_by: "sel_01JD8Q1234567",
    operations: [
      {
        type: "update",
        variant_id: "variant_01JD8Q1234567",
        fields: { sku: "LINEN-M" },
      },
      { type: "remove", variant_id: "variant_01JD8Q1234568" },
    ],
  },
})

Each operation becomes a VARIANT_ADD, VARIANT_UPDATE, or VARIANT_REMOVE action. An update whose fields all match the current variant stages nothing. For attributes, pass add, remove, and update arrays to productEditUpdateAttributesWorkflow, in the same shapes as the attribute batch.

Stage actions directly

For a mixed change, build the actions yourself and pass them to stageProductChangeWorkflow. It skips the diff and the pending check, so check for an open change first.

import { ProductChangeActionType } from "@mercurjs/types"
import { stageProductChangeWorkflow } from "@mercurjs/core/workflows"

await stageProductChangeWorkflow(container).run({
  input: {
    product_id: "prod_01JD8Q1234567",
    created_by: "sel_01JD8Q1234567",
    external_note: "Spring catalog refresh",
    actions: [
      {
        product_id: "prod_01JD8Q1234567",
        action: ProductChangeActionType.UPDATE,
        details: { field: "subtitle", value: "Washed linen" },
      },
    ],
  },
})

Every action needs its own product_id. The workflow fills in product_change_id for you.

Apply an edit without review

Pass auto_confirm: true to stageProductChangeWorkflow or productEditDeleteProductWorkflow to confirm and apply the change in the same run. Use it for trusted sources, such as an operator tool. The change still lands in the trail as confirmed, and product-change.confirmed still fires.

Attach custom data with additional_data

productEditUpdateProductWorkflow and productEditUpdateAttributesWorkflow accept additional_data and pass it to their productChangeCreated hook. Use the hook to store your own data on the change:

src/workflows/hooks/product-change-created.ts

import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
import { MercurModules } from "@mercurjs/types"

productEditUpdateProductWorkflow.hooks.productChangeCreated(
  async ({ product_change, additional_data }, { container }) => {
    const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)

    await productEdit.updateProductChanges({
      id: product_change.id,
      metadata: { ticket_id: additional_data?.ticket_id },
    })
  }
)

The hook runs after staging and auto-confirm, so product_change is the record the workflow returns.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Stage a field edit

Stage variant and attribute edits

Stage actions directly

Apply an edit without review

Attach custom data with additional_data

Next steps

​Before you begin

​Stage a field edit

​Stage variant and attribute edits

​Stage actions directly

​Apply an edit without review

​Attach custom data with additional_data

​Next steps

Before you begin

Stage a field edit

Stage variant and attribute edits

Stage actions directly

Apply an edit without review

Attach custom data with additional_data

Next steps