@mercurjs/docs 2.3.8-canary.2 → 2.3.8-canary.4

package/content/platform/review/reference/workflows.mdx

@@ -1,31 +1,87 @@
 ---
-title: "Workflows"
+title: "Review workflows"
 sidebarTitle: "Workflows"
-description: "Review workflows for creating, moderating, responding, and deleting."
+description: "The four review workflows, their inputs, steps, compensation, and errors."
 ---
 
-This reference lists the workflows for the Review domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+Core ships four review workflows in `packages/core/src/workflows/review/`. Import them from `@mercurjs/core/workflows` and run them with the Medusa container. None of them exposes a workflow hook, and none emits an event of its own: the events come from the module service, as listed in the [Events reference](/platform/review/reference/events).
 
-## Review workflows
+```ts
+import { createReviewWorkflow } from "@mercurjs/core/workflows"
 
-| Workflow | Input | Purpose |
+const { result: review } = await createReviewWorkflow(container).run({
+  input: {
+    order_id: "order_01JD8Q1234567",
+    reference: "seller",
+    reference_id: "sel_01JD8Q1234567",
+    rating: 5,
+    customer_id: "cus_01JD8Q1234567",
+  },
+})
+```
+
+## createReviewWorkflow
+
+Validates a submission, creates a `pending` review, and writes its customer, order, and target links. Workflow id `create-review`. Input type `CreateReviewDTO`, returns the created review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `order_id` | `string` | The order that earned the review. Must belong to `customer_id` |
+| `reference` | `"product" \| "seller"` | The target type |
+| `reference_id` | `string` | The product id or seller id |
+| `rating` | `number` | The score. Not range checked |
+| `customer_note` | `string \| null` | Optional. Defaults to `null` |
+| `customer_id` | `string` | The customer writing the review |
+
+The workflow runs three steps:
+
+1. **`validate-review`**: fails with `INVALID_DATA` “Order not found!” when no order matches `order_id` and `customer_id`, and with “Review already exists” when the order has a review with the same `reference` and target id
+2. **`create-review`**: creates the review and links it to the customer and the order; on rollback, deletes the review
+3. **`create-remote-links`**: Medusa’s `createRemoteLinkStep`, which links the review to the product or the seller
+
+## updateReviewWorkflow
+
+Updates any of a review’s editable fields, including `status`. Workflow id `update-review`. Input type `UpdateReviewDTO`, returns the updated review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The review id |
+| `rating` | `number` | Optional |
+| `customer_note` | `string \| null` | Optional |
+| `seller_note` | `string \| null` | Optional. Pass `null` to clear an answer |
+| `status` | `"pending" \| "published" \| "rejected"` | Optional. Any value from any status |
+
+Its single step, `update-review`, reads the review before writing. On rollback it restores the previous `rating`, `customer_note`, `seller_note`, and `status`.
+
+## respondReviewWorkflow
+
+Writes a store’s answer to `seller_note`, once. Workflow id `respond-review`. Input type `RespondReviewDTO`, returns the updated review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The review id |
+| `seller_note` | `string` | The answer |
+
+Its single step, `respond-review`, fails with `NOT_FOUND` “Review not found” for an unknown id and with `NOT_ALLOWED` “This review already has a response” when `seller_note` is set. On rollback it sets `seller_note` back to `null`. The workflow doesn’t check which store owns the review: the Vendor API checks the seller link before running it.
+
+## deleteReviewWorkflow
+
+Soft deletes a review. Workflow id `delete-review`. The input is the review id as a plain string, and the workflow returns that id.
+
+```ts
+await deleteReviewWorkflow(container).run({ input: "rev_01JD8Q1234567" })
+```
+
+Its single step, `delete-review`, calls `softDeleteReviews` and leaves the review’s links in place. On rollback it calls `restoreReviews`.
+
+## Steps
+
+`@mercurjs/core/workflows` also exports each step, so you can compose them into your own workflows:
+
+| Step | Id | Input |
 | --- | --- | --- |
