Manage a store's team from server code

Manage a store’s team from your own server code when you migrate staff from another system, sync people from an identity provider, or build your own team screens. Every change runs through a workflow that validates the owner rules and emits an event.

Before you begin

You need the following in place:

A store id, such as sel_01JD8Q1234567
A notification provider for email, if you send invite links from a subscriber

Invite and onboard a member

Create the invite

createMemberInvitesWorkflow takes an array of invites, each with seller_id, email, and role_id. It signs a token for each one and fails if an email already belongs to the store.

import { SellerRole } from "@mercurjs/types"
import { createMemberInvitesWorkflow } from "@mercurjs/core/workflows"

const { result: invites } = await createMemberInvitesWorkflow(
  container
).run({
  input: [
    {
      seller_id: "sel_01JD8Q1234567",
      email: "ops@acme.com",
      role_id: SellerRole.ORDER_MANAGEMENT,
    },
  ],
})

Send the invite link

The workflow emits member_invite.created once per invite, with id, token, and expires_at. Mercur doesn’t email team invites itself, so send the link from a subscriber.

src/subscribers/member-invite-created.ts

import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
import { MercurModules } from "@mercurjs/types"

export default async function inviteCreated({
  event,
  container,
}: SubscriberArgs<{ id: string; token: string }>) {
  const sellers = container.resolve(MercurModules.SELLER)
  const invite = await sellers.retrieveMemberInvite(event.data.id)
  await container.resolve(Modules.NOTIFICATION).createNotifications({
    to: invite.email,
    channel: "email",
    template: "member-invite",
    data: { token: event.data.token },
  })
}

export const config: SubscriberConfig = { event: "member_invite.created" }

Accept the invite

When the invitee signs up or signs in, run acceptMemberInviteWorkflow with the token and their auth identity. It returns the member.

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

const { result: member } = await acceptMemberInviteWorkflow(
  req.scope
).run({
  input: {
    invite_token: "your_invite_token",
    auth_identity_id: req.auth_context.auth_identity_id,
    first_name: "Ola",
    last_name: "Nordmann",
  },
})

The workflow upserts the member by email, creates the membership with the invite’s role, and deletes the invite. Pass member_id when the person is already a member of another store, so the workflow leaves their auth identity as it is.

Resend or revoke an invite

resendMemberInviteWorkflow takes invite_id and seller_id. It deletes the invite and creates a fresh one with a new token and expiry, then emits member_invite.created again. deleteMemberInviteWorkflow takes invite_id and deletes the invite without a replacement.

Add an existing member directly

Skip the invite when the person already has a Member record, for example after a migration. addSellerMemberWorkflow creates the membership and returns it.

import { SellerRole } from "@mercurjs/types"
import { addSellerMemberWorkflow } from "@mercurjs/core/workflows"

await addSellerMemberWorkflow(container).run({
  input: {
    seller_id: "sel_01JD8Q1234567",
    member_id: "mem_01JD8Q1234567",
    role_id: SellerRole.SUPPORT,
  },
})

The membership is unique on (seller_id, member_id), so adding the same member twice fails.

Change a role or remove a member

Both workflows take the membership id, seller_member_id, not the member id. Both reject the owner membership with a NOT_ALLOWED error.

import { SellerRole } from "@mercurjs/types"
import {
  removeSellerMemberWorkflow,
  updateMemberRoleWorkflow,
} from "@mercurjs/core/workflows"

await updateMemberRoleWorkflow(container).run({
  input: {
    seller_member_id: "selmem_01JD8Q1234567",
    role_id: SellerRole.ACCOUNTING,
  },
})

await removeSellerMemberWorkflow(container).run({
  input: {
    seller_member_id: "selmem_01JD8Q1234567",
    seller_id: "sel_01JD8Q1234567",
  },
})

Removing a membership keeps the Member record, so the person keeps access to their other stores.

Update a member’s profile

updateMemberWorkflow changes first_name, last_name, and locale on members that match a selector. It exposes a membersUpdated hook and doesn’t emit an event.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Manage a store's team from server code

Before you begin

Invite and onboard a member

Resend or revoke an invite

Add an existing member directly

Change a role or remove a member

Update a member’s profile

Next steps

​Before you begin

​Invite and onboard a member

​Resend or revoke an invite

​Add an existing member directly

​Change a role or remove a member

​Update a member’s profile

​Next steps

Before you begin

Invite and onboard a member

Resend or revoke an invite

Add an existing member directly

Change a role or remove a member

Update a member’s profile

Next steps