Approve, suspend, and terminate stores

Drive a store through its lifecycle from your own server code, for example to auto-approve vetted sellers or to suspend a store when a risk check fails. Each transition is a workflow that validates the current status, writes the change, emits an event, and exposes a hook.

Moderate a store

Approve a pending store

approveSellerWorkflow moves a pending_approval store to open and stamps approved_at.

src/api/admin/stores/[id]/vet/route.ts

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

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  await approveSellerWorkflow(req.scope).run({
    input: { seller_id: req.params.id },
  })

  res.sendStatus(200)
}

Suspend and reinstate a store

suspendSellerWorkflow takes an optional reason, which it saves in status_reason. unsuspendSellerWorkflow reopens the store and clears the reason.

import {
  suspendSellerWorkflow,
  unsuspendSellerWorkflow,
} from "@mercurjs/core/workflows"

await suspendSellerWorkflow(container).run({
  input: { seller_id: "sel_01JD8Q1234567", reason: "Chargeback review" },
})

await unsuspendSellerWorkflow(container).run({
  input: { seller_id: "sel_01JD8Q1234567" },
})

Terminate a store

terminateSellerWorkflow accepts a pending_approval or suspended store. Suspend an open store first.

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

await terminateSellerWorkflow(container).run({
  input: { seller_id: "sel_01JD8Q1234567", reason: "Policy breach" },
})

To undo it, run unterminateSellerWorkflow. It returns the store to suspended, and you reopen it with unsuspendSellerWorkflow.

Reject a pending application

Mercur has no separate reject workflow. Run suspendSellerWorkflow on the pending_approval store with a reason: it stamps rejected_at and keeps the store out of the Store API. Terminate it afterwards if the decision is final.

Handle a failed transition

Each workflow checks the starting status and fails with a NOT_ALLOWED error when the transition isn’t allowed. Nothing is written in that case. Pass throwOnError: false to read the error instead of catching it.

import { MedusaError } from "@medusajs/framework/utils"
import { terminateSellerWorkflow } from "@mercurjs/core/workflows"

const { errors } = await terminateSellerWorkflow(container).run({
  input: { seller_id: "sel_01JD8Q1234567" },
  throwOnError: false,
})

const notAllowed = errors.some(
  ({ error }) => error.type === MedusaError.Types.NOT_ALLOWED
)

An open store makes notAllowed true here, with the message “Cannot terminate an open seller. Suspend or close first.” The workflow also fails when the seller id doesn’t exist, because its lookup step runs with throwIfKeyNotFound.

Extend a transition with a hook

Each lifecycle workflow exposes a hook that receives seller_id and additional_data. Register a handler to run your own step inside the transition.

src/workflows/hooks/seller-approved.ts

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

approveSellerWorkflow.hooks.sellerApproved(
  async ({ seller_id }, { container }) => {
    const logger = container.resolve("logger")
    logger.info(`Store ${seller_id} approved`)
  }
)

The other hooks follow the same shape: sellerSuspended, sellerUnsuspended, sellerTerminated, and sellerUnterminated.

Run side effects from a subscriber

Subscribe to the lifecycle events for work that shouldn’t block the transition, such as emails. Each event carries { id }, the seller id.

src/subscribers/store-suspended.ts

import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"

export default async function storeSuspended({
  event,
  container,
}: SubscriberArgs<{ id: string }>) {
  const logger = container.resolve("logger")
  logger.info(`Store ${event.data.id} suspended`)
}

export const config: SubscriberConfig = {
  event: "seller.suspended",
}

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Approve, suspend, and terminate stores

Moderate a store

Reject a pending application

Handle a failed transition

Extend a transition with a hook

Run side effects from a subscriber

Next steps

​Moderate a store

​Reject a pending application

​Handle a failed transition

​Extend a transition with a hook

​Run side effects from a subscriber

​Next steps

Moderate a store

Reject a pending application

Handle a failed transition

Extend a transition with a hook

Run side effects from a subscriber

Next steps