-| `createReviewWorkflow` | `{ order_id, reference, reference_id, rating, customer_note?, customer_id }` | Validate and create a review, linking it to its target, order, and customer |
-| `updateReviewWorkflow` | `{ id, rating?, customer_note?, seller_note?, status? }` | Update a review, including moderating its `status` |
-| `respondReviewWorkflow` | `{ id, seller_note }` | Attach a store's single response to a review |
-| `deleteReviewWorkflow` | `id` | Soft-delete a review (restorable on rollback) |
-
-Each workflow supports compensation: `createReviewWorkflow` deletes the review it
-created on failure, `updateReviewWorkflow` and `respondReviewWorkflow` restore the
-previous values, and `deleteReviewWorkflow` restores the soft-deleted row.
-
-<Note>
-  `createReviewWorkflow` validates that the order belongs to the customer and
-  that the target hasn't already been reviewed on that order. `respondReviewWorkflow`
-  refuses to overwrite an existing response.
-</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/review/reference/service). To run side effects when
-a review changes, see the [Event reference](/platform/review/reference/events).
+| `validateReviewStep` | `validate-review` | `CreateReviewDTO` |
+| `createReviewStep` | `create-review` | `CreateReviewDTO` |
+| `updateReviewStep` | `update-review` | `UpdateReviewDTO` |
+| `respondReviewStep` | `respond-review` | `RespondReviewDTO` |
+| `deleteReviewStep` | `delete-review` | `string` |

package/content/platform/store/concepts/lifecycle.mdx

@@ -1,62 +1,86 @@
 ---
-title: "Lifecycle"
+title: "Store statuses and transitions"
 sidebarTitle: "Lifecycle"
-description: "Store statuses, transitions, scheduled closures, and premium."
+description: "The four store statuses, the workflow behind each transition, scheduled closures, and the premium flag."
 ---
 
-This page covers the store account lifecycle and the states a store moves through.
+Every store has a status that decides whether it can trade. The status lives in the `status` field of `Seller`, typed by the `SellerStatus` enum, and only dedicated workflows move it. Each transition validates the current status, records a reason or a timestamp, emits an event, and exposes a hook you can extend.
 
-## Status
+## The four statuses
 
-A store's state lives in the `status` field of the `Seller` model, typed by the
-`SellerStatus` enum. A store moves through four statuses.
-
-```
-                ┌───────────────────┐
-                │  pending_approval  │
-                └─────────┬─────────┘
-                          │ approve
-                          ▼
-   ┌───────────┐     ┌────────┐
-   │ suspended  │◄───►│  open   │
-   └───────────┘     └───┬────┘
-                         │ terminate
-                         ▼
-                  ┌────────────┐
-                  │ terminated  │
-                  └────────────┘
-```
+A store is in exactly one status at a time. New stores start in `pending_approval` unless you pass another status to `createSellersWorkflow`.
 
 | Status | Meaning |
 | --- | --- |
-| `pending_approval` | Registered, waiting for operator review. |
-| `open` | Active. Can list offers, take orders, and collect payouts. |
-| `suspended` | Temporarily frozen. Offers stay listed but cannot be purchased. |
-| `terminated` | Permanently closed. This status is irreversible. |
+| `pending_approval` | Registered and waiting for operator review |
+| `open` | Trading: listed in the Store API with its offers |
+| `suspended` | Frozen by the operator, hidden from the Store API |
+| `terminated` | Closed by the operator, hidden from the Store API and from its members’ store list |
 
-Only the operator can change a store's status. Each transition runs through a
-dedicated workflow: `approveSellerWorkflow`, `suspendSellerWorkflow`,
-`unsuspendSellerWorkflow`, and `terminateSellerWorkflow`.
+The Store API seller and offer listings return only `open` stores that aren’t inside a closure window. A store in any other status disappears from those listings, but its records stay intact.
 
