Create a store from server code

Create a store from your own server code when you seed a marketplace, import sellers from another system, or build a custom onboarding flow. createSellersWorkflow creates the Seller, links its regions, and invites its first team member.

Before you begin

You need the following in place:

A Mercur server with @mercurjs/core installed through withMercur()
A default region set on your Medusa store, since every new store links to it

Create the store

Add a route that runs the workflow

Create an API route and run the workflow against the request’s container. Each entry in sellers needs a member.email: the workflow sends that address an invite with the role_seller_administration role.

src/api/admin/import-sellers/route.ts

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

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result: sellers } = await createSellersWorkflow(req.scope).run({
    input: {
      sellers: [
        {
          name: "Acme Supplies",
          email: "team@acme.com",
          currency_code: "usd",
          member: { email: "owner@acme.com" },
          region_ids: ["reg_01JD8Q1234567"],
        },
      ],
    },
  })

  res.status(201).json({ sellers })
}

The store gets the handle acme-supplies and links to the default region plus reg_01JD8Q1234567.

Open the store

New stores start in pending_approval. Run approveSellerWorkflow to open one, or pass status: "open" in the seller input when you import stores you’ve already vetted.

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

await approveSellerWorkflow(req.scope).run({
  input: { seller_id: sellers[0].id },
})

Approval stamps approved_at and emits seller.approved.

Let the owner accept the invite

The workflow emits member_invite.created with the invite’s id, token, and expires_at. Send the token to the invitee from a subscriber. When they accept it through acceptMemberInviteWorkflow, they join as the store’s owner. Manage the team shows both the subscriber and the accept call.

Attach custom data with additional_data

The workflow passes additional_data to its sellersCreated hook. Use the hook to save data that belongs to your extension, such as a referral code, without changing the workflow.

src/workflows/hooks/sellers-created.ts

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

createSellersWorkflow.hooks.sellersCreated(
  async ({ sellers, additional_data }, { container }) => {
    const referralCode = additional_data?.referral_code
    if (!referralCode) {
      return
    }
    const logger = container.resolve("logger")
    logger.info(`${sellers.length} sellers joined via ${referralCode}`)
  }
)

Pass additional_data: { referral_code: "SPRING25" } next to sellers in the workflow input to reach this hook. The workflow also has a validate hook that runs before anything is written, so you can throw there to reject the input.

Create the owner membership directly

createSellersWorkflow invites the owner. When the person already signed in, for example in a custom registration route, run createSellerAccountWorkflow instead. It creates the store in pending_approval and adds the member as owner in one call.

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

const { result: seller } = await createSellerAccountWorkflow(
  req.scope
).run({
  input: {
    auth_identity_id: req.auth_context.auth_identity_id,
    member_email: "owner@acme.com",
    seller: {
      name: "Acme Supplies",
      email: "team@acme.com",
      currency_code: "usd",
    },
  },
})

The workflow upserts the member by email and stores its id on the auth identity under the member actor type. It also accepts address, professional_details, and payment_details, and writes each one when present.

Handle a failed creation

The workflow rolls back every step when one fails. These inputs fail:

Duplicate name, email, handle, or external_id: the unique indexes reject the insert
Invalid handle: a handle with characters that aren’t URL safe fails with INVALID_DATA
Unknown region: a region_ids entry that doesn’t exist fails with NOT_FOUND

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Create the store

Attach custom data with additional_data

Create the owner membership directly

Handle a failed creation

Next steps

​Before you begin

​Create the store

​Attach custom data with additional_data

​Create the owner membership directly

​Handle a failed creation

​Next steps

Before you begin

Create the store

Attach custom data with additional_data

Create the owner membership directly

Handle a failed creation

Next steps