@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/store/reference/data-models.mdx

@@ -1,89 +1,164 @@
 ---
-title: "Data models"
+title: "Seller module data models"
 sidebarTitle: "Data models"
-description: "The data models owned by the Store (Seller) domain."
+description: "Every data model in the Seller module, with fields, types, defaults, indexes, and relations."
 ---
 
-The Store domain is owned by the **Seller module**. This reference lists its data
-models and their fields. For the full module overview, see the
-[Store overview](/platform/store/overview).
+The Seller module (`MercurModules.SELLER`) owns the store, its business details, and its team. Every model also has the standard `created_at`, `updated_at`, and `deleted_at` columns, which the tables below leave out.
 
 ## Seller
 
-Table `seller`, id prefix `sel`. The store account and profile.
+The store account and its public profile. Table `seller`, id prefix `sel`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | Unique, searchable |
-| `handle` | text | Unique; auto-generated from `name` when omitted |
-| `email` | text | Unique, searchable |
-| `phone` | text | Nullable |
-| `description` | text | Nullable |
-| `logo` / `banner` | text | Nullable |
-| `website_url` | text | Nullable |
-| `external_id` | text | Nullable; unique when set |
-| `currency_code` | text | The store's single operating currency |
-| `status` | enum | `SellerStatus`, default `pending_approval` |
-| `status_reason` | text | Nullable |
-| `approved_at` / `rejected_at` | dateTime | Nullable |
-| `is_premium` | boolean | Default `false`; operator-set only |
-| `closed_from` / `closed_to` | dateTime | Nullable; scheduled closure window |
-| `closure_note` | text | Nullable |
-| `metadata` | json | Nullable |
-
-Relations: `professional_details`, `address`, `payment_details` (one-to-one,
-deleted with the seller), `members` (many-to-many through `SellerMember`),
-`member_invites` (one-to-many, deleted with the seller).
+| `id` | `text` | Primary key |
+| `name` | `text` | Searchable, unique |
+| `handle` | `text` | Searchable, unique, generated from `name` when omitted |
+| `email` | `text` | Searchable, unique |
+| `phone` | `text` | Nullable |
+| `description` | `text` | Nullable |
+| `logo` | `text` | Nullable, image URL |
+| `banner` | `text` | Nullable, image URL |
+| `website_url` | `text` | Searchable, nullable |
+| `external_id` | `text` | Searchable, nullable, unique when set |
+| `currency_code` | `text` | The store’s settlement currency |
+| `status` | `enum` | `SellerStatus`, default `pending_approval` |
+| `status_reason` | `text` | Nullable, set by suspend and terminate |
+| `approved_at` | `dateTime` | Nullable, set on first approval |
+| `rejected_at` | `dateTime` | Nullable, set on first suspension |
+| `is_premium` | `boolean` | Default `false` |
+| `default_leadtime_to_ship` | `number` | Default `2`, in days |
+| `closed_from` | `dateTime` | Nullable, start of a scheduled closure |
+| `closed_to` | `dateTime` | Nullable, end of a scheduled closure |
+| `closure_note` | `text` | Nullable |
+| `metadata` | `json` | Nullable |
+
+Unique indexes on `name`, `handle`, `email`, and `external_id` apply only to rows that aren’t deleted. An extra index on `(status, closed_from, closed_to)` serves the Store API visibility filter.
+
+Relations:
+
+- **`professional_details`**: has one `ProfessionalDetails`, deleted with the seller
+- **`address`**: has one `SellerAddress`, deleted with the seller
+- **`payment_details`**: has one `PaymentDetails`, deleted with the seller
+- **`members`**: many-to-many with `Member` through `SellerMember`, detached when the seller is deleted
+- **`member_invites`**: has many `MemberInvite`, deleted with the seller
+
+## SellerStatus
+
+The enum in `@mercurjs/types` that types `Seller.status`.
+
+| Key | Value |
+| --- | --- |
+| `OPEN` | `open` |
+| `PENDING_APPROVAL` | `pending_approval` |
+| `SUSPENDED` | `suspended` |
+| `TERMINATED` | `terminated` |
 
 ## ProfessionalDetails
 
-Table `professional_details`, id prefix `selprodet`. Presence marks the store as
-a registered business.
+A store’s registered business identity. Table `professional_details`, id prefix `selprodet`.
 