-<Note>
-  Termination is irreversible. All orders and payouts must be resolved before a
-  store can be terminated.
-</Note>
+## Transitions
+
+Each transition is its own workflow, and each one checks the starting status before it writes.
+
+<img className="block dark:hidden" src="/images/figures/store-lifecycle-light.svg" alt="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated." />
+<img className="hidden dark:block" src="/images/figures/store-lifecycle-dark.svg" alt="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated." />
+
+The workflows accept these starting statuses:
+
+| Workflow | Allowed from | Sets |
+| --- | --- | --- |
+| `approveSellerWorkflow` | `pending_approval` | `open`, and `approved_at` on first approval |
+| `suspendSellerWorkflow` | `pending_approval`, `open` | `suspended`, `status_reason`, and `rejected_at` on first suspension |
+| `unsuspendSellerWorkflow` | `suspended` | `open`, and clears `status_reason` |
+| `terminateSellerWorkflow` | `pending_approval`, `suspended` | `terminated` and `status_reason` |
+| `unterminateSellerWorkflow` | `terminated` | `suspended`, and clears `status_reason` |
+
+Any other starting status fails with a `NOT_ALLOWED` error and changes nothing.
+
+<Warning>
+  You can’t terminate an `open` store. Suspend it first, then terminate it.
+</Warning>
+
+Termination isn’t final: `unterminateSellerWorkflow` brings a store back as `suspended`, and you then unsuspend it to reopen. Use suspension to reject a pending application: it stamps `rejected_at` and keeps the reason in `status_reason`.
 
 ## Scheduled closures
 
-A store can schedule a temporary closure with the `closed_from` and `closed_to`
-fields without changing its status. During the window, the storefront shows as
-unavailable and no new orders are accepted. The account stays `open` and resumes
-on its own once `closed_to` passes.
+A scheduled closure takes a store offline for a window without changing its status. Set `closed_from` and `closed_to`, and optionally a `closure_note` for the reason. Both the operator and the store’s own members can set these fields.
 
-<Tip>
-  A closure overlays the current status. It is not a status of its own, and it
-  does not affect the transition rules.
-</Tip>
+The Store API filter shows a store only when both bounds allow it:
+
+- **`closed_from`**: `null`, or later than now
+- **`closed_to`**: `null`, or earlier than now
+
+The store comes back once `closed_to` passes, with no job or workflow involved. Set the fields as the closure starts, for example from a scheduled job, because a future `closed_to` hides the store right away even when `closed_from` is also in the future.
+
+```ts
+import { updateSellersWorkflow } from "@mercurjs/core/workflows"
+
+await updateSellersWorkflow(container).run({
+  input: {
+    selector: { id: "sel_01JD8Q1234567" },
+    update: {
+      closed_from: new Date(),
+      closed_to: new Date("2026-12-27"),
+    },
+  },
+})
+```
+
+This closes the store from now until December 27. A `closed_from` in the past with a `null` `closed_to` hides the store until you clear the fields.
+
+<Note>
+  Closures filter the Store API seller and offer listings. They don’t block cart or checkout workflows, so add your own check there if a closed store must refuse orders.
+</Note>
 
 ## Premium
 
-The `is_premium` boolean is set only by the operator. Stores cannot designate
-themselves as premium. The storefront uses the flag for featured placement,
-badges, and curation priority.
+`is_premium` is a boolean that defaults to `false`. The Admin API accepts it on create and update, and the Vendor API doesn’t, so only the operator can set it. Mercur stores the flag and returns it, and your storefront decides what premium means, such as featured placement or a badge.
+
+## Related
+
+- [Moderate stores](/platform/store/guides/moderate-a-store)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)

package/content/platform/store/concepts/store-entity.mdx

@@ -1,19 +1,27 @@
 ---
-title: "The store entity"
+title: "What a store is made of"
 sidebarTitle: "The store"
-description: "The seller record, its business identity, and its satellite data."
+description: "The seller record, its currency and regions, and the satellite records that hold its business details."
 ---
 
-This page covers the store record and the data models that make up its business
-identity.
+A store is the `Seller` record: the account a seller trades under on your marketplace. It holds the public profile customers see, the single currency the store settles in, and its status. Three satellite records carry its business details: an address, professional details, and bank payment details.
 
-## Store
+## The seller record
 
-A store is the marketplace vendor. It owns offers, orders, and payouts, and it
-holds the profile shown to customers on the storefront. A store is represented by
-the `Seller` data model (table `seller`, id prefix `sel`).
+The `Seller` data model (table `seller`, id prefix `sel`) is the root of everything a store owns. Offers, orders, payouts, and price lists link to it from their own modules.
+
+A seller has four unique fields besides its id:
+
+- **`name`**: unique among stores that aren’t deleted
+- **`handle`**: unique, URL safe, and generated from `name` when you omit it
+- **`email`**: unique, the store’s contact address
+- **`external_id`**: optional, unique when set, for mapping to an outside system
+
+The service validates `handle` on create and update. A handle with characters that aren’t URL safe fails with an `INVALID_DATA` error.
 
 ```ts
+import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
 const { result } = await createSellersWorkflow(container).run({
   input: {
     sellers: [
@@ -21,33 +29,43 @@ const { result } = await createSellersWorkflow(container).run({
         name: "Acme Supplies",
         email: "team@acme.com",
         currency_code: "usd",
+        member: { email: "owner@acme.com" },
       },
     ],
   },
 })
 ```
 
-<Tip>
-  A store settles in exactly one currency, set by `currency_code`. A seller who
-  needs to trade in several currencies creates a separate store for each one, and
-  each store operates independently.
-</Tip>
+This creates a store with the handle `acme-supplies` and the status `pending_approval`. It also invites `owner@acme.com` to join the team as an administrator.
+
+## Currency and regions
+
+A store settles in one currency, set by `currency_code` when you create it. `UpdateSellerDTO` has no `currency_code` field, so the currency stays fixed for the life of the store. The vendor request context carries it as `seller_context.currency_code`.
+
+A store also links to one or more regions through the `region_seller` link:
+
+- **On create**: the store links to the default region of your Medusa store, plus any `region_ids` you pass
+- **On change**: `linkSellerRegionsWorkflow` adds and removes region links in one call
+- **Rule**: a store must keep at least one region, so removing the last one fails
+
+## Business details
+
+Three one-to-one records hang off the seller. Each workflow that writes them creates the record when it’s missing and updates it otherwise.
+
+| Model | Holds | Written by |
+| --- | --- | --- |
+| `SellerAddress` | The store’s postal address and contact name | `updateSellerAddressWorkflow` |
+| `ProfessionalDetails` | Corporate name, registration number, tax id | `updateSellerProfessionalDetailsWorkflow` |
+| `PaymentDetails` | Bank account holder, IBAN, BIC, routing and account numbers | `updateSellerPaymentDetailsWorkflow` |
 
-## Professional details
+You remove professional details with `deleteSellerProfessionalDetailsWorkflow`. Deleting a seller cascades to all three records and to its pending invites, and detaches its members without deleting them.
 
-A store can carry professional details: a corporate name, a registration number,
-and a tax id. These are represented by the `ProfessionalDetails` data model. When
-this record is present, the store is a registered business. When it is absent,
-the store is an individual seller.
+## Fulfillment defaults
 
-## Addresses and payment details
+`default_leadtime_to_ship` holds the number of days a store needs before it ships, and defaults to `2`. Vendors can change it on their own store.
 
-A store keeps its addresses as `SellerAddress` records, one each for a warehouse,
-return, or business address. The bank details used to settle payouts live on a
-`PaymentDetails` record. Both are satellite records of the store, and fulfillment
-and payout settlement read from them.
+## Related
 
-<Note>
-  `ProfessionalDetails`, `SellerAddress`, and `PaymentDetails` are one-to-one with
-  the store and are deleted along with it.
-</Note>
+- [Team & members](/platform/store/concepts/team)
+- [Lifecycle](/platform/store/concepts/lifecycle)
+- [Data models reference](/platform/store/reference/data-models)