-| Field | Type |
-| --- | --- |
-| `corporate_name` | text, nullable |
-| `registration_number` | text, nullable |
-| `tax_id` | text, nullable |
+| Field | Type | Description |
+| --- | --- | --- |
+| `corporate_name` | `text` | Nullable |
+| `registration_number` | `text` | Nullable |
+| `tax_id` | `text` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
 
 ## SellerAddress
 
-Table `seller_address`, id prefix `seladdr`. Fields: `name`, `company`,
-`first_name`, `last_name`, `address_1`, `address_2`, `city`, `country_code`,
-`province`, `postal_code`, `phone`, and `metadata`. All are nullable.
+A store’s postal address. Table `seller_address`, id prefix `seladdr`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `text` | Searchable, nullable |
+| `company` | `text` | Searchable, nullable |
+| `first_name` | `text` | Searchable, nullable |
+| `last_name` | `text` | Searchable, nullable |
+| `address_1` | `text` | Searchable, nullable |
+| `address_2` | `text` | Searchable, nullable |
+| `city` | `text` | Searchable, nullable |
+| `country_code` | `text` | Nullable |
+| `province` | `text` | Searchable, nullable |
+| `postal_code` | `text` | Searchable, nullable |
+| `phone` | `text` | Nullable |
+| `metadata` | `json` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
 
 ## PaymentDetails
 
-Table `payment_details`, id prefix `selpaydet`. Fields: `country_code`,
-`holder_name`, `bank_name`, `iban`, `bic`, `routing_number`, and
-`account_number`. All are nullable.
+A store’s bank account details. Table `payment_details`, id prefix `selpaydet`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `country_code` | `text` | Nullable |
+| `holder_name` | `text` | Nullable |
+| `bank_name` | `text` | Nullable |
+| `iban` | `text` | Nullable |
+| `bic` | `text` | Nullable |
+| `routing_number` | `text` | Nullable |
+| `account_number` | `text` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
 
 ## Member
 
-Table `member`, id prefix `mem`. A dashboard user that can belong to one or more
-stores.
+A person who can work for one or more stores. Table `member`, id prefix `mem`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `email` | text | Unique, searchable |
-| `first_name` / `last_name` | text | Nullable |
-| `locale` | text | Nullable |
-| `is_active` | boolean | Default `true` |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `email` | `text` | Searchable, unique across the marketplace |
+| `first_name` | `text` | Searchable, nullable |
+| `last_name` | `text` | Searchable, nullable |
+| `locale` | `text` | Nullable |
+| `is_active` | `boolean` | Default `true` |
+| `metadata` | `json` | Nullable |
+
+Relations: `sellers`, many-to-many with `Seller` through `SellerMember`.
 
 ## SellerMember
 
-Table `seller_member`, id prefix `selmem`. Pivot between `Seller` and `Member`,
-unique on `(seller_id, member_id)`.
+One member’s membership in one store. Table `seller_member`, id prefix `selmem`, unique on `(seller_id, member_id)`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `role_id` | text | Nullable; resolved against the RBAC roles module |
-| `is_owner` | boolean | Default `false` |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `seller_id` | `text` | Belongs to `Seller` |
+| `member_id` | `text` | Belongs to `Member` |
+| `role_id` | `text` | Nullable, a `SellerRole` value |
+| `is_owner` | `boolean` | Default `false` |
+| `metadata` | `json` | Nullable |
+
+## SellerRole
+
+The enum in `@mercurjs/types` whose values go in `role_id`.
+
+| Key | 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` |
 
 ## MemberInvite
 
-Table `member_invite`, id prefix `meminv`. A pending team invitation, carrying
-the invited `email`, target `seller_id`, `role_id`, and an expiry.
+A pending invitation to join a store. Table `member_invite`, id prefix `meminv`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `email` | `text` | Searchable, the invited address |
+| `token` | `text` | Signed JWT, indexed |
+| `accepted` | `boolean` | Default `false` |
+| `expires_at` | `dateTime` | Set by the service, 7 days out by default |
+| `role_id` | `text` | The `SellerRole` the member gets on accept |
+| `seller_id` | `text` | Belongs to `Seller` |
+| `metadata` | `json` | Nullable |
+
+A unique index on `(email, seller_id)` covers invites that aren’t accepted or deleted, so a store has one open invite per email.
+
+## OrderGroup
+
+The Seller module also holds the `OrderGroup` model, which groups the per-store orders split from one cart. See the [order group data models](/platform/order-group/reference/data-models) for its fields.

package/content/platform/store/reference/events.mdx

@@ -1,22 +1,23 @@
 ---
-title: "Event reference"
+title: "Seller module events"
 sidebarTitle: "Events"
-description: "Events emitted by the Store domain, for subscribers and side effects."
+description: "Every event the store and team workflows emit, when each fires, and its payload."
 ---
 
-The Store domain emits events as stores and members change. Subscribe to them to
-run side effects such as sending notifications, syncing external systems, or
-kicking off follow-up workflows, instead of polling.
+The Seller module workflows emit events after they write. Subscribe to them to send notifications, sync an outside system, or start follow-up work without polling. The event names are exported from `@mercurjs/core/workflows` as `SellerWorkflowEvents`, `SellerMemberWorkflowEvents`, and `MemberInviteWorkflowEvents`.
 
 ```ts title="src/subscribers/store-approved.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules } from "@mercurjs/types"
 