package/content/platform/store/concepts/team.mdx

@@ -1,50 +1,71 @@
 ---
-title: "Team & members"
+title: "How store teams work"
 sidebarTitle: "Team & members"
-description: "Members, roles, invites, and the many-to-many store relationship."
+description: "Members, memberships, owners, roles, invites, and how a member picks the store they act for."
 ---
 
-This page covers how a store's team is modeled and how access is structured.
+A store’s team is the set of people who can sign in to the Vendor panel and act for that store. Mercur models the person and the membership separately, so one person can work for several stores with a different role in each. This matters as soon as an agency, a franchise, or a holding company runs more than one store on your marketplace.
 
-## Member
+## Members and memberships
 
-A member is a dashboard user who can manage one or more stores. A member is
-represented by the `Member` data model (table `member`, id prefix `mem`). Their
-identity is tied to their `email`, which is unique across the system.
+A `Member` (id prefix `mem`) is a person. Their `email` is unique across the whole marketplace, so the same person never has two member records. A member can be deactivated with `is_active` without touching their memberships.
 
-## Seller member
+A `SellerMember` (id prefix `selmem`) is one person’s membership in one store. It’s the pivot between `Seller` and `Member`, and it’s unique on `(seller_id, member_id)`. Each membership carries:
 
-The relationship between stores and members is many-to-many. A store can have
-several members, and a member can belong to several stores. Each membership is a
-`SellerMember` record, the pivot between `Seller` and `Member`, unique on
-`(seller_id, member_id)`.
+- **`role_id`**: the member’s role in this store, one of the `SellerRole` values
+- **`is_owner`**: `true` for the store’s owner membership, `false` for everyone else
+- **`metadata`**: free-form data for your own extensions
 
-```ts
-await addSellerMemberWorkflow(container).run({
-  input: {
-    seller_id: "sel_123",
-    member: { email: "ops@acme.com" },
-  },
-})
-```
+## Roles
+
+`SellerRole` from `@mercurjs/types` lists the five roles a membership can hold. The membership stores the role as a plain string.
+
+| `SellerRole` key | Stored value |
+| --- | --- |
+| `SELLER_ADMINISTRATION` | `role_seller_administration` |
+| `INVENTORY_MANAGEMENT` | `role_seller_inventory_management` |
+| `ORDER_MANAGEMENT` | `role_seller_order_management` |
+| `ACCOUNTING` | `role_seller_accounting` |
+| `SUPPORT` | `role_seller_support` |
+
+The vendor membership check confirms that a member belongs to the store they’re acting for. It doesn’t restrict routes by role, so enforce role rules in your own middleware when you need them.
+
+## The owner
+
+Every store has at most one owner membership, flagged with `is_owner`. Mercur sets it in two places:
+
+- **Self-registration**: `createSellerAccountWorkflow` adds the registering member as owner with `role_seller_administration`
+- **First accepted invite**: `acceptMemberInviteWorkflow` makes the new member owner when the store has none yet
 
-Every membership carries a `role_id`, resolved against the RBAC roles module, and
-an `is_owner` flag.
+`updateMemberRoleWorkflow` and `removeSellerMemberWorkflow` both reject the owner membership with a `NOT_ALLOWED` error. That keeps every store with someone who can administer it.
 
-<Tip>
-  A store must always keep at least one member with admin access. The last admin
-  cannot be removed or demoted.
-</Tip>
+## Invites
 