-export default async function storeApprovedHandler({
+export default async function storeApproved({
   event,
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const sellerId = event.data.id
-  // ...send a welcome email, provision resources, etc.
+  const sellerService = container.resolve(MercurModules.SELLER)
+  const seller = await sellerService.retrieveSeller(event.data.id)
+
+  container.resolve("logger").info(`${seller.name} is open`)
 }
 
 export const config: SubscriberConfig = {
@@ -24,20 +25,44 @@ export const config: SubscriberConfig = {
 }
 ```
 
+This subscriber loads the store when it’s approved. Store events carry only the id, so retrieve the record when you need more.
+
 ## Store events
 
+`SellerWorkflowEvents` covers creation, updates, and every status transition.
+
 | Event | Emitted when | Payload |
 | --- | --- | --- |
-| `seller.created` | A store is created | `{ id }` |
-| `seller.updated` | A store's profile changes | `{ id }` |
-| `seller.approved` | A store is approved (`→ open`) | `{ id }` |
-| `seller.suspended` | A store is suspended | `{ id }` |
-| `seller.terminated` | A store is terminated | `{ id }` |
+| `seller.created` | `createSellersWorkflow` or `createSellerAccountWorkflow` creates a store, once per store | `{ id }` |
+| `seller.updated` | `updateSellersWorkflow` updates a store, once per store | `{ id }` |
+| `seller.deleted` | `deleteSellersWorkflow` soft deletes a store, once per store | `{ id }` |
+| `seller.approved` | `approveSellerWorkflow` opens a pending store | `{ id }` |
+| `seller.suspended` | `suspendSellerWorkflow` suspends a store | `{ id }` |
+| `seller.unsuspended` | `unsuspendSellerWorkflow` reopens a suspended store | `{ id }` |
+| `seller.terminated` | `terminateSellerWorkflow` terminates a store | `{ id }` |
+| `seller.unterminated` | `unterminateSellerWorkflow` returns a terminated store to `suspended` | `{ id }` |
 
-## Member events
+The address, professional details, payment details, and region workflows don’t emit events.
+
+## Membership events
+
+`SellerMemberWorkflowEvents` covers memberships changed directly. Accepting an invite emits `member_invite.accepted` instead of `seller_member.created`.
 
 | Event | Emitted when | Payload |
 | --- | --- | --- |
-| `member_invite.created` | A team invite is sent | `{ id }` |
-| `member_invite.accepted` | An invite is accepted | `{ id }` |
-| `seller_member.created` | A member is added to a store | `{ id }` |
+| `seller_member.created` | `addSellerMemberWorkflow` adds a member to a store | `{ seller_id, member_id }` |
+| `seller_member.updated` | `updateMemberRoleWorkflow` changes a membership’s role | `{ seller_member_id }` |
+| `seller_member.deleted` | `removeSellerMemberWorkflow` removes a membership | `{ seller_id, seller_member_id }` |
+
+## Invite events
+
+`MemberInviteWorkflowEvents` covers team invites. The created payload includes the signed token, so a subscriber can build the invite link.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `member_invite.created` | `createMemberInvitesWorkflow`, `resendMemberInviteWorkflow`, or `createSellersWorkflow` creates an invite, once per invite | `{ id, token, expires_at }` |
+| `member_invite.accepted` | `acceptMemberInviteWorkflow` turns an invite into a membership | `{ seller_id, member_id }` |
+
+<Warning>
+  The `member_invite.created` payload carries a working invite token. Don’t log it or forward it to systems that shouldn’t grant store access.
+</Warning>

package/content/platform/store/reference/links.mdx

@@ -1,71 +1,89 @@
 ---
-title: "Links to other modules"
+title: "Seller module links"
 sidebarTitle: "Links"
-description: "How the Store (Seller) domain links to other modules across the marketplace."
+description: "Every module link that connects the Seller module to other modules, with cardinality, source file, and query.graph aliases."
 ---
 
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Seller module is the most linked domain in the marketplace,
-and almost every other module attaches to a store. Once a link is defined, you
-retrieve related records with `query.graph` using the link alias.
+Mercur modules never reference each other directly: they connect through module links defined in `packages/core/src/links`. The `seller` entity is the most linked record in the marketplace. Once a link exists, `query.graph` resolves the other side through the link’s alias.
 
 ```ts
-const { data: stores } = await query.graph({
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+const { data: [seller] } = await query.graph({
   entity: "seller",
-  fields: ["id", "name", "offers.*", "payout_account.*"],
+  fields: ["id", "name", "regions.*", "payout_account.*"],
+  filters: { id: "sel_01JD8Q1234567" },
 })
 ```
 
-## Commerce
+The tables below list the alias on each side. Read the “From seller” column as a field on `seller`, and the “From the other side” column as a field on the linked entity.
+
+## Catalog and offers
+
+These links decide what a store sells and where it’s listed.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Product | many-to-many, table `product_seller` | `products` | `product.sellers` | `product-seller-link.ts` |
+| Product category | many-to-many | `product_categories` | `product_category.sellers` | `category-seller-link.ts` |
+| Offer | many offers to one seller, read-only | none | `offer.seller` | `offer-seller-link.ts` |
+
+The offer link is read-only and built on the `offer.seller_id` column, so you can’t create or dismiss it through the Link API. Query it from the offer side.
+
+## Orders and payouts
+
+These links attach a store’s sales and settlements.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Order | many orders to one seller | `orders` | `order.seller` | `order-seller-link.ts` |
+| Payout | many payouts to one seller | `payouts` | `payout.seller` | `payout-seller-link.ts` |
+| Payout account | one-to-one | `payout_account` | `payout_account.seller` | `seller-payout-account-link.ts` |
+
+## Regions and customers
+
+These links set where a store trades and who it serves.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Region | many-to-many, table `region_seller` | `regions` | `region.sellers` | `region-seller-link.ts` |
+| Customer | many-to-many | `customers` | `customer.sellers` | `seller-customer-link.ts` |
+| Customer group | many groups to one seller | `customer_groups` | `customer_group.seller` | `seller-customer-group-link.ts` |
 
-| Linked module | Relationship |
-| --- | --- |
-| **Offer** | A store has many offers (`offer.seller_id`, read-only). Offers are how a store sells against a master product. |
-| **Product** | Many-to-many allowlist (`product_seller`) that controls which stores may sell a given master product. |
-| **Product category** | Many-to-many link to the categories a store is associated with. |
-| **Order** | Each order belongs to one store; a store has many orders. |
+`createSellersWorkflow` and `createSellerAccountWorkflow` create the region links. `linkSellerRegionsWorkflow` changes them later.
 
-## Payouts
+## Fulfillment and inventory
 
-| Linked module | Relationship |
-| --- | --- |
-| **Payout** | A store has many payouts. |
-| **Payout account** | A store has one payout account (its provider onboarding record). |
+These links scope fulfillment setup and stock to a store.
 
-## Customers
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Fulfillment set | many sets to one seller | `fulfillment_sets` | `fulfillment_set.seller` | `fulfillment-set-seller-link.ts` |
+| Service zone | many zones to one seller | `service_zones` | `service_zone.seller` | `service-zone-seller-link.ts` |
+| Shipping option | many options to one seller | `shipping_options` | `shipping_option.seller` | `shipping-option-seller-link.ts` |
+| Stock location | many locations to one seller | `stock_locations` | `stock_location.seller` | `stock-location-seller-link.ts` |
+| Inventory item | many items to one seller | `inventory_items` | `inventory_item.seller` | `inventory-item-seller-link.ts` |
 
-| Linked module | Relationship |
-| --- | --- |
-| **Customer** | Many-to-many link to the customers associated with a store. |
-| **Customer group** | A customer group is owned by exactly one store; a store owns many groups. |
+## Pricing and promotions
 
-## Fulfillment & inventory
+These links scope a store’s own pricing and marketing.
 
-| Linked module | Relationship |
-| --- | --- |
-| **Shipping profile** | A store has many shipping profiles. |
-| **Shipping option** | A store has many shipping options. |
-| **Service zone** | A store has many service zones. |
-| **Fulfillment set** | A store has many fulfillment sets. |
-| **Stock location** | A store has many stock locations. |
-| **Inventory item** | A store has many inventory items. |
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Price list | many lists to one seller | `price_lists` | `price_list.seller` | `price-list-seller-link.ts` |
+| Promotion | many promotions to one seller | `promotions` | `promotion.seller` | `promotion-seller-link.ts` |
+| Campaign | many campaigns to one seller | `campaigns` | `campaign.seller` | `campaign-seller-link.ts` |
 
-## Pricing & promotions
+## Reviews
 
-| Linked module | Relationship |
-| --- | --- |
-| **Price list** | A store has many price lists. |
-| **Promotion** | A store has many promotions. |
-| **Campaign** | A store has many campaigns. |
+This link attaches customer reviews of a store.
 
-## Access & reviews
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Review | many reviews to one seller | `reviews` | `review.seller` | `seller-review.ts` |
 
-| Linked module | Relationship |
-| --- | --- |
-| **RBAC role** | A member's role on a store (`seller_member.role_id`, read-only) resolves against the roles module. |
-| **Review** | A store has many reviews. |
+## Order groups
 
-<Note>
-  Read-only links (Offer, RBAC role) are resolved from the field on the owning
-  record and can't be written through the link itself.
-</Note>
+The order group links start from `OrderGroup`, which lives in the Seller module, not from `Seller`. See the [order group links](/platform/order-group/reference/links) for `order-group-order-link.ts` and `order-group-cart-link.ts`.

package/content/platform/store/reference/service.mdx

@@ -1,51 +1,123 @@
 ---
-title: "Service reference"
+title: "Seller module service"
 sidebarTitle: "Service"
-description: "The Seller module service and its methods for working with records directly."
+description: "Resolve the Seller module service, and the generated and custom methods it exposes for direct reads and writes."
 ---
 
-The Seller module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+The Seller module service reads and writes the module’s records directly, without a workflow. Use it for reads in subscribers, scheduled jobs, and custom steps. Its writes don’t emit events, run hooks, or roll back, so prefer the [workflows](/platform/store/reference/workflows) for changes.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with the `MercurModules.SELLER` key from `@mercurjs/types`.
 
 ```ts
-import { MercurModules } from "@mercurjs/types"
+import { MercurModules, SellerStatus } from "@mercurjs/types"
 
-const sellerModuleService = container.resolve(MercurModules.SELLER)
+const sellerService = container.resolve(MercurModules.SELLER)
 
-const [sellers, count] = await sellerModuleService.listAndCountSellers({
-  status: "open",
-})
+const [sellers, count] = await sellerService.listAndCountSellers(
+  { status: SellerStatus.OPEN, is_premium: true },
+  { take: 20, order: { created_at: "DESC" } }
+)
 ```
 
+This lists the 20 newest open premium stores and the total count of matches.
+
 ## Generated methods
 
-Each data model gets a standard set of auto-generated methods. For `Seller`:
+The service extends Medusa’s `MedusaService`, which generates the same eight methods for every model. For `Seller` they are:
 
 | Method | Description |
 | --- | --- |
-| `createSellers(data)` | Create one or more stores |
-| `retrieveSeller(id, config?)` | Retrieve a store by id |
-| `listSellers(filters?, config?)` | List stores matching filters |
-| `listAndCountSellers(filters?, config?)` | List stores with a total count |
-| `updateSellers(data)` | Update one or more stores |
-| `deleteSellers(ids)` | Delete one or more stores |
+| `retrieveSeller(id, config?)` | Retrieve one store by id |
+| `listSellers(filters?, config?)` | List stores that match filters |
+| `listAndCountSellers(filters?, config?)` | List stores and return the total count |
+| `createSellers(data)` | Create one store or an array of stores |
+| `updateSellers(data)` | Update one store or an array of stores by id |
+| `deleteSellers(ids)` | Hard delete stores |
+| `softDeleteSellers(ids)` | Soft delete stores |
+| `restoreSellers(ids)` | Restore soft deleted stores |
 
-The same set exists for every model in the module, such as `Member`, `SellerMember`,
-`MemberInvite`, `ProfessionalDetails`, `SellerAddress`, and `PaymentDetails`
-(e.g. `createMembers`, `listMemberInvites`, `updatePaymentDetails`).
+Each model gets the same set under its own name:
 
-## Team methods
-
-| Method | Description |
+| Model | Method names |
 | --- | --- |
-| `addSellerMember(data)` | Attach a member to a store |
-| `removeSellerMember(sellerId, memberId)` | Detach a member from a store |
-| `createMemberInvites(data)` | Create pending team invitations |
-| `updateMember(data)` | Update a member record |
-
-<Warning>
-  Prefer [workflows](/platform/store/reference/workflows) for anything with side
-  effects (status changes, invites, payouts). The service writes records
-  directly and does **not** emit events or run compensation.
-</Warning>
+| `Member` | `retrieveMember`, `listMembers`, `createMembers`, `updateMembers`, … |
+| `SellerMember` | `retrieveSellerMember`, `listSellerMembers`, `createSellerMembers`, … |
+| `MemberInvite` | `retrieveMemberInvite`, `listMemberInvites`, `deleteMemberInvites`, … |
+| `SellerAddress` | `listSellerAddresses`, `createSellerAddresses`, `updateSellerAddresses`, … |
+| `ProfessionalDetails` | `listProfessionalDetails`, `createProfessionalDetails`, … |
+| `PaymentDetails` | `listPaymentDetails`, `createPaymentDetails`, `updatePaymentDetails`, … |
+| `OrderGroup` | `retrieveOrderGroup`, `listOrderGroups`, `listAndCountOrderGroups`, … |
+
+## Custom methods
+
+The service overrides some generated methods and adds a few of its own.
+
+### createSellers and updateSellers
+
+```ts
+createSellers(
+  data: CreateSellerDTO | CreateSellerDTO[]
+): Promise<SellerDTO | SellerDTO[]>
+
+updateSellers(
+  data: UpdateSellerDTO | UpdateSellerDTO[]
+): Promise<SellerDTO | SellerDTO[]>
+```
+
+Both validate `handle` and throw `INVALID_DATA` when it isn’t URL safe. When `handle` is missing and `name` is present, both set the handle from the name.
+
+### upsertMembers
+
+```ts
+upsertMembers(
+  data: {
+    email: string
+    first_name?: string | null
+    last_name?: string | null
+  }[]
+): Promise<MemberDTO[]>
+```
+
+Matches members by `email` and creates the missing ones. For existing members, it fills `first_name` and `last_name` only when they’re empty. It returns the members in input order.
+
+### createMemberInvites
+
+```ts
+createMemberInvites(
+  data: CreateMemberInviteDTO | CreateMemberInviteDTO[]
+): Promise<MemberInviteDTO | MemberInviteDTO[]>
+```
+
+Throws `INVALID_DATA` if an email already belongs to the target store. For each invite, it signs a JWT with the module’s `jwt_secret`, stores it in `token`, and sets `expires_at` from `invite_valid_duration`.
+
+### validateMemberInviteToken
+
+```ts
+validateMemberInviteToken(token: string): Promise<MemberInviteDTO>
+```
+
+Verifies the token’s signature and returns its invite. Throws `INVALID_DATA` for a bad signature, and `NOT_ALLOWED` when the invite is accepted or expired.
+
+### getStatistics
+
+```ts
+getStatistics(): Promise<SellerStatisticsOutput>
+```
+
+Counts stores by status and returns `{ total, premium, by_status }`, where `by_status` has a key for every `SellerStatus` value.
+
+### Order group reads
+
+`listOrderGroups`, `listAndCountOrderGroups`, and `retrieveOrderGroup` go through a custom repository that computes `seller_count` and `total`. See the [order group service](/platform/order-group/reference/service).
+
+## Module options
+
+The service reads these options from its module registration, typed by `SellerModuleOptions`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `invite_valid_duration` | `604800` | Invite lifetime in seconds, 7 days |
+| `jwt_secret` | `projectConfig.http.jwtSecret` | Secret used to sign and verify invite tokens |
+| `vendor_url` | `MERCUR_VENDOR_URL`, or `""` | Base URL of the Vendor panel |