-## Member invite
+A `MemberInvite` (id prefix `meminv`) is a pending offer to join one store with one role. The service signs a JWT for each invite, stores it in `token`, and sets `expires_at` 7 days out unless you change the module’s `invite_valid_duration` option.
+
+Invites follow these rules:
+
+- **One open invite per email and store**: a unique index covers `(email, seller_id)` while `accepted` is `false`
+- **No invites for existing members**: inviting an email that already belongs to the store fails
+- **Existing accounts are reused**: accepting an invite for a known email links the existing member instead of creating one
+- **Single use**: accepting deletes the invite, and an expired or accepted token fails validation
+
+## The active store
+
+A member who belongs to several stores picks the active one per request. The vendor middleware reads the store id from the `x-seller-id` header, or from the session, and checks for a matching `SellerMember`. It then exposes the store on `req.seller_context`, typed by the `SellerContext` interface:
+
+```ts
+interface SellerContext {
+  seller_id: string
+  currency_code: string
+  seller_member: SellerMemberDTO
+}
+```
 
-Pending invitations are represented by the `MemberInvite` data model. If an
-invited email already belongs to a user, accepting the invite links the new store
-association to their existing account instead of creating a new one.
+Every vendor route scopes its reads and writes to `seller_context.seller_id`, so switching stores in the Vendor panel never shows another store’s data. The store list a member sees leaves out terminated stores.
 
-## Store switcher
+## Related
 
-A user who belongs to several stores uses the store switcher in the Vendor panel
-to change the active store. Each store context is fully isolated. Switching stores
-shows only that store's offers, orders, and payouts, and it never leaks data
-across stores.
+- [Manage the team](/platform/store/guides/manage-the-team)
+- [Workflows reference](/platform/store/reference/workflows)
+- [What a store is made of](/platform/store/concepts/store-entity)

package/content/platform/store/guides/create-a-store.mdx

@@ -1,55 +1,122 @@
 ---
-title: "Create a store"
+title: "Create a store from server code"
 sidebarTitle: "Create a store"
-description: "Create a seller programmatically with createSellersWorkflow."
+description: "Create stores with createSellersWorkflow from a route, a seed script, or an import job, and extend creation with hooks."
 ---
 
-In this guide, you'll learn how to create a store from your own server code. This
-is useful in a seed script, a custom API route, or an onboarding flow.
+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.
 
-Mercur exposes a `createSellersWorkflow` that creates the `Seller` record along
-with its defaults. Run it from any place that has access to the Medusa container.
+## Before you begin
 
-## Run the workflow
+You need the following in place:
 
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createSellersWorkflow } from "@mercurjs/core/workflows"
+- 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
+
+<Steps>
+  <Step title="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.
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createSellersWorkflow(req.scope).run({
-    input: {
-      sellers: [
-        {
-          name: "Acme Supplies",
-          email: "team@acme.com",
-          currency_code: "usd",
+    ```ts title="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`.
+  </Step>
+  <Step title="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.
+
+    ```ts
+    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`.
+  </Step>
+  <Step title="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](/platform/store/guides/manage-the-team) shows both the subscriber and the accept call.
+  </Step>
+</Steps>
+
+## Attach custom data with additional_data
 
-  res.status(201).json({ seller: result[0] })
-}
+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.
+
+```ts title="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}`)
+  }
+)
 ```
 
-<Note>
-  An operator can set a new store to `open` right away. A store created through
-  the public self-registration flow starts in `pending_approval` and waits for
-  operator review. See [Moderate stores](/platform/store/guides/moderate-a-store).
-</Note>
+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.
 
-## Attach custom data
+## Create the owner membership directly
 
-The workflow accepts an `additional_data` payload. It is passed to the workflow's
-hooks, so you can persist marketplace-specific data alongside the store without
-forking the workflow.
+`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.
 
 ```ts
-await createSellersWorkflow(req.scope).run({
+import { createSellerAccountWorkflow } from "@mercurjs/core/workflows"
+
+const { result: seller } = await createSellerAccountWorkflow(
+  req.scope
+).run({
   input: {
-    sellers: [{ name: "Acme Supplies", email: "team@acme.com", currency_code: "usd" }],
-    additional_data: { referral_code: "SPRING25" },
+    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`
+
+## Next steps
+
+- [Moderate stores](/platform/store/guides/moderate-a-store)
+- [Manage the team](/platform/store/guides/manage-the-team)
+- [Workflows reference](/platform/store/reference/workflows)