Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Rewrote the Marketplace, Sellers, and Catalogs user guides (#15003)

jaburghescd4a0e734c78
diff --git a/docs/developer/how-to/build-a-marketplace.mdx b/docs/developer/how-to/build-a-marketplace.mdx
index e86e8ba76b..651353b388 100644
--- a/docs/developer/how-to/build-a-marketplace.mdx
+++ b/docs/developer/how-to/build-a-marketplace.mdx
@@ -362,7 +362,7 @@ Approval is refused while a required requirement is unmet, unless `override_requ
A seller can also take themselves off sale without any operator involvement, by setting `holiday_mode_until`. The catalog stays visible; what stops is selling.
-**Read more:** [The seller lifecycle](/developer/core-concepts/sellers#the-seller-lifecycle), [Onboarding](/user/sellers/onboarding), [Managing sellers](/user/sellers/managing-sellers).
+**Read more:** [The seller lifecycle](/developer/core-concepts/sellers#the-seller-lifecycle), [Onboarding](/user/sellers/onboarding), [Sellers](/user/sellers/sellers).
## Review what sellers list
diff --git a/docs/docs.json b/docs/docs.json
index 0423c693d1..56e89b0f34 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -490,7 +490,7 @@
},
{
"source": "/user/vendors/vendor-management",
- "destination": "/user/sellers/managing-sellers"
+ "destination": "/user/sellers/sellers"
},
{
"source": "/user/vendors/vendor-onboarding-manual",
@@ -550,7 +550,7 @@
},
{
"source": "/use-case/marketplace/admin-dashboard",
- "destination": "/user/sellers/managing-sellers"
+ "destination": "/user/sellers/sellers"
},
{
"source": "/use-case/marketplace/capabilities",
@@ -723,6 +723,10 @@
{
"source": "/developer/agentic/mcp",
"destination": "/developer/agentic/docs-mcp"
+ },
+ {
+ "source": "/user/sellers/managing-sellers",
+ "destination": "/user/sellers/sellers"
}
],
"contextual": {
@@ -1338,10 +1342,11 @@
"pages": [
"user/sellers/sellers",
"user/sellers/onboarding",
- "user/sellers/managing-sellers",
+ "user/sellers/seller-panel",
"user/sellers/products",
"user/sellers/orders",
"user/sellers/commission-rates",
+ "user/sellers/transfers",
"user/sellers/payouts"
]
},
@@ -2988,10 +2993,11 @@
"pages": [
"user/sellers/sellers",
"user/sellers/onboarding",
- "user/sellers/managing-sellers",
+ "user/sellers/seller-panel",
"user/sellers/products",
"user/sellers/orders",
"user/sellers/commission-rates",
+ "user/sellers/transfers",
"user/sellers/payouts"
]
},
diff --git a/docs/images/user/catalogs/catalogs/1-catalogs-list.png b/docs/images/user/catalogs/catalogs/1-catalogs-list.png
new file mode 100644
index 0000000000..a8128b6d78
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/1-catalogs-list.png differ
diff --git a/docs/images/user/catalogs/catalogs/2-audience-step.png b/docs/images/user/catalogs/catalogs/2-audience-step.png
new file mode 100644
index 0000000000..c2b9257d88
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/2-audience-step.png differ
diff --git a/docs/images/user/catalogs/catalogs/3-products-step.png b/docs/images/user/catalogs/catalogs/3-products-step.png
new file mode 100644
index 0000000000..9b32cdebe5
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/3-products-step.png differ
diff --git a/docs/images/user/catalogs/catalogs/4-percentage-pricing.png b/docs/images/user/catalogs/catalogs/4-percentage-pricing.png
new file mode 100644
index 0000000000..64646958dd
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/4-percentage-pricing.png differ
diff --git a/docs/images/user/catalogs/catalogs/5-review-step.png b/docs/images/user/catalogs/catalogs/5-review-step.png
new file mode 100644
index 0000000000..a118d20750
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/5-review-step.png differ
diff --git a/docs/images/user/catalogs/catalogs/6-edit-prices.png b/docs/images/user/catalogs/catalogs/6-edit-prices.png
new file mode 100644
index 0000000000..fc0343cc8a
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/6-edit-prices.png differ
diff --git a/docs/images/user/catalogs/catalogs/7-quantity-break.png b/docs/images/user/catalogs/catalogs/7-quantity-break.png
new file mode 100644
index 0000000000..09e68d4293
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/7-quantity-break.png differ
diff --git a/docs/images/user/catalogs/catalogs/8-commercial-terms.png b/docs/images/user/catalogs/catalogs/8-commercial-terms.png
new file mode 100644
index 0000000000..8d1ace9c12
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/8-commercial-terms.png differ
diff --git a/docs/images/user/catalogs/catalogs/9-priced-by.png b/docs/images/user/catalogs/catalogs/9-priced-by.png
new file mode 100644
index 0000000000..95a12a91e3
Binary files /dev/null and b/docs/images/user/catalogs/catalogs/9-priced-by.png differ
diff --git a/docs/images/user/sellers/commission-rates/1-rates-list.png b/docs/images/user/sellers/commission-rates/1-rates-list.png
new file mode 100644
index 0000000000..88f5f9f804
Binary files /dev/null and b/docs/images/user/sellers/commission-rates/1-rates-list.png differ
diff --git a/docs/images/user/sellers/commission-rates/2-add-rate.png b/docs/images/user/sellers/commission-rates/2-add-rate.png
new file mode 100644
index 0000000000..16ad12d9b8
Binary files /dev/null and b/docs/images/user/sellers/commission-rates/2-add-rate.png differ
diff --git a/docs/images/user/sellers/commission-rates/3-commission-order.png b/docs/images/user/sellers/commission-rates/3-commission-order.png
new file mode 100644
index 0000000000..1e0b1b13dc
Binary files /dev/null and b/docs/images/user/sellers/commission-rates/3-commission-order.png differ
diff --git a/docs/images/user/sellers/onboarding/1-new-seller-page.png b/docs/images/user/sellers/onboarding/1-new-seller-page.png
new file mode 100644
index 0000000000..6cc3a7af46
Binary files /dev/null and b/docs/images/user/sellers/onboarding/1-new-seller-page.png differ
diff --git a/docs/images/user/sellers/onboarding/2-seller-checklist.png b/docs/images/user/sellers/onboarding/2-seller-checklist.png
new file mode 100644
index 0000000000..c6082e8523
Binary files /dev/null and b/docs/images/user/sellers/onboarding/2-seller-checklist.png differ
diff --git a/docs/images/user/sellers/onboarding/3-delivery-method.png b/docs/images/user/sellers/onboarding/3-delivery-method.png
new file mode 100644
index 0000000000..7f1f4123ab
Binary files /dev/null and b/docs/images/user/sellers/onboarding/3-delivery-method.png differ
diff --git a/docs/images/user/sellers/onboarding/4-seller-products.png b/docs/images/user/sellers/onboarding/4-seller-products.png
new file mode 100644
index 0000000000..cd33397669
Binary files /dev/null and b/docs/images/user/sellers/onboarding/4-seller-products.png differ
diff --git a/docs/images/user/sellers/onboarding/5-seller-profile.png b/docs/images/user/sellers/onboarding/5-seller-profile.png
new file mode 100644
index 0000000000..2bd5552aa4
Binary files /dev/null and b/docs/images/user/sellers/onboarding/5-seller-profile.png differ
diff --git a/docs/images/user/sellers/onboarding/6-requirement-review.png b/docs/images/user/sellers/onboarding/6-requirement-review.png
new file mode 100644
index 0000000000..239b2dfa2a
Binary files /dev/null and b/docs/images/user/sellers/onboarding/6-requirement-review.png differ
diff --git a/docs/images/user/sellers/orders/1-orders-list.png b/docs/images/user/sellers/orders/1-orders-list.png
new file mode 100644
index 0000000000..d8fba48ff9
Binary files /dev/null and b/docs/images/user/sellers/orders/1-orders-list.png differ
diff --git a/docs/images/user/sellers/orders/2-seller-card.png b/docs/images/user/sellers/orders/2-seller-card.png
new file mode 100644
index 0000000000..393eb2f6d9
Binary files /dev/null and b/docs/images/user/sellers/orders/2-seller-card.png differ
diff --git a/docs/images/user/sellers/orders/3-seller-order.png b/docs/images/user/sellers/orders/3-seller-order.png
new file mode 100644
index 0000000000..fa63398a22
Binary files /dev/null and b/docs/images/user/sellers/orders/3-seller-order.png differ
diff --git a/docs/images/user/sellers/orders/4-seller-orders-list.png b/docs/images/user/sellers/orders/4-seller-orders-list.png
new file mode 100644
index 0000000000..d500b59c3b
Binary files /dev/null and b/docs/images/user/sellers/orders/4-seller-orders-list.png differ
diff --git a/docs/images/user/sellers/orders/5-fulfill-form.png b/docs/images/user/sellers/orders/5-fulfill-form.png
new file mode 100644
index 0000000000..38baf321ee
Binary files /dev/null and b/docs/images/user/sellers/orders/5-fulfill-form.png differ
diff --git a/docs/images/user/sellers/payouts/1-payouts-list.png b/docs/images/user/sellers/payouts/1-payouts-list.png
new file mode 100644
index 0000000000..d8b5bdecc7
Binary files /dev/null and b/docs/images/user/sellers/payouts/1-payouts-list.png differ
diff --git a/docs/images/user/sellers/payouts/2-balance-card.png b/docs/images/user/sellers/payouts/2-balance-card.png
new file mode 100644
index 0000000000..644be4a66a
Binary files /dev/null and b/docs/images/user/sellers/payouts/2-balance-card.png differ
diff --git a/docs/images/user/sellers/payouts/3-payout-detail.png b/docs/images/user/sellers/payouts/3-payout-detail.png
new file mode 100644
index 0000000000..12e00c6dc1
Binary files /dev/null and b/docs/images/user/sellers/payouts/3-payout-detail.png differ
diff --git a/docs/images/user/sellers/payouts/4-row-menu.png b/docs/images/user/sellers/payouts/4-row-menu.png
new file mode 100644
index 0000000000..9dcb7f5a74
Binary files /dev/null and b/docs/images/user/sellers/payouts/4-row-menu.png differ
diff --git a/docs/images/user/sellers/payouts/5-mark-as-paid.png b/docs/images/user/sellers/payouts/5-mark-as-paid.png
new file mode 100644
index 0000000000..4825d7dc15
Binary files /dev/null and b/docs/images/user/sellers/payouts/5-mark-as-paid.png differ
diff --git a/docs/images/user/sellers/products/1-seller-products-list.png b/docs/images/user/sellers/products/1-seller-products-list.png
new file mode 100644
index 0000000000..fc3489f32c
Binary files /dev/null and b/docs/images/user/sellers/products/1-seller-products-list.png differ
diff --git a/docs/images/user/sellers/products/2-seller-product-in-review.png b/docs/images/user/sellers/products/2-seller-product-in-review.png
new file mode 100644
index 0000000000..3a4561d1cc
Binary files /dev/null and b/docs/images/user/sellers/products/2-seller-product-in-review.png differ
diff --git a/docs/images/user/sellers/products/3-admin-product-in-review.png b/docs/images/user/sellers/products/3-admin-product-in-review.png
new file mode 100644
index 0000000000..d53b851058
Binary files /dev/null and b/docs/images/user/sellers/products/3-admin-product-in-review.png differ
diff --git a/docs/images/user/sellers/products/4-sent-back.png b/docs/images/user/sellers/products/4-sent-back.png
new file mode 100644
index 0000000000..b261e8c9eb
Binary files /dev/null and b/docs/images/user/sellers/products/4-sent-back.png differ
diff --git a/docs/images/user/sellers/products/5-publishing.png b/docs/images/user/sellers/products/5-publishing.png
new file mode 100644
index 0000000000..4d0f6934d4
Binary files /dev/null and b/docs/images/user/sellers/products/5-publishing.png differ
diff --git a/docs/images/user/sellers/seller-panel/1-panel-home.png b/docs/images/user/sellers/seller-panel/1-panel-home.png
new file mode 100644
index 0000000000..a848f246a7
Binary files /dev/null and b/docs/images/user/sellers/seller-panel/1-panel-home.png differ
diff --git a/docs/images/user/sellers/seller-panel/2-setup-checklist.png b/docs/images/user/sellers/seller-panel/2-setup-checklist.png
new file mode 100644
index 0000000000..e7c73950b8
Binary files /dev/null and b/docs/images/user/sellers/seller-panel/2-setup-checklist.png differ
diff --git a/docs/images/user/sellers/seller-panel/3-fulfilled-order.png b/docs/images/user/sellers/seller-panel/3-fulfilled-order.png
new file mode 100644
index 0000000000..3cd6fdc4ec
Binary files /dev/null and b/docs/images/user/sellers/seller-panel/3-fulfilled-order.png differ
diff --git a/docs/images/user/sellers/seller-panel/4-earnings.png b/docs/images/user/sellers/seller-panel/4-earnings.png
new file mode 100644
index 0000000000..17856cd766
Binary files /dev/null and b/docs/images/user/sellers/seller-panel/4-earnings.png differ
diff --git a/docs/images/user/sellers/seller-panel/5-payouts.png b/docs/images/user/sellers/seller-panel/5-payouts.png
new file mode 100644
index 0000000000..3ccfb4ba9d
Binary files /dev/null and b/docs/images/user/sellers/seller-panel/5-payouts.png differ
diff --git a/docs/images/user/sellers/sellers/1-sellers-list.png b/docs/images/user/sellers/sellers/1-sellers-list.png
new file mode 100644
index 0000000000..bf9188ef88
Binary files /dev/null and b/docs/images/user/sellers/sellers/1-sellers-list.png differ
diff --git a/docs/images/user/sellers/sellers/2-seller-page.png b/docs/images/user/sellers/sellers/2-seller-page.png
new file mode 100644
index 0000000000..41b73deae4
Binary files /dev/null and b/docs/images/user/sellers/sellers/2-seller-page.png differ
diff --git a/docs/images/user/sellers/sellers/3-custom-fields.png b/docs/images/user/sellers/sellers/3-custom-fields.png
new file mode 100644
index 0000000000..67c3aedbcb
Binary files /dev/null and b/docs/images/user/sellers/sellers/3-custom-fields.png differ
diff --git a/docs/images/user/sellers/sellers/4-approve-anyway.png b/docs/images/user/sellers/sellers/4-approve-anyway.png
new file mode 100644
index 0000000000..74eafd6c98
Binary files /dev/null and b/docs/images/user/sellers/sellers/4-approve-anyway.png differ
diff --git a/docs/images/user/sellers/sellers/5-more-actions.png b/docs/images/user/sellers/sellers/5-more-actions.png
new file mode 100644
index 0000000000..49533edd13
Binary files /dev/null and b/docs/images/user/sellers/sellers/5-more-actions.png differ
diff --git a/docs/images/user/sellers/transfers/1-transfers-list.png b/docs/images/user/sellers/transfers/1-transfers-list.png
new file mode 100644
index 0000000000..118af91258
Binary files /dev/null and b/docs/images/user/sellers/transfers/1-transfers-list.png differ
diff --git a/docs/images/user/sellers/transfers/2-balance-card.png b/docs/images/user/sellers/transfers/2-balance-card.png
new file mode 100644
index 0000000000..56bd8816c1
Binary files /dev/null and b/docs/images/user/sellers/transfers/2-balance-card.png differ
diff --git a/docs/images/user/settings/marketplace/1-marketplace-overview.png b/docs/images/user/settings/marketplace/1-marketplace-overview.png
deleted file mode 100644
index 0b92af1a5a..0000000000
Binary files a/docs/images/user/settings/marketplace/1-marketplace-overview.png and /dev/null differ
diff --git a/docs/images/user/settings/marketplace/1-payouts.png b/docs/images/user/settings/marketplace/1-payouts.png
new file mode 100644
index 0000000000..6052af1336
Binary files /dev/null and b/docs/images/user/settings/marketplace/1-payouts.png differ
diff --git a/docs/images/user/settings/marketplace/2-seller-admission.png b/docs/images/user/settings/marketplace/2-seller-admission.png
new file mode 100644
index 0000000000..f58e0df365
Binary files /dev/null and b/docs/images/user/settings/marketplace/2-seller-admission.png differ
diff --git a/docs/images/user/settings/marketplace/3-seller-files.png b/docs/images/user/settings/marketplace/3-seller-files.png
new file mode 100644
index 0000000000..77f6a2ca92
Binary files /dev/null and b/docs/images/user/settings/marketplace/3-seller-files.png differ
diff --git a/docs/images/user/settings/marketplace/4-communication.png b/docs/images/user/settings/marketplace/4-communication.png
new file mode 100644
index 0000000000..5ca4c40c3e
Binary files /dev/null and b/docs/images/user/settings/marketplace/4-communication.png differ
diff --git a/docs/images/user/settings/marketplace/5-commission-tax.png b/docs/images/user/settings/marketplace/5-commission-tax.png
new file mode 100644
index 0000000000..b05921155e
Binary files /dev/null and b/docs/images/user/settings/marketplace/5-commission-tax.png differ
diff --git a/docs/images/user/settings/seller-requirements/1-requirements-list.png b/docs/images/user/settings/seller-requirements/1-requirements-list.png
new file mode 100644
index 0000000000..d9fe6e0529
Binary files /dev/null and b/docs/images/user/settings/seller-requirements/1-requirements-list.png differ
diff --git a/docs/user/catalogs/catalogs.mdx b/docs/user/catalogs/catalogs.mdx
index 6a82f68537..064506a1ea 100644
--- a/docs/user/catalogs/catalogs.mdx
+++ b/docs/user/catalogs/catalogs.mdx
@@ -1,93 +1,237 @@
---
title: "Catalogs"
-description: "Give a company or customer group its own product range, prices and order terms."
+description: "Learn how to control which products a group of buyers can see and what they pay."
---
-A catalog is a commercial agreement. It decides what an audience sees, what they pay, and how much they must order — the B2B equivalent of a negotiated price list.
+A catalog is an agreement with a set of buyers that decides two things: which products they can see, and what those products cost them. It is assigned to an audience, which is either a company or a customer group, and once it is active, everyone in that audience shops under its terms.
-Catalogs are how you give a wholesale customer their own range and pricing without running a second store. To manage them, open **Catalogs** under Products.
+Catalogs are how a store sells to different buyers on different terms from one set of products. A trade customer pays agreed prices, a wholesale group buys in multiples of a case, and a distributor sees a range nobody else does, all without a separate store or a duplicate product.
-## The two ways a catalog is used
+Pricing and visibility are separate decisions, and a catalog can change one without changing the other. A catalog that lists no products covers your whole range, so it can change prices without hiding anything. A catalog that lists products covers only those, and its audience sees nothing else, whether or not the price changes too.
-The single most useful thing to understand is that an **empty product list means something different from a full one**.
+To manage catalogs, navigate to **Products → Catalogs** in the admin dashboard.
-<Tabs>
- <Tab title="Pricing overlay">
- **No products added.** Nothing is hidden — the audience browses your normal range — but they pay this catalog's prices.
+<Note>A catalog's prices are kept with the catalog itself and never appear under **Products → Price Lists**. Use a price list for prices that apply to anyone matching a rule, such as a channel, a market or a quantity, and a catalog for terms agreed with a particular audience. See [<u>Price Lists</u>](/user/pricing/price-lists).</Note>
- This is what you want for a customer who buys anything you sell, at agreed rates.
- </Tab>
- <Tab title="Restricted range">
- **Products added.** The audience now sees *only* those products, at this catalog's prices.
+## Reviewing Catalogs
- This is what you want for a buyer with a contracted range — the twelve SKUs in their agreement and nothing else.
- </Tab>
-</Tabs>
+![The Catalogs list, showing each catalog's status, pricing and product count](/docs/images/user/catalogs/catalogs/1-catalogs-list.png)
-Adding the first product to an empty catalog therefore does not add one item to what a customer sees. It switches the catalog into restricting mode, and they now see only that item.
+The list shows one row per catalog.
-## Creating a catalog
+| Column | What it means |
+|---|---|
+| **Name** | What the agreement is called. |
+| **Status** | Whether the catalog is in force. Only an active catalog changes what its audience sees or pays. |
+| **Pricing** | How it prices its products: normal prices, prices you entered, or a percentage off. |
+| **Products** | How many products it lists. A catalog listing none covers your whole range instead. |
+| **Created at** | When the catalog was made. |
-**Add catalog** opens a short wizard: name it, choose who it is for, pick the products it covers, set what they pay, then review. Nothing is created until you finish.
+The **Status** filter narrows the list to **Active** or **Inactive**, **Add filter** offers the created and updated dates, and the menu at the end of a row offers **Edit** and **Delete**.
-You can also create a bare catalog and fill it in afterwards — the same cards are on the catalog page.
+<Note>The list does not show who each catalog is assigned to, so two catalogs covering the same audience cannot be identified from this screen. Open a catalog to see its **Audiences** card.</Note>
-## Who sees it
+## How to Create a Catalog
-A catalog reaches nobody until you assign an audience. Assign it to:
+**Add catalog** opens a five-step wizard. Nothing is created until the last step, and **Back** can be used at any point.
-- a **company** — which covers that company and every division beneath it, or
-- a **customer group**.
+### Details
-<Note>
-Company assignments win. A buyer whose company — or one above it — has any catalog gets those catalogs, and their customer group is not consulted. To give company buyers tier pricing, assign the catalog to their companies or divisions rather than to a group.
-</Note>
+- **Name** - What your team calls the agreement, such as Wholesale.
+- **Description** - An internal note about what the agreement is for. Shoppers never see it.
-## What they pay
+### Audience
-A catalog prices through its own price list, set up on the catalog page. Each product row shows where its price comes from:
+![The Audience step, with two companies assigned to the same catalog](/docs/images/user/catalogs/catalogs/2-audience-step.png)
-| From | Meaning |
-|---|---|
-| Entered | An amount typed onto this catalog's price list |
-| Adjusted | The shop price with this catalog's percentage applied |
-| Shop price | The normal price — this catalog does not price that product |
+Who the catalog is for. **Assign** takes:
+
+- **Audience type** - **Company** or **Customer group**.
+- **Audience** - The company or group itself. A company assignment covers that company and every sub-unit below it, so assigning to a parent covers its divisions.
+
+An audience can be added now or later, but a catalog assigned to nobody cannot be activated unless it is a sales channel's default catalog, so one has to be set before the catalog can start applying.
+
+### Products
+
+![The Products step, with several products moved into the catalog](/docs/images/user/catalogs/catalogs/3-products-step.png)
+
+The range of products the agreement covers. Products are searched for on the right, and when added are moved into the catalog's product list on the left. They can be added one by one, or in bulk by selecting every product on the page or every product matching the search.
+
+Leaving this step empty is a valid setup rather than an incomplete one. An empty list means the catalog covers every product in your store, so its audience carries on seeing your whole range and only the price changes. That is what you want when the agreement is about price alone.
+
+### Pricing
+
+![The Pricing step, set to a percentage off base prices](/docs/images/user/catalogs/catalogs/4-percentage-pricing.png)
+
+What the audience pays. The choice made here decides which pricing controls the catalog's page carries afterwards, and it can be changed at any time.
+
+- **Normal prices** - Your usual shop prices, unchanged.
+- **Prices I enter for this catalog** - A price you set yourself for each variant.
+- **A percentage off base prices** - Your shop prices adjusted by a percentage.
+
+Each is described in full under [<u>How a Catalog Prices Its Products</u>](#how-a-catalog-prices-its-products). A percentage and its quantity tiers can be set here in the wizard. Prices you enter yourself cannot, because they are typed against each variant, so a catalog using them is created first and priced from its own page.
+
+### Review
+
+![The Review step, which states that the catalog is created inactive](/docs/images/user/catalogs/catalogs/5-review-step.png)
+
+The summary lists the name, audiences, product count and pricing. **Create catalog** then opens the catalog's own page.
+
+<Note>A new catalog is always created inactive and has no effect until it is activated. Enter its prices first, then activate it.</Note>
+
+## How a Catalog Prices Its Products
+
+The **Pricing** card on the catalog's page holds one of three choices. The choice decides how the catalog works out its prices, and which other controls appear beside it.
+
+### Normal Prices
+
+The catalog charges your usual shop prices and carries no pricing controls of its own. Use it when the catalog exists to decide which products its audience can see rather than what they pay.
+
+### Prices I Enter for This Catalog
+
+The catalog charges a price you set for each variant, in each currency you sell in. Prices are set in a grid that opens over the catalog page, or loaded from a CSV file. There is no percentage setting in this mode. A price you enter is stored on the catalog, so changing the product's own shop price later leaves the catalog's price exactly as you set it.
+
+![The price grid, with a price entered against a variant](/docs/images/user/catalogs/catalogs/6-edit-prices.png)
+
+**Enter prices** appears on both the **Products** card and the **Pricing** card, and opens the same grid.
+
+1. Click **Enter prices**. Each variant is listed with its SKU, a **From qty**, a **Price** and a **Compare-at price**, in the currency shown at the top. The dropdown there switches to your other currencies, each priced separately.
+2. Double-click the **Price** cell, type the price and press Tab. A single click only selects the cell, so typing straight after one does nothing.
+3. Click **Save prices**. The grid counts unsaved changes as you work, and confirms how many prices were saved.
+
+The variant's row on the **Products** card then shows your price labeled **Entered**, where it previously showed the shop price labeled **Shop price**.
+
+#### Quantity Tier
+
+![The price grid with a quantity break that lowers the price from 10 units](/docs/images/user/catalogs/catalogs/7-quantity-break.png)
+
+A quantity tier lowers the line item price once a buyer takes a set number of units, which is how volume is set up on a catalog. The **Pricing** card carries no setting for breaks in this mode. A break is an extra row in the price grid, or an extra row in an imported file, and the **From qty** on that row is the quantity it starts at.
+
+1. In the empty row under the variant, type the quantity the break starts at under **From qty**.
+2. Type the price for that quantity in the row that appears.
+3. Click **Save prices**.
+
+The variant's row on the **Products** card then carries a marker such as **+1 tier** beside its price, and hovering over it lists every quantity with the price that applies from it. A variant can hold ten breaks at most.
+
+#### Importing and Exporting These Prices
+
+**Import** and **Export** on the **Pricing** card move this catalog's prices as a CSV file. This is the practical way to load an agreed price list a buyer has sent you, or to set prices for many products at once instead of entering them one by one.
+
+- **SKU** and **Price** are required.
+- **Currency**, **Minimum quantity** and **Compare at Price** are optional.
+
+Because the minimum quantity is a column, quantity breaks travel as extra rows for the same SKU, and the grid and the file are two routes to the same prices. The import panel offers a blank template and an example file, and the step after upload matches your file's columns to those fields.
+
+### A Percentage Off Base Prices
+
+When using the **Percentage Off Base Prices** model, the catalog works its prices out from your shop prices rather than storing its own, so changing a product's shop price changes what this audience pays at the same time. There is no grid and no import in this mode, because there are no individual prices to enter.
+
+- **Percentage** - How much to adjust your shop prices by. A discount is entered as a negative percentage, and an increase as a positive one.
+- **Quantity tiers** - A deeper percentage from a given quantity upward, which is how a bulk discount is set up without pricing each variant by hand. Each tier takes its own percentage and the quantity it starts at, and a catalog can hold ten tiers at most.
+- **Adjust compare-at prices** - Whether the compare-at price is adjusted by the same percentage. With it off, the compare-at price a shopper sees crossed out stays as it is on the product.
+
+<Note>Each tier is worked out from your shop price, never from the tier below it. A catalog set to 10% off with a tier of 20% off from fifty units charges twenty percent off the shop price at fifty, not twenty percent off the already-discounted price.</Note>
+
+<Note>A catalog carrying tiers but no overall percentage charges your shop prices until a line reaches the first tier, which is how an agreement that gives no discount below a case is set up.</Note>
+
+## How to Edit a Catalog
+
+Everything set in the wizard can be changed afterwards from the catalog's own page, which is laid out in cards.
+
+- **Products** - **Add products** adds more, and each row offers **Remove from catalog**. Each row also carries its own **Minimum** and **Multiple**, which override the catalog-wide terms for that product.
+- **Catalog** - The name and the internal description.
+- **Pricing** - The same three choices as the wizard, with whichever controls that choice carries beside them.
+- **Commercial terms** - The smallest quantity and order value this agreement accepts, described in the next section.
+- **Audiences** - **Assign** adds another company or group, and each row offers **Remove**. A catalog can serve several audiences at once.
+
+### Commercial Terms
+
+![The Commercial terms card, with a minimum order quantity and an order multiple](/docs/images/user/catalogs/catalogs/8-commercial-terms.png)
+
+Commercial terms set the smallest order this agreement accepts, which is how a catalog enforces case quantities and minimum order values.
+
+- **Minimum order quantity** - The fewest units a buyer may take of one product. A smaller quantity is refused in the cart, and the message names the quantities they can order instead.
+- **Order multiple** - The step size above that minimum. A multiple of 24 allows 24, 48 and 72 but not 30. Steps are counted from the minimum, so a minimum of 50 in steps of 24 allows 50, 74 and 98.
+- **Order minimums** - The smallest total an order may come to, set separately for each currency. Only the items count towards it, so more expensive delivery method does not make up the difference. Buyers see how much more they need to add, and cannot check out until they reach it.
+
+Both quantity rules apply to every product in the catalog, and a product can override either of them on its own row on the **Products** card.
+
+The minimum and the multiple are settled separately, each taking the first answer it finds in this order:
+
+1. The product's row on this catalog, where an override has been set.
+2. The catalog's own **Commercial terms**.
+3. The product's own setting on its product page, used when no catalog states one.
+
+So a product's row on the catalog beats the catalog-wide term, and both beat whatever the product itself says. Because the two are settled separately, a catalog can supply the multiple while the product supplies the minimum.
+
+<Note>Quantity rules apply to buyers shopping for themselves. An order your team builds in the dashboard is not held to them, so staff can enter a quantity that was agreed as an exception.</Note>
+
+## How to Activate or Deactivate a Catalog
+
+**Activate** at the top of the catalog page puts the agreement in force after a confirmation. Its audience then sees the products it lists and pays its prices. A catalog with no audience cannot be activated, unless it is a sales channel's default catalog. Otherwise there would be nobody for it to apply to.
+
+**Deactivate** stops it applying. Everything the catalog holds is kept, so activating it again makes its terms apply again.
+
+<Warning>The confirmation says a deactivated catalog's audience goes back to the shop prices. That is only true when no other catalog covers them, and if a second catalog still applies, the audience is priced by that second catalog instead.</Warning>
+
+## How to Delete a Catalog
+
+**Delete catalog** under **More actions** removes the catalog, its audience assignments and its price list with every price in it. The products themselves stay in your store. This cannot be undone, so deactivate the catalog instead when the agreement might be needed again.
+
+## Which Catalog Applies
+
+A buyer can be covered by more than one catalog, and two rules decide which one prices their order.
+
+**Only one kind of audience is used.** A buyer's company is consulted first, and their customer groups are used only when no catalog is assigned to their company or to any company above it. A company buyer is therefore never priced by their customer group's catalog, which is why trade tiers belong on the companies themselves. Where neither applies, the sales channel's default catalog is used, if one is set.
+
+**The closest company to the buyer decides, and then the cheapest price.** The buyer's own company is checked first, then the company above it, and so on up the company hierarchy. The first one carrying a catalog that prices the product wins, even where a company further up would have charged less. A division's own catalog therefore prices its buyers ahead of its parent company's.
+
+Where one company carries more than one catalog, the buyer pays the lowest price any of them gives for the quantity being bought. Quantity breaks count in that comparison, so which catalog wins can change with the quantity ordered. Take one catalog charging 40.00 a unit and another charging 45.00 that drops to 35.00 from ten units: a buyer taking nine pays 40.00 under the first catalog, and a buyer taking ten pays 35.00 under the second.
+
+### How to Check What a Buyer Will Pay
+
+![A draft order line naming the catalog that priced it](/docs/images/user/catalogs/catalogs/9-priced-by.png)
+
+A buyer's price is not shown on the product page, the company page or the customer's page, so the way to see it is to start a draft order.
+
+1. Navigate to **Orders → Draft Orders** and click **New Order**.
+2. Pick the business under **Company (optional)**. The customer list then offers only the people who buy for it.
+3. Choose the customer, add the product under **Add a variant**, and click **New Order**.
+
+The draft's line shows the price this buyer is charged, with **Priced by** and the catalog's name beneath it as a link. The variant search shows your shop price while you are building the order, because the catalog is applied when the draft is created rather than while you are searching.
-A percentage is the quickest way to express "this customer gets 15% off everything", with no rows to maintain as your prices change.
+A draft keeps the price it was created with even if the catalog changes afterwards. Changing a line's quantity through **Edit order** prices it again on save, and the line may then name a different catalog.
-<Warning>
-Removing a catalog's pricing deletes the price list and the prices in it, and that audience goes back to paying normal prices. The dashboard warns you before saving such a change.
-</Warning>
+<Note>A draft order holds stock for as long as it exists, so a draft started only to check a price takes those units out of what you can sell until it is removed.</Note>
-## Order terms
+## Ways to Use Catalogs
-Catalogs can also carry the commercial terms of the agreement — how much a buyer must order:
+### Agreed Prices for One Business
-- a **minimum order quantity** and **order multiple**, set for the whole catalog or per product
-- an **order minimum**, the least a whole order must come to, set per currency
+Create a catalog, assign it to the company, leave the **Products** step empty and choose **Prices I enter for this catalog**. Then enter each price on the catalog page, save them, and click **Activate**, because a new catalog does nothing until it is activated. The company's buyers see your whole range and pay your agreed prices. This is the most common arrangement, and leaving the product list empty is what keeps their view of your range unchanged.
-Leave them blank and buyers may order any quantity, any total.
+### A Range Only Some Buyers See
-## Going live
+Create a catalog, assign it to the company or group, and add only the products that audience should have. Its buyers then see exactly those products and nothing else, as long as no other active catalog also covers them. Where an audience has a second active catalog that lists products, its buyers see both catalogs' products together.
-Catalogs are created switched off, so you can build one up without anyone seeing a half-finished agreement. **Activate** puts it into effect: its audience starts seeing its assortment and getting its prices.
+<Warning>A catalog that lists products hides every other product from its audience. An audience whose only catalog holds six products sees six products in the shop and nothing else. Where that audience is covered by a second active catalog, they see what both catalogs list.</Warning>
-**Deactivate** stops it applying. The audience goes back to shop prices and everything the catalog holds is kept, so you can switch it on again later.
+### An Extra Product for One Audience
-<Note>
-A catalog with no audience cannot be activated — there would be nobody to apply it to. The exception is a catalog set as a sales channel's default, which reaches buyers through the channel rather than through an assignment.
-</Note>
+Letting one audience have access to a product that nobody else can buy takes two catalogs, because a catalog restricts its audience to the products it lists. A catalog holding that product on its own would leave its audience being able to see only that one product and nothing else.
-## Deleting a catalog
+1. Build a **Main range** catalog holding the products everyone should see, and assign it to a catch-all customer group, or set it as the channel's default catalog.
+2. Build a second catalog holding the special product, and assign it to the audience that may buy it.
+3. Assign the **Main range** catalog to that audience as well, and activate both.
-**Delete** ends the agreement for good. It removes the catalog, its audience assignments, and its price list together with the prices in it. Your products stay in the store, and orders already placed are untouched.
+An audience sees every product listed by any catalog covering them, so this audience sees the main range plus the special product, while everyone else sees the main range only. Make sure both catalogs list products, because a catalog with an empty product list removes the restriction for everyone it covers and would show them your whole range.
-<Warning>
-Deleting cannot be undone, and the prices typed onto the catalog's price list cannot be recovered. If you only want the agreement to stop applying, deactivate it instead.
-</Warning>
+<Note>A catalog can only narrow what a sales channel already publishes. A product that is not published to the channel cannot be reached by adding it to a catalog, so publish the special product first and let the catalogs decide who sees it. See [<u>Sales Channels</u>](/user/settings/sales-channels).</Note>
-## Related
+## Further Reading
-- [Selling to businesses](/user/how-to/selling-to-businesses) — the whole B2B setup, end to end
-- [Companies](/user/customers/companies) and [Customer Groups](/user/customers/customer-groups) — the two audiences a catalog is assigned to
-- [Price Lists](/user/pricing/price-lists) — pricing matched by market, volume or zone rules rather than owned by an agreement
+- [<u>Price Lists</u>](/user/pricing/price-lists) - Prices that apply to anyone matching a rule
+- [<u>Companies</u>](/user/customers/companies) - The businesses and divisions a catalog is assigned to
+- [<u>Groups</u>](/user/customers/customer-groups) - The other kind of audience a catalog can have
+- [<u>Draft Orders</u>](/user/orders/draft-orders) - Building an order on a buyer's behalf
+- [<u>Products</u>](/user/products/products) - The products a catalog covers
diff --git a/docs/user/sellers/commission-rates.mdx b/docs/user/sellers/commission-rates.mdx
index ea7ad320da..6340255306 100644
--- a/docs/user/sellers/commission-rates.mdx
+++ b/docs/user/sellers/commission-rates.mdx
@@ -1,68 +1,119 @@
---
title: "Commission Rates"
-description: "What the marketplace charges on each sale — set as rates with rules, applied in list order, and frozen onto every sale."
+description: "Learn how to set what your marketplace charges sellers on each sale, and which sales each rate applies to."
---
-Commission is what you charge a seller for a sale. It is set as **rates**, each with the rules for when it applies, and recorded per sale as a **commission line** that never changes afterwards.
+A commission rate is what your marketplace charges a seller on a sale. Each rate carries a charge, which is either a percentage of the sale or a flat fee per unit, and the conditions deciding which sales it applies to.
-Find them under **Sellers → Commission rates**.
+A marketplace usually has more than one rate: a standard charge on everything, and narrower rates charging differently for one category, one seller or sales above a certain value. The rates sit in an ordered list, and the first one matching is the one charged.
-## A rate
+Rates are configuration rather than records. Editing one changes what the next sale is charged and never what a past one was, because the fee charged on an order is written once when the order is placed and is never worked out again.
-| Field | Meaning |
+To manage them, navigate to **Sellers → Commission rates** in the admin dashboard.
+
+## Reviewing Your Commission Rates
+
+![The Commission rates list, in the order they are applied](/docs/images/user/sellers/commission-rates/1-rates-list.png)
+
+The list shows one row per rate, in the order they are tried.
+
+| Column | What it means |
|---|---|
-| Name and code | How it appears on the seller's earnings and in reports |
-| Kind | **Percentage** of the sale, or a **fixed** fee per sale |
-| Value | The percentage for a percentage rate, or the fee per currency for a fixed one |
-| Enabled | Switched-off rates are skipped |
+| **Name** | What the rate is called, with your own code for it beneath. |
+| **Value** | What it charges, such as 10.0%. |
+| **Conditions** | Which sales it applies to, or **Every sale** where it has none. |
+| **Enabled** | Whether the rate is being charged at all. |
+
+**The order of the rows is the order of priority.** There is no priority number to set: the first rate whose conditions match is the one charged, and the rest are not consulted. Rows are dragged to reorder them.
+
+## How a Rate Is Chosen
+
+A rate is chosen for each item sold rather than for the order as a whole, so one order can be charged by several rates. The marketplace walks the enabled rates from the top of the list and takes the first one whose conditions admit that item and whose charge can be made in the order's currency.
+
+A rate with no conditions matches everything, which is how a marketplace states a single standard charge. That rate belongs at the **bottom** of the list, because nothing below a rate that matches everything is ever reached.
+
+<Warning>Where no rate matches an item, no commission is charged on it and the seller keeps the sale, less any consumer tax your marketplace remits. Narrowing every rate with conditions and leaving nothing to catch the remainder is the way a marketplace stops earning without anything appearing to be wrong.</Warning>
-A percentage rate can carry a **floor and cap per currency** — at least $1, at most $50 — so a small sale still earns you something and a large one is not commissioned without limit. A fixed rate states its fee per currency, and applies only in currencies it has an amount for.
+Two kinds of sale are never commissioned. Products your own team sells are the marketplace's own and carry no fee, and the seller charged is the one recorded against the item when the order was placed rather than whoever owns the product today.
-## The list is the precedence
+## How to Create a Commission Rate
-This is the most important thing to understand, and it is deliberately simple.
+![The Add commission rate form](/docs/images/user/sellers/commission-rates/2-add-rate.png)
-When a sale happens, Spree walks your enabled rates **from the top of the list** and takes **the first whose rules match**. There is no scoring, and no built-in idea that a product rule beats a category rule. What you see in the table is exactly what happens — to change the answer, drag a row up or down.
+1. Click **Add commission rate**.
+2. Enter a **Name**, and a **Code** if you want your own identifier for it.
+3. Choose the **Charge**, which is either a percentage of the sale or a flat fee.
+4. Enter the value. A percentage takes one figure, up to 100, and a flat fee takes an amount per currency, charged for every unit sold.
+5. Add any **Conditions**, described below. A rate with none charges every sale.
+6. Set whatever else the rate needs from the fields below the conditions, described under [<u>Other Settings</u>](#other-settings).
+7. Click **Create commission rate**.
-Two consequences:
+The new rate appears at the top of the list and starts charging immediately.
-- **A rate with no rules matches everything.** That is how you express your default — and it belongs at the **bottom**, because anything below it can never be reached.
-- **New rates are created at the top**, since a new rate is there to say something more specific than what exists.
+The top is the right place for most new rates, because a rate is usually created to charge something differently from the rates already there, and it has to sit above them to be reached. The exception is a rate with no conditions, which charges everything and stops the search. That one belongs at the bottom, and a new one has to be dragged there.
-If nothing matches, **no commission is charged**. A marketplace with no rate covering a sale charges nothing rather than inventing a default nobody set.
+<Note>With a flat fee, a currency left empty is one this rate does not charge, and sales in that currency fall through to the next rate instead. A percentage is a ratio rather than an amount, so it charges in every currency.</Note>
-## Rules
+### Conditions
-Rules narrow when a rate applies. A rate can hold several, and **all of them must match**; the items listed *within* one rule are alternatives.
+Conditions narrow which sales a rate charges. Every condition on a rate has to hold, and a condition naming several records matches any of them.
-| Rule | Matches when the item is |
+| Condition | What it limits the rate to |
|---|---|
-| Seller | from one of the sellers named |
-| Category | in one of the categories named |
-| Product | one of the products named |
-| Item total | worth at least, or at most, an amount |
+| **Seller** | Items sold by the sellers you pick. |
+| **Category** | Products in the categories you pick, and anything filed beneath them. |
+| **Product** | The products you pick. |
+| **Sale value** | Items whose value falls within a range, set as a minimum and an optional maximum. |
+
+**Sale value** is measured per item, on the same figure the fee itself is charged on, so a band and the charge it governs always weigh a sale the same way. The minimum is included in the band and the maximum is not, which lets two bands meet at a number without overlapping or leaving a gap. A rate charging 15% below 50 and one charging 10% from 50 upwards are two rates, each holding one of these.
+
+<Warning>A condition that names nothing never matches, so a half-filled condition takes the rate out of use rather than widening it. A **Seller** condition with no sellers chosen charges nobody. Make sure to enter values for any conditions added to a rate.</Warning>
+
+### Other Settings
+
+- **Floor and cap (optional)** - On a percentage rate, the least and the most it will ever charge, set per currency. These are amounts rather than ratios, so each holds only in the currency it was written in, and a sale in a currency with neither set is charged without limit.
+- **Maximum per sale line (optional)** - On a flat fee, a ceiling on what one line can be charged. A flat fee is charged in full for every unit sold, so on a cheap item it can come to more than the seller made on the sale, and this is what stops that.
+- **Tax on commission** - The tax charged on the commission itself. Your fee is a separate supply to the seller, so this is added on top of the fee rather than taken out of it, and the two are invoiced and reported apart. Leaving it empty uses the default under [<u>Marketplace Settings</u>](/user/settings/marketplace).
+- **Charge on delivery** - Whether commission is also charged on what the seller collected for delivery, rather than on the goods alone. Available on a percentage rate only, since a flat fee is charged per unit sold and has no sensible reading on a parcel.
+- **Charge on the gross price** - Whether commission is charged on the price including the customer's tax. Left off, it is charged on the seller's net revenue, which is the usual basis where your fee is taxed as its own supply. Discounts come off the figure either way.
+- **Enabled** - A disabled rate is skipped when a sale is charged, without being deleted.
+
+## How to Change Which Rate Takes Priority
+
+A rate's position in the list is its priority. The marketplace reads the list from the top and charges the first rate that matches, so a rate higher up outranks every rate beneath it, and the highest one that matches an item is the only one consulted for that item.
+
+![Dragging a commission-free rate above the standard rate](/docs/images/user/sellers/commission-rates/3-commission-order.png)
+
+1. Navigate to **Sellers → Commission rates**.
+2. Grab the handle at the start of a row.
+3. Drag it up to raise its priority, or down to lower it.
+
+The new order takes effect on the next sale. Nothing already charged changes.
-So "electronics from these three sellers" is two rules on one rate.
+The general rule for ordering is that the narrower the conditions of the rate are, the higher it belongs. A rate charging one category differently has to sit above the rate charging everything, because the broad rate would otherwise match first and the narrow one would never be reached. Priority is the only thing deciding this, so a narrow rate placed below a broad one is simply inactive.
-## What the fee is charged on
+These setups all depend on the order:
-- **Net of tax, by default.** The customer's VAT is not the seller's revenue, so commission is charged on the amount excluding it. Switch **tax inclusive** on to charge on the gross instead.
-- **After discounts, always.** Commission is charged on what the customer actually paid — a promotion is the seller's concession.
-- **Delivery is optional.** **Include shipping** charges commission on the delivery charge as well as the goods. A fixed fee cannot do this, since charging it again on the parcel would double it.
+- **Commission-free products.** A rate charging 0% with a **Product** or **Category** condition, placed at the top, trades the named goods for nothing. Below it, the standard rate charges everything else.
+- **A negotiated rate for one seller.** A rate charging 5% with a **Seller** condition, above a standard rate charging 10%. The named seller is charged 5% and everybody else falls through to 10%.
+- **Rates that vary with the value of the sale.** A rate charging 15% below 50 above a rate charging 10% from 50 upwards, with the standard rate below both. The first band to match wins, which is why the bands are ordered rather than given priorities of their own.
+- **A standard rate.** One rate with no conditions, at the bottom, catching everything the rates above did not.
-## Tax on your commission
+<Warning>Raising a percentage rate with no conditions above the others turns off everything beneath it, because it matches every sale in every currency and ends the search. A flat fee does not reach quite that far, since it is skipped for a currency it states no amount in, and the rates below it still apply to those sales. The list stays as it was and nothing warns you, so the effect only shows up in what the next sales are charged.</Warning>
-Your commission is a service you sell to the seller — a separate taxable supply from their sale to the customer. It is taxed at the **seller's** location, not the shopper's: a German marketplace charging a French seller is a cross-border business supply, and where the shopper lives has nothing to do with it.
+## How to Edit or Delete a Rate
-The tax rate is taken from the rate itself if you set one, otherwise from your tax setup using the seller's address, otherwise from the store's default commission tax rate.
+A rate can be edited or deleted at any time, from the menu at the end of its row.
-## What gets recorded
+To edit one, click **Edit**. The same fields open as when the rate was created, and saving changes what the next sale is charged. Commission already charged is untouched, so editing a rate is never a way to correct a fee on an order that has already been placed.
-When an order is placed, the matching rate is applied and the result frozen as a commission line — one per item, plus one per delivery where the rate includes it. Every field is a snapshot: editing or deleting the rate later changes nothing already charged. Lines cannot be edited; correcting a charge means recording a reversal, as with any ledger.
+To delete one, click **Delete** and confirm. Commission already charged on past sales is not affected either, so deleting a rate changes what future sales are charged rather than rewriting what has happened. The rate itself stays readable behind the commission it charged, so an old order can still say which rate produced its fee.
-Sellers see their commission on each earning in their panel.
+<Warning>Deleting a rate can leave sales with no commission at all. Where nothing below it matches, the sales it was charging fall through the rest of the list and are charged nothing, and the seller keeps the whole amount. Check that a rate with no conditions is sitting at the bottom of the list before deleting anything above it.</Warning>
-## Related
+## Further Reading
-- [Payouts](/user/sellers/payouts) — where the net of sale and commission ends up
-- [Managing sellers](/user/sellers/managing-sellers) — the sellers a rule can name
+- [<u>Seller Transfers</u>](/user/sellers/transfers) - What each sale earned its seller after commission
+- [<u>Marketplace Orders</u>](/user/sellers/orders) - Where the commission appears on an order
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - The default tax on commission
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling what sellers are owed
diff --git a/docs/user/sellers/managing-sellers.mdx b/docs/user/sellers/managing-sellers.mdx
deleted file mode 100644
index 0a5909e2ea..0000000000
--- a/docs/user/sellers/managing-sellers.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: "Managing Sellers"
-description: "The sellers list, a seller's page, and what you can do from it — suspend, reinstate, edit on their behalf, and see what they are owed."
----
-
-**Sellers** lists every seller on the marketplace with their status, contact, how far through onboarding they are, and how many products and team members they have. Search by name, contact or email, and filter by status.
-
-Open a seller and their page is arranged as cards.
-
-## What the seller maintains
-
-Some cards belong to the seller — they keep them up to date from their own panel, and anything you change here is done on their behalf:
-
-- **Contact** and **Brand** — the profile shoppers see. A seller who has not written a description yet shows as such.
-- **Billing address** and **Returns address** — where payouts are billed from, and where customer returns go.
-- **Team** — the people who can sign in to their panel. A seller always keeps at least one member; the last one cannot be removed without inviting someone else first.
-
-## What only you see
-
-- **Status** — approve, suspend, reinstate or cancel. See [Onboarding](/user/sellers/onboarding) for the lifecycle.
-- **Onboarding** — the checklist and its state.
-- **Balance** — what they have earned, what is pending, what is owed and what has been paid. See [Payouts](/user/sellers/payouts).
-- **Payouts and tax** — their payout schedule and minimum payout amount, which override the store defaults, and how their tax is remitted. The seller never sees or edits these.
-
-## Suspending a seller
-
-**Suspend** pauses them: their products stop being offered and they cannot sell, but nothing is deleted and their ledger is untouched. **Reinstate** puts them back. Give a reason when suspending — the seller sees it.
-
-Sellers can also pause themselves. **Holiday mode** hides their listings until a date they choose, without any action from you.
-
-## Deleting a seller
-
-A seller with order history is kept, not removed — the orders naming them have to keep meaning something. Cancel them instead.
-
-## Related
-
-- [Onboarding](/user/sellers/onboarding) — inviting and approving
-- [Products](/user/sellers/products) — reviewing what they list
-- [Payouts](/user/sellers/payouts) — the balance card in depth
diff --git a/docs/user/sellers/onboarding.mdx b/docs/user/sellers/onboarding.mdx
index 9c64b126db..b6caa8c64d 100644
--- a/docs/user/sellers/onboarding.mdx
+++ b/docs/user/sellers/onboarding.mdx
@@ -1,70 +1,223 @@
---
title: "Onboarding"
-description: "Invite a seller, set the checklist they complete before they can sell, and approve them when it is done."
+description: "Learn how a seller joins your marketplace, from the first invitation through the checklist to the decision that lets them trade."
---
-Bringing a seller onto a marketplace is a process with a decision at the end of it, not a switch. You invite them, they work through a checklist you have defined, they ask to be reviewed, and you approve — or send them back.
+Seller onboarding is everything between a seller record being created and that seller being able to trade on your marketplace. Somebody is invited to run the seller account, they accept and sign in to their own panel, they work through a checklist of onboarding tasks that your marketplace sets, and finally your team decides whether to admit them or not.
-## The lifecycle
+The work is split between the two sides. Your team creates the record, sends the invitation, settles anything that needs a decision from a person, and makes the final call. The seller does the filling in of the details, which is why most of the checklist can only be completed by them.
-| Status | Meaning |
-|---|---|
-| Pending | Created, nothing sent yet |
-| Invited | Invitation sent, not yet accepted |
-| Onboarding | Working through the requirements |
-| Ready for review | Waiting on you |
-| Approved | Live — they can sell |
-| Rejected | Sent back, with a reason; they return to Onboarding |
-| Suspended | Paused by you |
-| Canceled | Gone |
+This guide follows that order from beginning to end, so it can be read by your team and handed to a seller as the instructions for their side. Each section says whose work it is and which panel it happens in.
-Only an **approved** seller can sell.
+<Note>The checklist itself is written once for the whole marketplace under [<u>Seller Requirements</u>](/user/settings/seller-requirements). This page covers taking one seller through it.</Note>
-## 1. Invite a seller
+## How Onboarding Works
-Navigate to **Sellers**, click **Add seller** and name them. On their page, click **Invite** and enter the email of the person who will run the account. They receive a link; accepting it creates their sign-in and lands them in the seller panel, where the checklist is waiting.
+| Stage | Who does it | Seller status |
+|---|---|---|
+| The seller record is created | Your team | **Pending** |
+| Somebody is invited to run the account | Your team | **Invited** |
+| The invitation is accepted | The seller | **Onboarding** |
+| The checklist is worked through | The seller, with your team settling anything that needs reviewing | **Onboarding** |
+| The checklist is submitted | The seller | **Ready for review** |
+| The seller is admitted | Your team | **Approved** |
-## 2. The checklist
+The status is what decides which actions are offered at each point, so a seller who has not been invited cannot be approved, and a seller for which nobody has accepted the invite cannot start the checklist. Creating the record is covered under [<u>Sellers</u>](/user/sellers/sellers). Everything after it is on this page.
-What a seller must do before selling differs by marketplace — a hardware marketplace wants insurance documents, a craft marketplace wants a filled-in profile and one product. So the checklist is yours to define, under **Settings → Seller requirements**.
+## How to Invite a Seller
-Every store starts with seven, all required:
+A seller record on its own has nobody attached to it. An invitation is what grants a person access to the seller panel, and sending the first invite is what starts the onboarding process.
-| Requirement | Done when |
-|---|---|
-| Accept terms | The seller has read and accepted your marketplace terms |
-| Complete profile | Their public profile is filled in |
-| Billing address | They have given the address payouts are billed from |
-| Returns address | They have given the address customer returns go to |
-| Delivery method | They offer at least one way to ship |
-| Shipping box | They have recorded the size and weight of the box they ship in |
-| Minimum products | They have listed at least the number you set |
+![A new seller, with nothing on the checklist done and Invite in the header](/docs/images/user/sellers/onboarding/1-new-seller-page.png)
-Six more are available to add: a **document** upload for you to review, a **seller confirmation** they attest to, a **manual check** you perform, a **seller policy** they must publish, **required custom fields** they must fill in, and — for marketplaces that pay through a provider — a **payout account** they connect.
+1. Navigate to **Sellers** and open the seller.
+2. Click **Invite** in the header.
+3. Check the email address, which opens with the seller's contact email already in it. Change it where somebody else is running the seller.
+4. Click **Send invitation**.
-For each one you choose:
+The status becomes **Invited**, the header button becomes **Send again**, and the address appears on the **Team** card as an outstanding invitation. An email goes to that address with a link for joining.
-- **Required** or recommended. Required items must be done before you can approve the seller; recommended ones are shown but do not block.
-- **Active** — switch off to stop asking for it without deleting it.
-- **Instructions** — what the seller sees, and why you need it.
+An invitation is valid for two weeks by default. Once it has expired, revoke it on the **Team** card and send a new one in its place. When somebody accepts, the person who sent the invitation receives an email saying so.
-<Note>
-With no requirements at all, a seller can ask to be reviewed straight away.
-</Note>
+A seller can have more than one person on its team. The header button sends the first invitation only, and everybody after that is invited from the **Team** card. See [<u>Sellers</u>](/user/sellers/sellers).
-Requirements are checked three ways, which is what lets one list cover very different demands: some are **computed** from the seller's own data (a billing address exists, three products are listed), some are **attested** by the seller (accepting terms), and some are **verified** by you (a document, a manual check).
+<Note>Switching off **Email sellers** under [<u>Marketplace Settings</u>](/user/settings/marketplace) stops the approval, rejection and suspension emails. Invitations are sent either way, because without one nobody can reach the panel at all.</Note>
-## 3. Review and approve
+## How a Seller Accepts an Invitation
-When the seller finishes, they submit for review and move to **Ready for review**. Open their page:
+This section and the following one happen in the seller panel rather than in your admin dashboard.
-- The **Onboarding** card shows every requirement and its state. Documents they uploaded are there to open; anything you verify by hand is marked complete by you.
-- **Approve** makes them live. A required item still incomplete blocks this — approving anyway is a deliberate override, recorded as such.
-- **Send back** returns them to Onboarding with a reason they will see.
+The invited person opens the invitation link in their email and fills in a short form:
-Your developers can turn on automatic approval, so a seller who completes every required item is approved the moment they submit.
+- **First name**
+- **Last name**
+- **Password**
+- **Password confirmation**
-## Related
+Where the address has no account yet, submitting the form creates their sign-in and takes them straight into the seller panel, with no separate log in afterwards. Where it already has one, they enter that account's existing password instead, and no second account is created. The seller's status becomes **Onboarding**.
-- [Managing sellers](/user/sellers/managing-sellers) — suspending, reinstating, and the rest of a seller's page
-- [Payouts](/user/sellers/payouts) — the payout account requirement, and what happens once they sell
+Where the address has no account yet, that link is the whole credential, so anybody holding it can create the account and join the seller's team. Where it already has one, the link on its own is not enough, because joining also takes that account's password. Either way the link should go no further than the person it was meant for, and an invitation that has gone astray is stopped with **Revoke** on the **Team** card.
+
+## Working Through the Checklist
+
+![The seller's checklist in their own panel](/docs/images/user/sellers/onboarding/2-seller-checklist.png)
+
+The checklist is under **Setup** in the seller panel, with the number completed out of the total shown both in the sidebar and at the top of the page. Each requirement is a row that expands to show what is being asked and, in some cases, the control for doing it.
+
+None of the tasks depend on each other, so the rows can be worked through in any order. The page opens with the first outstanding task already expanded, so a seller returning to the checklist sees what to do next without reading back through what they have finished.
+
+Each row carries a status. The seller's checklist and your **Onboarding** card use different wording for the same states, because each is written for its own reader.
+
+| What it means | On the seller's checklist | On your Onboarding card |
+|---|---|---|
+| Not started | No badge | **Pending** |
+| Sent to the marketplace and waiting | **In review** | **Under review** |
+| Returned to the seller | **Needs another look** | **Sent back** |
+| Done | **Done** | **Done** |
+| Counted as met without being done | | **Waived** |
+
+Some rows are filled in on the checklist itself, and the rest carry a **Go there** button to wherever in the panel they are satisfied.
+
+- **Accept terms** - The terms appear in the row itself, with **Accept the terms** underneath. If the marketplace publishes them elsewhere as well, **Read the terms** opens a link to that copy.
+- **Complete profile** - Opens **Profile**, which holds the name, description, logo and cover photo shoppers see.
+- **Billing address** and **Returns address** - Filled in on the row itself, so the seller keeps their place on the checklist.
+- **Delivery method** - Opens **Settings → Delivery methods**, covered below.
+- **Shipping box** - Opens **Settings → Package types**, where the size and weight of the box orders are packed in is recorded. Delivery rates are quoted against that box, so the measurements need to be the real ones.
+- **Minimum products** - Satisfied by adding the minimum number of **Products**, covered below.
+- **Required custom fields** - The fields appear in the row and are saved from there.
+- **Seller policy** - Opens **Settings → Policies**. The documents the marketplace asks for are listed at the top of that page under **Asked of you**, each with a **Write it** button.
+- **Payout account** - Hands the seller to the payout provider's own form, which collects their bank and identity details. Neither reaches your marketplace. See [<u>Payouts</u>](/user/sellers/payouts).
+- **Seller confirmation**, **Manual check** and **Document** - All three are completed in the row itself, and are covered below.
+
+A requirement your marketplace marked as not required shows as **Optional** and never holds the seller back.
+
+### How a Seller Adds a Delivery Method
+
+A delivery method is one way a seller can ship an order, and what that costs the shopper. A physical product with no delivery method behind it quotes no rate at checkout, so the order cannot be completed. An order of digital goods alone skips delivery altogether, so this matters to any seller shipping something physical.
+
+![A seller adding a delivery method in their own panel](/docs/images/user/sellers/onboarding/3-delivery-method.png)
+
+The list is under **Settings → Delivery methods** in the seller panel. It holds the seller's own methods alongside any the marketplace shares with its sellers, told apart by the **Owner** column. A shared method cannot be edited by the seller, and a single shared method satisfies this requirement for every seller at once.
+
+1. Navigate to **Settings → Delivery methods**.
+2. Click **Add delivery method**.
+3. Fill in the form.
+4. Click **Save**.
+
+The form asks for the following:
+
+- **Name** - What shoppers read at checkout, such as Standard delivery or Next day.
+- **Internal name** - A name only the seller sees, for telling two similar methods apart.
+- **Show at checkout** - On by default. Switching it off keeps the method without offering it to anyone.
+- **Kind of goods** - The delivery profile this method belongs to, which is what decides the goods it can ship. It opens on the marketplace's default profile, the right answer for anything posted as an ordinary parcel.
+- **Ships to** - The delivery zone the method covers. Left blank, the method is offered everywhere that kind of goods reaches.
+- **Pricing** - How the charge is worked out. It opens on a flat rate, which takes one amount for each currency the marketplace trades in. See [<u>Rate calculators</u>](/user/settings/delivery-profiles#rate-calculators) for the other ways a rate can be priced.
+- **When this method applies** - Optional conditions, such as a minimum order value. With none set, the method is offered on every order it is able to ship.
+
+A method is edited or deleted from its own row. Deleting one leaves orders already shipped with it untouched.
+
+<Note>Your team can read and edit a seller's delivery methods under [<u>Delivery Profiles</u>](/user/settings/delivery-profiles), but a new one cannot be created there on a seller's behalf. To give every seller a way to ship without each of them building one, create a delivery method of your own and switch on **Available to sellers**.</Note>
+
+### How a Seller Adds Products
+
+A seller builds a product in their own panel using the same form your team uses, so [<u>Adding Products</u>](/user/products/adding-products) covers the fields themselves. Two things are different.
+
+The seller's form leaves out what belongs to the marketplace rather than to the seller: sales channels, categories, collections, tags and the tax category. Those are filed against the product when it is reviewed.
+
+Status is not a field either. The seller saves a product as a draft and then presses **Submit for review**, which passes it to your team to decide on. See [<u>Seller Products</u>](/user/sellers/products) for that decision and what happens after it.
+
+![A seller's products list, with Import and Export above it](/docs/images/user/sellers/onboarding/4-seller-products.png)
+
+A seller with a long range does not have to build every product by hand. **Import** and **Export** sit above the products list in their panel, exactly as they do on yours, and cover that seller's own products only. See [<u>Import and Export</u>](/user/products/import-and-export) for the file itself and [<u>Seller Products</u>](/user/sellers/products) for what to watch when a seller exports and reimports.
+
+Imported products arrive as drafts, which is where a product built by hand starts too. The seller then selects them in the list and uses the bulk **Submit for review** action to send the whole batch at once.
+
+A product counts towards the **Minimum products** requirement as soon as it is saved, whether or not it has been submitted or approved. This part of the checklist does not wait on a review.
+
+<Note>Switching on **Publish seller products automatically** under [<u>Marketplace Settings</u>](/user/settings/marketplace) approves a seller's product the moment it is submitted, with nobody reviewing it. Approving is not the same as listing it: the product still reaches shoppers only on a sales channel that carries it, and only while its seller is approved and not on holiday. See [<u>Seller Products</u>](/user/sellers/products).</Note>
+
+### Documents, Confirmations and Manual Checks
+
+These three kinds are the ones your marketplace writes the wording for, and the seller answers each of them on the checklist row rather than anywhere else in the panel. Every one of them gives the seller a note box for anything that should go with their answer.
+
+- **Seller confirmation** - The seller reads a statement your marketplace wrote, such as holding the rights to sell what they list, and clicks **Confirm**.
+- **Manual check** - The seller clicks **Confirm** to say they are ready to be checked, and uses the note for whatever reference your marketplace asked them for, such as a tax number.
+- **Document** - The seller attaches a file, as a PDF, a photo or an office document, and clicks **Submit for review**.
+
+What happens next is where the three differ. A seller confirmation is taken at the seller's word, so the row reads **Done** as soon as they confirm it. A manual check and a document both read **In review** until somebody on your team accepts them.
+
+### What Else a Seller Can Set Up
+
+![A seller's profile page, with their business details and tax registrations](/docs/images/user/sellers/onboarding/5-seller-profile.png)
+
+The checklist is the shortest route to being approved rather than every single detail the seller can manage. Everything below belongs to the seller and can be added or changed at any point, during onboarding or long after it.
+
+- **Stock locations** - Under **Settings → Stock locations**. A seller can hold more than one, which is how a business shipping from two warehouses keeps stock in each. The returns address on the checklist is read from these, taking the default location that accepts returns, so which location holds that mark decides where customers send things back to.
+- **Delivery methods** - Under **Settings → Delivery methods**. One is enough to be approved, and more can be added whenever the seller wants to offer another way to ship or charge differently for a region.
+- **Package types** - Under **Settings → Package types**. A seller can record several boxes and mark one as the default, which is the box delivery rates are quoted against. The list also carries any packaging your marketplace shares, which a seller can ship with but not change. See [<u>Package Types</u>](/user/settings/package-types).
+- **Policies** - Under **Settings → Policies**. Anything your checklist asks for is listed under **Asked of you**, and a seller can publish further documents of their own beside them and rewrite any of them later. See [<u>Policies</u>](/user/settings/policies).
+- **Profile** - Under **Profile**. The name, description, logo and cover photo shoppers see are the seller's to change at any time. The storefront address is the exception, and only your team can change that.
+- **Business details** - On the **Profile** page. The legal name and registration number of the business behind the seller, which is what a commission invoice has to be made out to.
+- **Tax registrations** - On the **Profile** page. One registration per tax regime the seller trades under, such as a UK VAT number or a US EIN, and a number can be checked against the registry it belongs to.
+
+No default requirement asks for business details or a tax registration, so a seller fills those in when they have them rather than being held up for them. A marketplace that wants either before admitting anybody collects it with a **Manual check**, where the seller leaves the number in the note and somebody on your team verifies it. See [<u>Seller Requirements</u>](/user/settings/seller-requirements).
+
+### How a Seller Submits for Review
+
+**Submit for review** sits at the top of the checklist and stays unavailable while anything required is outstanding, with a count of what is left beside it. Optional rows are ignored by that count.
+
+Pressing it moves the seller to **Ready for review** and passes the decision to your team. The checklist then reports that the marketplace is reviewing the application. No email goes out at this point, so the panel is the only confirmation the seller has until a decision is made.
+
+## How to Review What a Seller Submitted
+
+The rest of the onboarding process is managed by your team back in the admin dashboard.
+
+![A seller's page during onboarding, with a task waiting for review](/docs/images/user/sellers/onboarding/6-requirement-review.png)
+
+Anything waiting on your team appears on the **Onboarding** card of the seller's page, marked **Under review**, with the seller's note and a link to download whatever they attached. A policy requirement carries **View policy** instead, which opens what the seller published.
+
+1. Navigate to **Sellers** and open the seller.
+2. Find the row marked **Under review** and read what the seller sent.
+3. Click **Accept** to mark the requirement done, or **Send back** to return it to them.
+
+Accepting moves the seller's progress forward by one row. Sending it back returns the requirement to the seller, where it reads **Needs another look** and can be submitted again.
+
+Reviewing a single requirement does not change the seller's own status. A seller who has already submitted stays at **Ready for review** while a row goes back and forth. To return the whole application to the seller, use **Send back to onboarding** under **More actions**, which is covered in [<u>Sellers</u>](/user/sellers/sellers).
+
+## How to Waive a Requirement
+
+Waiving excuses one seller from something the marketplace asks of everyone, such as a seller who satisfied it elsewhere or one the requirement was never written for. The row counts as met for that seller alone, and the record shows it was waived rather than done.
+
+1. On the **Onboarding** card, open the menu at the end of the row.
+2. Click **Waive for this seller**.
+3. Confirm.
+
+Any requirement that is switched on can be waived, including the ones worked out from the seller's own data such as **Accept terms** or **Minimum products**. A requirement switched off for the whole marketplace cannot, because it is already asking nothing.
+
+A waiver is its own decision rather than an edit of what came before, so anything the seller submitted earlier stays readable on the record. It also cannot be accepted or sent back afterwards.
+
+## How to Approve a Seller
+
+Approving is what lets a seller trade. See [<u>Sellers</u>](/user/sellers/sellers) for the approval itself, what happens when the checklist is unfinished, and the other decisions available on a seller.
+
+Once approved, the seller receives an email saying so unless **Email sellers** is switched off under [<u>Marketplace Settings</u>](/user/settings/marketplace), and their own panel reports that their products are on sale.
+
+<Warning>Approving a seller does not put their products on your storefront. Each product still has to be approved and then listed on a sales channel, neither of which the seller can do. See [<u>Seller Products</u>](/user/sellers/products).</Warning>
+
+### What the Seller Receives
+
+Three emails can reach a seller during onboarding, and all come from your store rather than from a person on your team.
+
+- **The invitation**, sent when **Send invitation** is clicked, carrying the link that lets somebody join the team.
+- **The approval**, sent when the seller is approved.
+- **The rejection**, sent when the seller is turned down.
+
+Submitting the checklist sends nothing, and neither does accepting or sending back a single requirement. Those show up in the seller panel only.
+
+## Further Reading
+
+- [<u>Sellers</u>](/user/sellers/sellers) - The sellers list, a seller's page, approving and suspending
+- [<u>Seller Requirements</u>](/user/settings/seller-requirements) - Writing the checklist
+- [<u>The Seller Panel</u>](/user/sellers/seller-panel) - What a seller sees on their side
+- [<u>Seller Products</u>](/user/sellers/products) - Reviewing and listing what a seller submits
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - Automatic approval and seller emails
diff --git a/docs/user/sellers/orders.mdx b/docs/user/sellers/orders.mdx
index d83a86e1b9..0102f93af2 100644
--- a/docs/user/sellers/orders.mdx
+++ b/docs/user/sellers/orders.mdx
@@ -1,32 +1,103 @@
---
title: "Marketplace Orders"
-description: "One checkout across several sellers becomes one order per seller — paid once, shipped separately, settled separately."
+description: "Learn how a checkout spanning several sellers is split, what differs on each order page, and how sellers fulfill their own."
---
-This is what makes a marketplace different from a shop, and it is worth understanding before anything else.
+A marketplace order is an order carrying products from one of your sellers. Where a shopper buys from two sellers in a single checkout, that one purchase becomes one order per seller, each fulfilled by the seller it belongs to and each carrying its own share of what was paid.
-A customer fills one basket, enters one address, and pays once. But each seller needs their own order: they ship separately, they are paid separately, and they must never see each other's business. So at checkout, a basket spanning several sellers becomes an **order group** — one container holding one order per seller.
+The shopper experiences a single purchase. They pay once, receive one confirmation, and see their basket arriving in separate deliveries. Your team sees the separate orders, and each seller sees only their own.
-| Level | Owns |
+To review them, navigate to **Orders** in the admin dashboard.
+
+## How a Checkout Is Split
+
+![The Orders list, with two seller orders from one purchase](/docs/images/user/sellers/orders/1-orders-list.png)
+
+A checkout is split when its goods belong to more than one party, and your own goods count as a party of their own. A basket holding one seller's goods, or only your own, produces one ordinary order. A basket mixing your own goods with one seller's produces two.
+
+Where it does span several, the checkout becomes a **purchase** holding one order per seller. The purchase keeps the number the shopper saw, and the orders number off it. A purchase numbered R1003 produces R1003-1 and R1003-2.
+
+The split is a real division rather than a presentational one. Each order carries its own items, its own delivery charge and its own totals, worked out in its own right rather than divided down from the basket.
+
+| Held once for the purchase | Held by each order |
|---|---|
-| Order group | The customer, the addresses, the single payment, the combined total |
-| Order | One seller's items, its fulfillments, its own money lines |
+| The payment the shopper made | The items that seller sold |
+| The delivery and billing addresses | The delivery charge and the totals |
+| The contact email | The fulfillments, and who fulfills them |
+| | The commission and the seller's earning |
+
+<Note>The purchase itself is not an order and does not appear as a row in your orders list. Searching for R1003 finds R1003-1 and R1003-2, which are the orders that exist.</Note>
+
+### Finding the Other Parts of a Purchase
+
+![The Seller card on an order, with the link to the rest of the purchase](/docs/images/user/sellers/orders/2-seller-card.png)
+
+The **Seller** column on the orders list names the seller behind each order, with an empty field if the order is one of your own. It is shown by default, because the list holds your orders and your sellers' together.
+
+To see the rest of one purchase, open any order from it and use **View all orders in this purchase** on the **Seller** card. That filters the orders list to that purchase alone. The same link is available as a **Purchase** column on the list, which is hidden until you add it.
+
+## What Differs on a Seller's Order Page
+
+![A seller's order in the admin dashboard](/docs/images/user/sellers/orders/3-seller-order.png)
+
+A seller's order is processed in the same way as any other, and [<u>Processing Orders</u>](/user/orders/processing-orders) covers the screen itself. However, there are three things are there that an ordinary order does not have:
+
+- **Seller** names the business that sold it, linked to their seller page. On an order of your own this card reads **Sold by you**. Where the order was part of a larger purchase, the card also says so and links to the rest.
+- **Commission** lists what your marketplace charged, one row per item, naming the rate that charged it, the fee and any tax on that fee. Delivery appears as its own row where the rate charges on it.
+- **Seller transfers** shows what the sale earned the seller once the order is fulfilled, and whether it has been settled into a payout yet.
-The one payment is apportioned across the orders as **payment splits**, so each seller's share of a single charge is recorded exactly. That is what makes per-seller refunds and settlement possible later.
+The order summary carries both the order total and the marketplace fee, so what the shopper paid and what you charged are readable together.
-## In the dashboard
+<Note>Commission is charged when the order is placed, and the seller's earning is created when the order is fulfilled. An order that has not shipped therefore shows a commission with no transfer against it yet.</Note>
-On the **Orders** list, an order that is part of a group shows it in the **Order group** column, with a link to view every order in that group. On an order's page, a **Marketplace** card names the seller — or says the order is the marketplace's own — and shows which group it belongs to.
+## Who Fulfills a Seller Order
+
+The seller does, from their own panel. The goods are theirs, held at their own stock location, and shipped using the delivery methods they set up.
+
+Your team can still act on a seller's order from the admin dashboard in the same way as any other, which is what you need when a seller is unresponsive or a customer escalates to you.
+
+Some marketplaces are run the other way round. Where sellers hold their stock in a warehouse the marketplace owns, your own team picks and ships every order and fulfills each seller's orders on their behalf from the admin dashboard. Nothing about the split changes: each seller still has their own order, earns on it and is paid for it. What changes is who packs the parcel. A marketplace working this way puts its stock locations and delivery methods in its own hands rather than asking each seller to set up their own, which is covered under [<u>Onboarding</u>](/user/sellers/onboarding).
+
+## How a Seller Fulfills an Order
+
+![A seller's orders list in their own panel](/docs/images/user/sellers/orders/4-seller-orders-list.png)
+
+Orders reach a seller under **Orders** in their panel, where they see only their own. The list carries the order number, when it was placed, its fulfillment and payment status and its total, and can be filtered by any of those.
+
+![A seller fulfilling an order, with the tracking number and notification](/docs/images/user/sellers/orders/5-fulfill-form.png)
+
+Opening an order shows what has to go out on the **Fulfillments** card, with the delivery method the shopper chose and the location it ships from.
+
+1. Tick the items going in this parcel, and set the quantity where only some are being sent.
+2. Enter the **Tracking number**.
+3. Choose the **Shipping carrier**, or leave it to be detected from the tracking number.
+4. Leave **Send shipment notification to customer** ticked to email the shopper, or clear it to ship quietly.
+5. Click **Fulfill items**.
+
+The order moves to **Fulfilled**, or to **Partial** where some items are still to come, and the stock comes off the seller's own location. Fulfilling the whole order is also what creates the seller's earning.
+
+A seller can split a parcel into two, add a tracking number afterwards, print a packing slip or a label, and cancel a parcel to put the goods back on the shelf. Returns and claims are raised and handled from the same page. See [<u>The Seller Panel</u>](/user/sellers/seller-panel).
+
+## How the Money Divides
+
+Take a shopper who buys one $36.00 mug from a seller and pays $6.00 to have it delivered, on a marketplace charging ten percent commission on the goods alone. That seller's order comes to $42.00, and divides like this:
+
+| | |
+|---|---|
+| The customer pays | $42.00 for this part of their basket |
+| Your commission, at ten percent of the $36.00 of goods | $3.60 |
+| The seller earns | $38.40 |
-A basket with only one seller's products, or only your own, produces a single order with no group.
+Whether delivery is included in the fee depends on the rate, which can be set to charge on it or not. See [<u>Commission Rates</u>](/user/sellers/commission-rates).
-## Who does what
+The seller's earning appears as a transfer once the order is fulfilled, and earnings gather on their balance until they are settled into a payout. See [<u>Seller Transfers</u>](/user/sellers/transfers) and [<u>Payouts</u>](/user/sellers/payouts).
-- **The seller** sees their order in their panel, and ships it from their own stock location with their own delivery method. Shipping is what records their earning.
-- **You** see every order. Refunds are handled per order, so refunding one seller's items never touches another's.
-- **The customer** sees one purchase, and one confirmation.
+<Note>Refunding a seller's order writes a reversal that takes back the seller's share of what was refunded rather than the whole amount, so a refund does not charge them commission on goods that came back. The commission on the order itself is not rewritten, because it is the record of what was charged at the time. See [<u>Seller Transfers</u>](/user/sellers/transfers).</Note>
-## Related
+## Further Reading
-- [Payouts](/user/sellers/payouts) — how a shipped order turns into money owed
-- [Processing Orders](/user/orders/processing-orders) — the order page in general
+- [<u>Processing Orders</u>](/user/orders/processing-orders) - Working an order through, which applies to seller orders too
+- [<u>The Seller Panel</u>](/user/sellers/seller-panel) - How a seller runs their own orders
+- [<u>Commission Rates</u>](/user/sellers/commission-rates) - What the marketplace charges on each sale
+- [<u>Seller Transfers</u>](/user/sellers/transfers) - The ledger of what each order earned its seller
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling what sellers are owed
diff --git a/docs/user/sellers/payouts.mdx b/docs/user/sellers/payouts.mdx
index 049bae0bf6..1dd0080185 100644
--- a/docs/user/sellers/payouts.mdx
+++ b/docs/user/sellers/payouts.mdx
@@ -1,71 +1,165 @@
---
title: "Payouts"
-description: "What each seller has earned, what they are owed, and how it reaches them — by hand, or through Stripe Connect."
+description: "Learn how to settle what your sellers are owed and record each payment as sent."
---
-Spree keeps a ledger of what every seller earns, and pays it out on a schedule. Two pages under **Sellers** show it, and one settings page controls how it works.
+A payout is a settlement with one seller, in one currency. It gathers the earnings that seller has accrued and not yet been paid for, states the total, and names exactly which earnings it covers.
-## Transfers — the ledger
+A payout is a record of a settlement rather than the settlement itself. Where your marketplace is set to **Your own books**, creating a payout moves no money: you send the payment through your bank and then mark the payout as paid. Where a payment provider such as Stripe Connect is connected, the provider sends the money and the record follows it.
-Every time a seller ships an order, an **earning** is recorded: their share of the sale, less [commission](/user/sellers/commission-rates), in the sale's currency. If a refund is later issued on that order, a **refund reversal** takes the corresponding amount back off. **Sellers → Transfers** lists them all, and each links to the order that produced it.
+Payouts are the second half of the seller ledger. The first half is seller transfers, which credit a seller as each of their orders is fulfilled. A payout gathers those credits and settles them. See [<u>Seller Transfers</u>](/user/sellers/transfers).
-A seller's page sums this into a **Balance** card:
+To review payouts, navigate to **Sellers → Payouts** in the admin dashboard.
-| Figure | Meaning |
+## Reviewing Your Payouts
+
+![The Payouts list, with one pending payout](/docs/images/user/sellers/payouts/1-payouts-list.png)
+
+The list shows one row per payout.
+
+| Column | What it means |
|---|---|
-| Earned | Everything recorded in their favour |
-| Pending | Earned, not yet included in a payout |
-| Owed | Ready to pay |
-| Paid | Already paid out |
+| **Date** | When the payout was created. |
+| **Sellers** | Which seller it settles. |
+| **Status** | Where the payout has got to, described below. |
+| **Earnings** | How many transfers it covers, as a count rather than an amount. |
+| **Reference** | The reference recorded when it was marked as paid. |
+| **Amount** | What the payout comes to. |
+
+Filters narrow the list by date, seller and status. The search box matches on the reference rather than on seller names.
+
+### Payout Statuses
+
+What a status means depends on the **Paid through** setting under [<u>Marketplace Settings</u>](/user/settings/marketplace).
-## Payouts — settlements
+Where that is set to **Your own books**, a payout is created as **Pending** and stays there until you mark it as paid, at which point it becomes **Completed**. No other status occurs, because nothing is being attempted on your behalf.
-On schedule, a seller's pending earnings are batched into a **payout**. **Sellers → Payouts** lists them with their status, and each payout itemises the earnings it covers.
+Where a payment provider is connected, the provider moves the money and reports back, and a payout can also reach the following:
-| Status | Meaning |
+| Status | What it means |
|---|---|
-| Pending | Batched, not yet sent |
-| Processing | Handed to the payout provider |
-| Completed | Paid |
-| Failed | The provider refused it |
-| Unresolved | The provider's answer was lost — needs a person to check |
+| **Pending** | Created and not yet confirmed. |
+| **Processing** | An attempt is under way. |
+| **Completed** | The money reached the seller. |
+| **Failed** | The provider refused it. The earnings it held are released, and the next settlement picks them up. |
+| **Needs checking** | The provider could not say whether the money moved. The earnings stay attached to this payout so nothing sends them again, and it waits for somebody to establish what happened. |
+
+## How Payouts Are Created
+
+Payouts are created by a sweep that runs once a day and looks at every approved seller in turn. A seller is settled when both of the following hold.
+
+**Their schedule is due.** The schedule is set under [<u>Marketplace Settings</u>](/user/settings/marketplace) as daily, weekly, every two weeks, monthly, or only when you say so. A seller carrying their own **Payout schedule** on their seller page follows that instead. Being due is measured from the seller's last payout in that currency, so a seller who has never been paid in a currency is settled as soon as they are owed anything rather than waiting out a full period. A seller whose schedule is set to manual is never settled by the sweep.
+
+**They are owed at least the minimum.** The **Minimum payout** is also set under Marketplace Settings, with a seller's own figure taking precedence. A balance below it is carried into the next period rather than being sent.
+
+One payout is created per currency. Nothing is converted, so a seller owed in two currencies receives two payouts rather than one combined figure.
+
+A payout gathers the seller's unsettled transfers oldest first, and every refund is included whatever else is. A payout can therefore cover a sale, a refund and a second sale, which is why its total can be lower than the sales inside it. The period shown on the payout runs from the oldest earning it covers to the moment it was created.
+
+<Note>Where a balance has gone negative, because refunds came to more than earnings, nothing is created and the shortfall is carried forward to be absorbed by what the seller earns next.</Note>
+
+### How to Settle a Seller Immediately
+
+![A seller's Balance card, showing what is owed](/docs/images/user/sellers/payouts/2-balance-card.png)
+
+**Settle now** gathers everything a seller is owed into a payout at once, without waiting for their schedule. This is how a seller on a manual schedule is paid by default.
+
+1. Navigate to **Sellers** and open the seller.
+2. On the **Balance** card, click **Settle now**.
+3. Read the confirmation and click **Settle now** again.
+
+One payout is created per currency, exactly as the sweep creates them. No money moves, and each payout waits to be marked as paid.
+
+<Note>The **Balance** card reads the same after settling. The amount stays under **Owed**, because owed counts what has been earned and not yet paid, and a payout that has not been marked as paid has not paid anything yet.</Note>
+
+## Reading a Payout
+
+![A payout, with the earnings it covers](/docs/images/user/sellers/payouts/3-payout-detail.png)
+
+Opening a payout from the list shows the amount, the status and the seller in the header, over the two cards below.
+
+**Covers N earnings** lists every transfer in the payout, with the date, the order it came from, whether it was a sale or a refund, and the amount. This is what a seller needs to reconcile a deposit against their own records.
+
+**Payout** carries the settlement itself:
+
+- **Amount** - What the payout comes to.
+- **Reference** - The reference recorded when it was marked as paid, or **Not provided** where none was given.
+- **Provider** - What settled it. A marketplace keeping its own books reads `Spree::PayoutProvider::System` here.
+- **Period** - From the oldest earning in the payout to the moment the payout was created.
+
+## How to Mark a Payout as Paid
+
+Marking a payout as paid records that the money reached the seller. It is what clears the amount from the seller's balance, moving it from **Owed** to **Paid out**, so it is done after the payment has been sent rather than before.
+
+This is the step a marketplace paying through **Your own books** works through on payout day. Where a payment provider is connected, the provider confirms its own settlements and this is needed only in the one case described under [<u>Payouts Through Stripe Connect</u>](#payouts-through-stripe-connect).
+
+![The row menu on the payouts list, with Mark as paid](/docs/images/user/sellers/payouts/4-row-menu.png)
+
+It can be done from either of two places. On the payouts list, open the menu at the end of a row and click **Mark as paid**. On a payout's own page, click **Mark as paid** in the header. Both open the same dialog.
+
+![The Mark as paid dialog, with its reference field](/docs/images/user/sellers/payouts/5-mark-as-paid.png)
+
+1. Send the payment to the seller through your bank.
+2. Open the payout, or the menu at the end of its row on the payouts list.
+3. Click **Mark as paid**.
+4. Enter the **Reference** the payment went out under, such as the bank reference, so it can be traced later. This is optional, and no two payouts can share one.
+5. Click **Mark as paid** in the dialog.
+
+The payout becomes **Completed** and the reference is shown against it. The seller's balance moves the amount from **Owed** to **Paid out**, and the seller sees the same change in their own panel.
+
+<Warning>Marking a payout as paid moves no money. It records a payment you made separately, so doing it before sending the money leaves the seller reading that they have been paid when they have not.</Warning>
+
+The action is offered on a payout that is **Pending**, **Processing** or **Needs checking**. A payout that is already **Completed** cannot be marked again, and a **Failed** one has already released its earnings to the next settlement.
+
+## Payouts Through Stripe Connect
+
+Where **Paid through** is set to **Stripe Connect**, the records on this page are written in the same way and the same schedule governs them. What changes is that the money moves on its own, and payouts are completed by Stripe rather than by you.
+
+Setting the provider up is covered in [<u>Stripe Connect for Marketplaces</u>](/integrations/payments/stripe-connect).
+
+### How the Money Reaches a Seller
+
+The money makes two separate moves rather than one.
+
+- **As each order is fulfilled**, the seller's earning is transferred from your Stripe account to that seller's connected account. The transfer is funded by the customer's own charge, so it settles when that charge settles and your marketplace does not have to front the money. This is the seller transfer described under [<u>Seller Transfers</u>](/user/sellers/transfers).
+- **When a payout is created**, Spree instructs that connected account to pay its balance out to the seller's bank. This is the payout.
+
+Connected accounts are set up so that Stripe runs no payout schedule of its own. The **Settle sellers** interval under [<u>Marketplace Settings</u>](/user/settings/marketplace) is therefore the only schedule in effect, exactly as it is without a provider.
+
+### Payouts Complete on Their Own
+
+A payout created against Stripe Connect holds Stripe's own payout identifier as its **Reference** from the moment it is created, and stays **Pending** until Stripe reports what happened to it.
+
+- When the money reaches the seller's bank, the payout becomes **Completed** and the seller's balance moves from **Owed** to **Paid out**. Nobody marks it.
+- When Stripe cannot send it, the payout becomes **Failed** and the earnings it held are released, so the next settlement picks them up and sends them again.
-## The schedule
+A bank can return a payout days after paying it, so a payout that has already completed can still be reported as failed later. The earnings are released in that case too, which keeps a seller's balance correct rather than reporting them settled while Stripe still holds the money.
-Under **Settings → Marketplace** you set the defaults:
+<Note>These confirmations arrive on a second Stripe webhook endpoint, separate from the one carrying your customers' payments. Spree registers it when the Stripe payment method is saved. See [<u>Stripe Connect for Marketplaces</u>](/integrations/payments/stripe-connect).</Note>
-- **Schedule** — daily, weekly, every two weeks, monthly, or manual.
-- **Minimum payout amount** — earnings below it roll into the next payout rather than paying out a trivial sum.
+### When You Still Mark a Payout as Paid
-A seller can have their own schedule and minimum, set on their page under **Payouts and tax**; leave them blank to inherit the defaults.
+One case remains. Where Stripe's answer to a request was lost rather than refused, the payout is left at **Needs checking**, because nobody can tell whether the money moved and sending it again would risk paying twice.
-## How the money moves
+Check that payout against your Stripe dashboard. Where the money went out, mark it as paid with the Stripe payout identifier as the reference, which completes it in the same way the confirmation would have.
-**Settings → Marketplace** also chooses the **payout provider** — the thing that actually sends money.
+### What a Seller Needs First
-<Tabs>
- <Tab title="Built-in (pay by hand)">
- The default. Spree keeps the books and moves no money: earnings accrue, batch into payouts on schedule, and each payout waits in your queue as **Pending**. You pay it by bank transfer from your own bank, then open the payout and mark it **paid**, recording the reference it went out under.
+A seller is only credited once they hold a connected Stripe account, which they set up themselves from the **Payout account** row on their onboarding checklist. Until then their earnings are recorded and held at **Pending**, and are sent once their account can receive them. See [<u>Onboarding</u>](/user/sellers/onboarding).
- Right for a marketplace starting out, or one that settles by invoice.
- </Tab>
- <Tab title="Stripe Connect">
- Each seller connects a Stripe account — the **payout account** onboarding requirement asks them to, and the seller panel walks them through it. You charge the customer on your own Stripe account; as each seller's goods ship, their share is transferred to their connected account, tied to the charge that funds it so it moves as soon as that charge settles rather than out of your balance.
+### Why a Payout Can Be Smaller Than the Balance
- When a refund is issued after the seller was paid, the seller's share is taken back from their Stripe account automatically.
+A seller's earning is credited when their order is fulfilled, but the money behind it only reaches their connected account once the customer's charge settles with Stripe. Those are not the same moment.
- From there, Stripe pays the seller's bank on the schedule set for their account. Spree records what Stripe is going to do, and a webhook confirms when it did — which is when the payout turns **Completed**.
+Before creating a payout, Spree asks Stripe what the seller's account can actually send, and settles only that much, taking the oldest earnings first. Anything left over stays owed and goes out in the next settlement. Where Stripe cannot be reached for that figure, no payout is created for that seller in that period, and the balance carries forward intact.
- Requires an active Stripe payment method under Settings → Payments. Setup is on the [Stripe Connect](/integrations/payments/stripe-connect) page.
- </Tab>
-</Tabs>
+### Refunds
-<Note>
-Reconciliation against Stripe statements and seller tax reports are part of Spree Enterprise.
-</Note>
+A refund writes its reversal against the seller's ledger in the usual way, so balances and payouts stay correct from then on. The Stripe transfer behind the original earning is not pulled back, and a balance driven negative by refunds is absorbed by what the seller earns next rather than being recovered from them directly.
-## Related
+## Further Reading
-- [Commission rates](/user/sellers/commission-rates) — what is deducted before an earning is recorded
-- [Marketplace orders](/user/sellers/orders) — the payment splits earnings are computed from
-- [Onboarding](/user/sellers/onboarding) — the payout account requirement
+- [<u>Seller Transfers</u>](/user/sellers/transfers) - The earnings a payout gathers up
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - The payout schedule, provider and minimum
+- [<u>Sellers</u>](/user/sellers/sellers) - The seller pages carrying the Balance card
+- [<u>Commission Rates</u>](/user/sellers/commission-rates) - What is deducted before a seller earns
diff --git a/docs/user/sellers/products.mdx b/docs/user/sellers/products.mdx
index 6b583f9e73..e0fa92c022 100644
--- a/docs/user/sellers/products.mdx
+++ b/docs/user/sellers/products.mdx
@@ -1,36 +1,130 @@
---
title: "Seller Products"
-description: "Sellers list their own products and submit them; you review each one before it goes on sale."
+description: "Learn how products listed by your sellers are reviewed, approved and put on sale."
---
-A product can belong to a seller. If it does, the seller created it in their panel and maintains it there. If it does not, it is the marketplace's own stock.
+A seller product is a product listed by one of your sellers rather than by your own team. The seller writes it, prices it and holds the stock, and it appears in your products list alongside your own with the seller named against it.
-Sellers do not publish. They **submit**, and you decide.
+Three things set it apart from one of your own listings. It cannot go on sale until you have reviewed it, because what the marketplace lists is what the marketplace vouches for. It can only be merchandised into categories and collections by your team. And when it sells, the seller fulfills the order from their own stock and is paid for it, less the commission you charge.
-## The review queue
+To find what your sellers have listed, navigate to **Products** in the admin dashboard. The **Seller** column is shown by default and names the seller behind each row, with a dash where the product is your own.
-A product a seller has submitted arrives with the status **Proposed**. Filter the Products list by that status to see everything waiting.
+## What Puts a Seller's Product on Sale
-Open one and you have two choices:
+Three separate things all have to be true before a shopper can buy a product one of your sellers listed.
-- **Approve** — it goes on sale as soon as you do.
-- **Send back** — it returns to the seller as a draft, with a reason they will see. They can fix it and submit again.
+1. **The seller is approved.** A seller still working through onboarding, or one who has been rejected or suspended, has nothing on sale whatever their products say. A seller in holiday mode keeps their listings visible but unbuyable until the date passes. See [<u>Sellers</u>](/user/sellers/sellers).
+2. **The product is approved.** The seller submits it and you approve it, which sets its status to **Active**.
+3. **The product is listed on a sales channel.** This is a separate step from approving, described below.
-The product page shows who decided, and when.
+Any one of the three left undone leaves a product that reads as fine on both sides and cannot be bought.
-Stores that trust their sellers can have submissions approved automatically — ask your developers to switch it on.
+## What Makes a Seller Product Different
-## What sellers manage themselves
+A seller product is an ordinary product with a seller attached to it. From the admin dashboard your team can edit all of it exactly as you would one of your own listings, down to the price and the stock count. The one thing that cannot be changed is which seller it belongs to.
-From their panel, a seller looks after everything about how their products reach the customer:
+What differs is the seller's side. Their panel reaches part of the listing and not the rest.
-- **Stock locations** — where they ship from. Stock for their products lives there.
-- **Delivery methods** — their own shipping options, with their own rates, alongside any shared marketplace ones.
-- **Package types** — the boxes and cartons they ship in, which their delivery quotes are built on.
+| | |
+|---|---|
+| **The seller maintains** | The name, description and media, the prices and stock, the variants and their options, the SKU, the slug and the search engine listing. They also pick the product type and the delivery profile, from your marketplace's own lists. |
+| **Only your team can set** | The categories, collections and tags the product is filed under, the tax category, and which sales channels carry it. |
-Delivery profiles and zones stay yours; a seller assigns a profile to each product rather than defining them.
+Being able to edit a seller's listing is not the same as it being yours to maintain. The seller holds the stock and sets their own prices, so corrections to either should normally come from them, and editing a seller's product is usually reserved for corrections rather than fully managing their catalog.
-## Related
+Filing is the marketplace's side of the bargain. Tags in particular belong to the whole marketplace rather than to one product, so a seller adding one would be writing into shared vocabulary. The product type and the delivery profile are theirs to pick because the type is what hands their product its options, and the profile is what decides how their goods can be shipped at all.
-- [Products](/user/products/adding-products) — the product editor, which is the same for a seller's products
-- [Managing sellers](/user/sellers/managing-sellers) — the seller behind the product
+### Product Statuses
+
+A product carries one of five statuses. The seller panel and the admin dashboard do not always name them the same way, and the two review statuses are read differently in the products list than on the product's own page.
+
+| What it means | The seller sees | You see |
+|---|---|---|
+| The seller is still working on it. | **Draft** | **Draft** |
+| Submitted and waiting on your decision. The seller can still make changes while it waits. | **In review** | **Proposed** |
+| You sent it back. The seller edits it and submits it again. | **Changes needed** | **Rejected** |
+| Approved, and on sale wherever it is listed, for as long as its seller is approved and not on holiday. | **Active** | **Active** |
+| Taken out of the seller's active listings and off sale. | **Archived** | **Archived** |
+
+A seller never sets a status directly. **Draft** and **Archived** they reach through their own actions, and the other three move only through submission and your decision.
+
+## How a Seller Submits a Product
+
+![A seller's products list in their own panel](/docs/images/user/sellers/products/1-seller-products-list.png)
+
+The form a seller fills in is the same one your team uses, so the fields themselves are covered in [<u>Adding Products</u>](/user/products/adding-products).
+
+Once the seller has finished the product and saved it, they press **Submit for review**, which is what passes it to you. Their copy then reads **In review**, and they can carry on editing it while it waits.
+
+![A seller's product waiting for review](/docs/images/user/sellers/products/2-seller-product-in-review.png)
+
+Only a product that is **Draft** or **Changes needed** can be submitted. An active listing is already on sale and an archived one has been taken down, so neither is submitted again without first being moved back to draft.
+
+Each submission is recorded in its own right, so a product sent back twice and resubmitted carries the full trail of who asked, who decided, and what they were told. Correcting a decision never overwrites the one before it.
+
+## How to Review a Submitted Product
+
+![A submitted product on the admin side, with its Seller, Status and Publishing cards](/docs/images/user/sellers/products/3-admin-product-in-review.png)
+
+A submitted product appears in your products list with the status **Proposed**. The **Status** column can be sorted to bring them together, and the **Seller** column filtered to one seller at a time.
+
+Opening one shows the seller's work in the main form and your decision on the cards beside it. The **Seller** card names the seller and carries their own status, which matters because a product from a suspended seller is not on sale whatever the product itself says.
+
+1. Navigate to **Products** and open the product.
+2. Read what the seller wrote, and check the price, the media and the stock.
+3. File the listing on the **Categorization** card, choosing its categories, collections and tags.
+4. Click **Approve** on the **Status** card and confirm, or click **Send back**.
+
+**Approve** sets the status to **Active** and closes the review.
+
+<Note>Switching on **Publish seller products automatically** under [<u>Marketplace Settings</u>](/user/settings/marketplace) approves a product the moment it is submitted, with nobody reviewing it. The approval is recorded as automatic rather than against anyone's name.</Note>
+
+### How to Send a Product Back
+
+Sending a product back returns it to the seller to work on, rather than turning it down for good.
+
+![A product that has been sent back, with the reason against it](/docs/images/user/sellers/products/4-sent-back.png)
+
+1. On the product's **Status** card, click **Send back**.
+2. Enter the reason, answering the question the box asks: what should the seller change.
+3. Click **Send back** again to confirm.
+
+The product reads **Rejected** in your products list and **Changes needed** on its own page. The seller sees **Changes needed** in their panel with your reason shown against the product, so they know what to fix before submitting it again.
+
+The reason is recorded against your decision rather than against the product itself, which means the seller cannot edit it away. **Send back** stays available on a product that has already been sent back, which is how a reason is corrected. Each one is recorded as its own decision in the product's review history rather than overwriting the last.
+
+## How to Publish an Approved Product
+
+Approving a product does not put it in front of shoppers. Until a sales channel carries it, the **Publishing** card reads **Not listed on any sales channel yet** and the product cannot be found or bought.
+
+![The Publishing card, with the product listed on a sales channel](/docs/images/user/sellers/products/5-publishing.png)
+
+1. On the product, find the **Publishing** card.
+2. Click **Manage**.
+3. Tick the sales channels the product should appear on.
+4. Click **Done**, then save the product.
+
+The card then names each channel the product is live on, and shoppers on those channels can buy it. Switching a channel off unlists the product there.
+
+<Warning>The seller's panel reports an approved product as **Active** whether or not a channel carries it, because the status describes your decision rather than where the product is listed. A seller can therefore believe they are selling before you have listed them anywhere.</Warning>
+
+## Stock and Fulfillment
+
+A seller's product is stocked at the seller's own location rather than yours, and the seller sets the count. When a shopper buys it, the order goes to that seller to fulfill and the stock comes off their location.
+
+This is why a seller has stock locations, delivery methods and package types of their own in their panel. The delivery options a shopper is offered at checkout come from the seller the product belongs to. See [<u>Onboarding</u>](/user/sellers/onboarding).
+
+## Importing and Exporting
+
+Sellers can export their products to a CSV file and import changes back from their own panel, covering their own products only. This is how a seller with a long range updates prices or stock without working through each product one at a time.
+
+A product the import creates arrives as a draft, exactly as one built by hand does, so a new listing never reaches shoppers without your decision. A row that updates a product already on sale is applied straight away, so an existing listing's price or description changes without coming back for review. The seller selects them in their list and uses the bulk **Submit for review** action to send the batch. See [<u>Import and Export</u>](/user/products/import-and-export) for the file itself.
+
+## Further Reading
+
+- [<u>Sellers</u>](/user/sellers/sellers) - The sellers themselves, and approving them
+- [<u>Onboarding</u>](/user/sellers/onboarding) - How a seller lists their first products
+- [<u>The Seller Panel</u>](/user/sellers/seller-panel) - What a seller sees when building a product
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - Reviewing products automatically
+- [<u>Products</u>](/user/products/products) - The products list, which holds your own and your sellers'
+- [<u>Sales Channels</u>](/user/settings/sales-channels) - The channels a product is listed on
diff --git a/docs/user/sellers/seller-panel.mdx b/docs/user/sellers/seller-panel.mdx
new file mode 100644
index 0000000000..7448525b8a
--- /dev/null
+++ b/docs/user/sellers/seller-panel.mdx
@@ -0,0 +1,116 @@
+---
+title: "Seller Panel"
+description: "Learn what a seller sees and can do in their own panel on your marketplace."
+---
+
+Every seller on your marketplace has a panel of their own. It is a separate sign-in from your admin dashboard, showing one seller their own products, orders and earnings, with no access to your dashboard and none to any other seller.
+
+Every seller uses it at least once, because the panel is where they accept their invitation and work through your onboarding checklist. In most circumstances that is not optional, though you can admit a seller before they have finished the checklist, which is covered in [<u>Sellers</u>](/user/sellers/sellers).
+
+What happens after approval varies. A seller whose whole business runs on your marketplace works in the panel every day, listing products and fulfilling orders from it. A seller already trading on their own platform, such as a Shopify store connected to your marketplace, may never open it again, because their products and orders flow between the two systems and they manage both from the dashboard they already use. For that seller the panel was the onboarding step and nothing more.
+
+Knowing what the panel holds is what lets you answer a seller who cannot find something, which is usually because the thing they are looking for belongs to your marketplace rather than to them.
+
+## Home Screen
+
+![The seller panel home screen](/docs/images/user/sellers/seller-panel/1-panel-home.png)
+
+Home is where a seller lands after signing in. It opens with their business name and answers one question, which is where they stand with your marketplace.
+
+Three figures sit across the top:
+
+- **Status** - Their seller status, in the same words you see on their record. See [<u>Sellers</u>](/user/sellers/sellers).
+- **Products** - How many products they have listed, counting drafts and products still in review.
+- **Team members** - How many people can sign in and run the seller.
+
+Below them, **Selling** states plainly whether their products are on sale or not yet.
+
+A seller who has not finished onboarding also gets a **Finish setting up** card above all of this, showing how much of your checklist is done, with a **Continue setup** button into it. That card disappears once the checklist is complete rather than sitting at full for good.
+
+<Note>**Selling** reports the seller's own standing rather than whether any shopper can actually buy from them. A seller reads that their products are on sale as soon as they are approved and not on holiday, even where none of their products has been listed on a sales channel. See [<u>Seller Products</u>](/user/sellers/products).</Note>
+
+Home carries no sales figures, order counts or balance. Each of those lives on its own screen.
+
+## What the Sidebar Holds
+
+The sidebar is the whole panel. It is deliberately short compared to the admin dashboard.
+
+| Screen | What the seller does there |
+|---|---|
+| **Home** | Reads their status, product count, team size and whether they are selling. |
+| **Setup** | Works through your onboarding checklist and submits for review. |
+| **Products** | Lists products, submits them for review, imports and exports. |
+| **Orders** | Reads the orders they received and fulfills them. |
+| **Earnings** | Reads what their sales earned, less your commission. |
+| **Payouts** | Reads what has been paid to them, and what is on its way. |
+| **Profile** | Writes their public profile and uploads their logo and cover photo. |
+| **Settings** | Manages stock locations, delivery methods, package types, policies and their team. |
+
+**Earnings** and **Payouts** are there because a seller needs to see their own money. Your dashboard has nothing like them for your own team, because the same question asked from your side covers every seller at once, which is what **Sellers → Seller transfers** and **Sellers → Payouts** answer.
+
+## Setup
+
+![The Setup checklist in the seller panel](/docs/images/user/sellers/seller-panel/2-setup-checklist.png)
+
+**Setup** is your onboarding checklist as the seller sees it, with their progress at the top and each requirement as a row they expand to work on. **Submit for review** stays unavailable until everything you marked as required is done.
+
+This screen is the one part of the panel every seller has to use. See [<u>Onboarding</u>](/user/sellers/onboarding).
+
+## Products
+
+A seller's product form is the same one your team uses, with the parts that belong to your marketplace left out. There is no sales channel control, no categories, collections or tags, and no tax category.
+
+A seller cannot put a product on sale. They save it, submit it for review, and wait for your decision. See [<u>Seller Products</u>](/user/sellers/products).
+
+## Orders
+
+![A fulfilled order in the seller panel, with the carrier and tracking number](/docs/images/user/sellers/seller-panel/3-fulfilled-order.png)
+
+A seller sees only the orders that are theirs. Where one shopper buys from two sellers in a single checkout, each seller sees their own part of it and neither sees the other's.
+
+The order screen carries what has to be shipped, the customer's delivery address, and a summary showing what the order came to and the marketplace fee charged on it. The seller fulfills from here, entering a tracking number and choosing whether the customer is notified. Returns and claims are raised and handled on the same screen. See [<u>Marketplace Orders</u>](/user/sellers/orders).
+
+## Earnings
+
+![The Earnings screen in the seller panel](/docs/images/user/sellers/seller-panel/4-earnings.png)
+
+**Earnings** is where a seller sees what their sales have made them. A balance card leads, carrying one position per currency, with **Owed to you** as the headline figure and three more beneath it:
+
+- **Earned** - Everything their sales have earned, net of anything refunded.
+- **Paid out** - How much of that has already reached them through a completed payout.
+- **On its way** - Earnings a payment provider has not confirmed yet, so a seller who has shipped does not read their own order as unpaid.
+
+Below the balance sits every earning line by line, with the date, the order it came from, whether it was a sale or a refund, its status and its amount.
+
+The screen is read-only. An earning is written when an order is fulfilled and corrected by a refund when one is given, so there is nothing on it for a seller to change. The figures are the same ones you read under **Sellers → Seller transfers**. See [<u>Seller Transfers</u>](/user/sellers/transfers).
+
+<Note>A seller never sees your commission rates. They see the fee charged on each of their own orders, which appears on the order itself, and the earning that fee was taken from.</Note>
+
+## Payouts
+
+![The Payouts screen in the seller panel](/docs/images/user/sellers/seller-panel/5-payouts.png)
+
+**Payouts** is the settlements themselves, rather than the sales behind them. Each row carries the date, the status, how many earnings it covers, the reference and the amount.
+
+The **Reference** is worth knowing about. Where you settle by bank transfer, it is the reference your team typed in when marking the payout as paid, which is what lets a seller match a payment against their own bank statement.
+
+This screen is read-only as well. Payouts are created on the schedule you set and completed by your team or by the payment provider, so there is nothing here for a seller to act on. See [<u>Payouts</u>](/user/sellers/payouts).
+
+## Profile and Settings
+
+**Profile** holds the public description, the logo and the cover photo shoppers see, along with the seller's business details and tax registrations.
+
+**Settings** holds what the seller runs their own fulfillment with, which is their stock locations, delivery methods and package types, plus their published policies and their team. See [<u>Onboarding</u>](/user/sellers/onboarding) for what each of those is for.
+
+**Team** is where a seller invites colleagues by email. Everyone on a seller's team has the same access, so a colleague brought in to help with packing can also change prices, read earnings and remove other members, including the person who invited them.
+
+<Warning>There are no roles within a seller team. Anyone a seller invites can do everything that seller can do.</Warning>
+
+## Further Reading
+
+- [<u>Onboarding</u>](/user/sellers/onboarding) - Inviting a seller and the checklist they work through
+- [<u>Seller Products</u>](/user/sellers/products) - Reviewing and listing what sellers submit
+- [<u>Marketplace Orders</u>](/user/sellers/orders) - How an order is split between sellers
+- [<u>Seller Transfers</u>](/user/sellers/transfers) - The ledger behind a seller's earnings
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling what a seller is owed
+- [<u>Sellers</u>](/user/sellers/sellers) - The seller records themselves
diff --git a/docs/user/sellers/sellers.mdx b/docs/user/sellers/sellers.mdx
index 571e269306..698b4f4930 100644
--- a/docs/user/sellers/sellers.mdx
+++ b/docs/user/sellers/sellers.mdx
@@ -1,40 +1,187 @@
---
title: "Sellers"
-description: "Run a marketplace — other businesses list on your store, ship their own orders, and get paid their share."
+description: "Learn how to add the third-party sellers trading on your marketplace, review where each one stands, and approve or suspend them."
---
-A seller is another business selling through your store. They list their own products, ship their own orders from their own locations, and are paid their share of each sale, less the commission you charge. Everything a seller does happens in their own **seller panel** — they never see your dashboard, other sellers, or anything belonging to the store at large.
+A seller is a third-party business trading on your marketplace. Each one lists its own products, fulfills its own orders and is paid for what it sells, less the commission you charge.
-A marketplace can sell its own stock too. A product with no seller is yours, so a store that is part shop, part marketplace is a normal setup.
+Every seller has a record holding everything about that business in one place: the people who run it, how much of your onboarding checklist it has completed, its contact and address details, and what it has earned and is owed. The sellers list gathers those records onto one screen, so every seller and its current state can be seen together.
-## What a seller owns
+Sellers maintain their own profile, catalog and orders from their own panel, so most of the work on this screen is deciding who may trade, correcting details on a seller's behalf, and setting the commercial terms that only the marketplace operator controls.
-| Theirs | Yours |
+To manage sellers, navigate to **Sellers** in the admin dashboard.
+
+## Reviewing Your Sellers
+
+![The Sellers list, showing each seller's status and onboarding progress](/docs/images/user/sellers/sellers/1-sellers-list.png)
+
+The list shows one row per seller.
+
+| Column | What it means |
|---|---|
-| Their products — listed by them, approved by you | The catalog as a whole, categories, collections, pricing rules |
-| Their stock locations, delivery methods and packaging | Delivery profiles and zones, which sellers pick from |
-| Their orders, fulfilled from their own locations | The customer, the payment, the order group that ties a checkout together |
-| Their team, their profile page, their policies | Commission rates, payouts, the onboarding checklist |
+| **Name** | What the business is called. |
+| **Status** | Where the seller stands with you, described below. |
+| **Contact email** | Where marketplace notices are sent, and the address an invitation is offered to by default. |
+| **Onboarding** | How much of your checklist they have completed, such as 3 of 7 done. |
+| **Products** | How many products the seller has, drafts and products in review included. |
+| **Team** | How many people can sign in and run the seller. |
+| **Created at** | When the seller record was added. |
+
+Which columns appear is yours to choose, so a marketplace that never looks at team size can hide that column and keep the list to what it reads every day. Filtering by **Status** is the quickest way to bring up everyone waiting on a decision from you.
+
+### Seller Statuses
+
+A status indicates the point a seller has reached between being created and trading. The status is never typed in or updated manually. It changes in response to what you and the seller each do, and it governs what the seller can do next as well as which actions are offered to you on their page.
+
+| Status | What it means |
+|---|---|
+| **Pending** | The record exists, but nobody has been invited to run it yet. |
+| **Invited** | An invitation has been sent and nobody has accepted it. |
+| **Canceled** | The seller withdrew before joining. |
+| **Onboarding** | Somebody has accepted the invitation and is working through the checklist. |
+| **Ready for review** | The checklist is finished and the seller is waiting on your decision. |
+| **Approved** | The seller can trade on your marketplace. |
+| **Rejected** | The seller was turned down and cannot trade. |
+| **Suspended** | An approved seller has been stopped from trading, and can be reinstated later. |
+
+## How to Add a Seller
+
+Adding a seller creates the record. Inviting the people who will run it, and approving them, both happen afterwards from the seller's own page.
+
+1. Click **Add seller**.
+2. Enter the business's **Name**.
+3. Enter a **Contact email**, which is where marketplace notices are sent.
+4. Click **Create seller**.
+
+The seller's page opens, with the status **Pending** and nothing on the checklist done.
+
+<Note>The contact email is not an invitation. Nobody can sign in to the seller account until somebody has been invited and has accepted, which is covered in [<u>Onboarding</u>](/user/sellers/onboarding).</Note>
+
+## Reading a Seller's Page
+
+![A seller's page, with its onboarding checklist and status](/docs/images/user/sellers/sellers/2-seller-page.png)
+
+The header shows the seller's name, its status, how much of the checklist has been completed, and the main action available at that point, which is **Invite** before the seller has accepted and **Approve** once they are ready for review. The rest of the seller data sits on cards below.
+
+- **Profile** - The cover photo, logo, name, storefront address and public description, which together are what a shopper sees.
+- **Onboarding** - Every requirement on your checklist with the state of each one, and a link to **Manage requirements**, which opens the checklist itself. See [<u>Seller Requirements</u>](/user/settings/seller-requirements).
+- **Team** - The people who can sign in and run this seller, and any invitations still outstanding.
+- **Status** - The current status with a sentence explaining it.
+- **At a glance** - How many products and team members the seller has, and when the record was created.
+- **Balance** - What the seller has earned, been paid and is owed. This card appears only once the seller has earned something. See [<u>Payouts</u>](/user/sellers/payouts).
+- **Contact** - The contact email and the billing email.
+- **Billing address** - Where the seller is invoiced for commission.
+- **Returns address** - Where customer returns are sent.
+- **Payouts and tax** - Who remits tax, and this seller's own payout schedule and minimum payout where they differ from your marketplace defaults.
+- **Custom fields** - Any extra fields your marketplace records against sellers. See [<u>Custom Fields</u>](/user/settings/custom-fields).
+
+Cards are not hidden when the seller has not filled them in yet. A card with no data simply shows blank fields, so you can see at a glance where a seller has got to without opening their checklist.
+
+## Editing a Seller's Details
+
+Almost everything on a seller's record belongs to the seller, who maintains it from their own panel. The same fields can be edited here on their behalf, which is what you need when a seller cannot correct something themselves, such as before anyone has accepted the invitation.
+
+Two things work differently. The payout and tax settings are yours alone, and the seller never sees them. The returns address is the seller's alone, and can be read here but changed only by them.
+
+### Seller Profile
+
+The edit button on the profile card, and the one on the **Contact** card, both open the same panel:
+
+- **Logo** - Shown beside the seller wherever they appear. A square image works best.
+- **Square logo** - Used where a tight square is needed, such as an avatar.
+- **Cover photo** - The wide banner across the top of the seller's profile.
+- **Name** - What the business is called.
+- **Slug** - The seller's address on your storefront.
+- **Contact email** - Where marketplace notices are sent, and the address an invitation is offered to by default.
+- **Billing email** - Where commission invoices are sent, when that differs from the contact email.
+- **About** - The public description shown on the seller's profile.
+
+The seller maintains all of these from their own panel except the slug, which only the marketplace operator can change. A seller renaming their own storefront address would break every link already pointing at it.
+
+### Payouts and Tax
+
+These are set from the **Payouts and tax** card and are not shown to the seller:
+
+- **Tax remittance** - Whether the seller or the marketplace remits consumer tax on that seller's sales.
+- **Payout schedule** - How often this seller is paid, or **Use store default** to follow your marketplace setting.
+- **Minimum payout** - How much has to build up before this seller is paid.
+- **Holiday mode until** - A date the seller is away until. Their products stay visible on your storefront but cannot be bought until that date passes, so the seller keeps their listings and their search ranking instead of taking everything down and putting it back.
+
+The defaults these fall back on are under [<u>Marketplace Settings</u>](/user/settings/marketplace). Setting a value here applies to this seller only.
+
+### Addresses
+
+The **Billing address** is edited from its own card, and is the address a commission invoice is made out to.
+
+The **Returns address** is read-only on this screen. It comes from the seller's default stock location, so it changes when the seller changes the address on that location in their own panel.
+
+### Custom Fields
+
+![A seller's Custom fields card](/docs/images/user/sellers/sellers/3-custom-fields.png)
+
+Any custom fields your marketplace records against sellers are shown and edited on the **Custom fields** card. A field the seller was asked to fill in on their checklist shows their answer here, which is where you read what they told you, and a field only your own team uses is filled in here. See [<u>Custom Fields</u>](/user/settings/custom-fields) for creating the fields themselves, and [<u>Seller Requirements</u>](/user/settings/seller-requirements) for asking a seller to complete one.
+
+### Team
+
+The **Team** card lists everyone who can sign in and run this seller, together with invitations that have been sent and not yet accepted. Four things can be done from it:
+
+- **Invite** adds somebody to the seller's team. They join when they accept.
+- **Resend** sends an outstanding invitation again.
+- **Revoke** stops an outstanding invitation working.
+- **Remove** takes a team member's access to the seller away.
+
+Inviting the first person is what starts a seller's onboarding, which is covered in [<u>Onboarding</u>](/user/sellers/onboarding).
+
+### What Cannot Be Edited Directly
+
+A seller's **status** is never typed in or picked from a list. It moves only through the actions below, each of which sends the right notification, provisions what the new status needs and records who decided it.
+
+**Products cannot be created for a seller.** A product belongs to whoever submitted it, and there is no way to add one on a seller's behalf or to move one of your own products over to them. Reviewing, approving and listing what a seller submits is the extent of it. See [<u>Seller Products</u>](/user/sellers/products).
+
+**A payout account cannot be swapped by you.** Where your marketplace pays through Stripe Connect, the account a seller is paid into is the one that seller connected, and a seller who needs to be paid somewhere else has to connect the new account themselves. See [<u>Payouts</u>](/user/sellers/payouts).
+
+**Delivery methods cannot be added for a seller.** The methods a seller has set up can be read and edited under [<u>Delivery Profiles</u>](/user/settings/delivery-profiles), but a new one cannot be created on their behalf. A seller needing another way to ship adds it from their own panel. The alternative is a delivery method of your own shared with sellers, which reaches every seller at once rather than one.
+
+## How to Approve a Seller
+
+Approving lets a seller trade. The **Approve** button appears in the header once somebody has accepted an invitation and the seller is working through the checklist.
+
+1. Open the seller and read the **Onboarding** card.
+2. Settle anything waiting on you, such as a document to read or a manual check to mark done.
+3. Click **Approve**.
+
+A seller who has finished the checklist is approved straight away. A seller who has not finished brings up a confirmation naming the requirements still outstanding, and approving from there admits them regardless. The decision is recorded along with what was outstanding at the time.
+
+![The confirmation shown when approving a seller whose checklist is unfinished](/docs/images/user/sellers/sellers/4-approve-anyway.png)
+
+<Note>Where **Approve sellers automatically** is switched on under [<u>Marketplace Settings</u>](/user/settings/marketplace), a seller is approved as soon as they submit a finished checklist for review, and never waits on you.</Note>
+
+## How to Reject or Send Back a Seller
+
+![The More actions menu on a seller's page](/docs/images/user/sellers/sellers/5-more-actions.png)
+
+Both decisions are made from **More actions** on the seller's page, and both apply before a seller has been approved.
+
+**Reject** turns down an applicant. The seller is not admitted and cannot trade. A rejection is not final, because the **Approve** button is still offered on a rejected seller if the decision needs reversing.
+
+**Send back to onboarding** is offered on a seller who is waiting for review. It returns them to the checklist so they can correct their details and ask for review again, rather than deciding either way.
+
+## How to Suspend or Reinstate a Seller
-## Where things live
+**Suspend** is found under **More actions** on an approved seller. Suspending stops them selling immediately while keeping their catalog, their order history and everything they have earned, so money already owed can still be settled.
-Sellers has its own section of the dashboard, and two settings pages beside it:
+A suspended seller is reinstated with the **Reinstate** button in the header, which returns them to approved and lets them trade again.
-- **Sellers** — every seller, their status, and their page: [Managing sellers](/user/sellers/managing-sellers)
-- **Commission rates** — what you charge on each sale: [Commission rates](/user/sellers/commission-rates)
-- **Transfers** and **Payouts** — what each seller has earned and been paid: [Payouts](/user/sellers/payouts)
-- **Settings → Seller requirements** — the checklist a seller completes before you approve them: [Onboarding](/user/sellers/onboarding)
-- **Settings → Marketplace** — how and when sellers are paid
+## How to Delete a Seller
-## The shape of a marketplace sale
+**Delete seller** removes the record entirely and cannot be undone. Products the seller listed stay in your catalog without a seller attached.
-1. A seller [lists a product](/user/sellers/products) and you approve it.
-2. A customer buys it — possibly alongside products from other sellers — in one checkout. Spree splits that into [one order per seller](/user/sellers/orders), under one order group, paid once.
-3. The seller ships their order from their panel.
-4. Shipping records what they earned, less [commission](/user/sellers/commission-rates), on their ledger.
-5. On schedule, those earnings settle into a [payout](/user/sellers/payouts).
+<Warning>Deleting is not the way to stop a seller trading. Suspending keeps the record, its orders and its earnings, which is what lets you settle what is already owed and reinstate the seller later. Delete only a record that should never have existed.</Warning>
-## Related
+## Further Reading
-- [Onboarding](/user/sellers/onboarding) — inviting a seller and the checklist they complete
-- [Managing sellers](/user/sellers/managing-sellers) — the list, statuses, and a seller's page
+- [<u>Onboarding</u>](/user/sellers/onboarding) - Inviting a seller and getting them through the checklist
+- [<u>Seller Requirements</u>](/user/settings/seller-requirements) - The checklist itself
+- [<u>The Seller Panel</u>](/user/sellers/seller-panel) - What a seller sees and does on their side
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - Payouts, admission and commission tax
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling what a seller is owed
diff --git a/docs/user/sellers/transfers.mdx b/docs/user/sellers/transfers.mdx
new file mode 100644
index 0000000000..28e437b644
--- /dev/null
+++ b/docs/user/sellers/transfers.mdx
@@ -0,0 +1,117 @@
+---
+title: "Seller Transfers"
+description: "Learn how to read the ledger of what each fulfilled order earned its seller, less your commission."
+---
+
+A seller transfer is a record of what one order earned one seller. A transfer is created when an order is fulfilled, with the value amounting to the order total minus the marketplace commission. Refunds are recorded as separate transfers, carrying a negative value that cancels part or all of the original.
+
+The ledger is the record behind every balance on your marketplace. A seller's balance, the amount a payout settles and what a seller sees on their own earnings screen are all built from these lines, so this is where a figure that looks wrong is checked.
+
+Existing transfers are never edited. Every correction is recorded as an additional transfer, so a seller's total is always the sum of their rows and the full history remains available.
+
+To review them, navigate to **Sellers → Seller transfers** in the admin dashboard.
+
+## Reviewing Seller Transfers
+
+![The Seller transfers list, with a sale and a refund](/docs/images/user/sellers/transfers/1-transfers-list.png)
+
+The list shows one row per transfer.
+
+| Column | What it means |
+|---|---|
+| **Date** | When the transfer was created. |
+| **Sellers** | Which seller earned or repaid it. |
+| **Order** | The order it came from. |
+| **Type** | **Sale** for an earning, **Refund** for one taken back. |
+| **Status** | Where the transfer has got to, described below. |
+| **Amount** | What the seller earned, or a negative figure where it was taken back. |
+
+Filters narrow the list by date, seller, type and status, which is how a single seller's history over a period is read.
+
+### Transfer Statuses
+
+What a status means depends on how your marketplace pays its sellers, which is set under [<u>Marketplace Settings</u>](/user/settings/marketplace).
+
+Where no payment provider is connected, Spree records what each seller is owed and you send the money yourself by bank transfer. Nothing is being attempted on your behalf, so every transfer is marked **Completed** the moment it is created and no other status appears on the list.
+
+Where a provider such as Stripe Connect is connected, the provider moves the money and reports back, and a transfer passes through the following:
+
+| Status | What it means |
+|---|---|
+| **Pending** | Recorded and not yet sent to the provider. |
+| **Processing** | An attempt failed and will be made again. |
+| **Completed** | The provider confirmed it. |
+| **Failed** | The provider refused it. |
+| **Needs checking** | The provider could not say whether the money moved. Nothing will retry it until somebody establishes what happened against the provider's own records. |
+
+<Note>A transfer records what a seller is owed rather than money moving. Even with a provider connected, a transfer is one half of the ledger: the money reaches the seller through a payout, which is a separate record. See [<u>Payouts</u>](/user/sellers/payouts).</Note>
+
+## When a Transfer Is Created
+
+A transfer is created when a seller order is **fully fulfilled**, not when it is placed or paid. Every item has to have gone out, so an order with one parcel still outstanding earns nothing yet, and an order sitting unfulfilled shows a commission on its own page while having earned the seller nothing.
+
+How the customer paid makes no difference. An order settled with store credit or a gift card produces the same transfer a card payment would, because how the sale was funded is a matter for your marketplace rather than for the seller.
+
+An order sold by your own team rather than by a seller has no seller against it, so no transfer is created for it.
+
+<Note>Where a payment provider is connected, a seller whose account with that provider is not ready yet is still credited. The transfer is recorded and held at **Pending** until their account can receive the money, and is sent once it can.</Note>
+
+## What a Seller Earns
+
+A transfer is the order total, less the consumer tax where your marketplace remits it, less the commission charged on the order including the tax on that commission. It can never be less than zero.
+
+Taking an order of $120.00 on a marketplace charging 10%, where the seller remits their own tax:
+
+| | |
+|---|---|
+| Order total | $120.00 |
+| Commission at 10% of the seller's net revenue | $10.00 |
+| Tax on that commission at 20% | $2.00 |
+| **The seller earns** | **$108.00** |
+
+Where the seller's **Tax remitted by** is set to the marketplace rather than to the seller, the consumer tax on the order comes off as well, because the marketplace files it and the seller never holds it. That setting is on the seller's own page under [<u>Sellers</u>](/user/sellers/sellers).
+
+The commission subtracted is the exact amount recorded against the order at the moment it was placed. Spree does not look up the commission rate again and recalculate the fee when the transfer is created.
+
+This matters because the recorded fee and the current rate can disagree. The rate may have been edited since the order was placed, the fee may have been limited by a floor or a cap, or a flat fee may have been charged per unit rather than as a share of the total. In each of those cases, applying today's rate to the order total would produce a different number from the one the seller was actually charged. See [<u>Commission Rates</u>](/user/sellers/commission-rates).
+
+## Refunds
+
+Refunding a seller order writes a second transfer against the same order, as a negative figure, rather than editing the first one.
+
+The amount taken back is the **seller's share** of what was refunded, not the whole of it. A refund is the customer's gross figure and carries both the consumer tax and your commission, while the seller only ever received their net cut, so clawing back the gross would charge them commission on goods that came back. On the $120.00 order above, refunding the customer in full takes $108.00 back from the seller.
+
+How that share is worked out depends on what the refund can say about itself:
+
+- **A return or a claim** names the lines it paid for, so the share is what those lines actually earned, scaled to the amount refunded. A restocking fee or a goodwill payment on top is absorbed by that scaling.
+- **A manual refund or a cancellation** is only an amount against an order, so the order's own ratio of earnings to total is used instead.
+
+A reversal can never take back more than is left of the earning, so several refunds against one order cannot between them claw back more than the seller was paid.
+
+<Note>Refunding an order before it is fulfilled reverses nothing, because the seller has not been credited for it yet. Where such an order is fulfilled afterwards, the seller is credited the full earning and the earlier refund is not taken off it.</Note>
+
+Where the earning has already been settled in a closed payout, the reversal lands in the next period instead. A settlement that has happened is never rewritten.
+
+## How a Seller's Balance Is Built
+
+![The Balance card on a seller's page](/docs/images/user/sellers/transfers/2-balance-card.png)
+
+A seller's page carries a **Balance** card once they have earned anything, and every figure on it comes from this ledger.
+
+| Figure | What it counts |
+|---|---|
+| **Owed** | What has been earned and not yet paid. This is the figure a payout can send. |
+| **Earned** | Every completed transfer added together, refunds included, so it is net of what has been given back. |
+| **Paid out** | Completed transfers sitting inside a completed payout. |
+| **On its way** | Transfers that have not completed yet, whether still to be sent, being retried, or waiting on a provider that could not report an outcome. |
+
+**On its way** counts transfers rather than payouts, so a seller whose balance has been swept into a payout that has not been marked paid reads zero here, with the amount showing under **Owed** until the payout is marked paid.
+
+Nothing is converted between currencies. A seller trading in two currencies holds two positions on the card rather than one total, and where their account settles in a currency other than the one they sold in, the card shows both what the sales were worth and what the account received.
+
+## Further Reading
+
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling these earnings and recording them as paid
+- [<u>Commission Rates</u>](/user/sellers/commission-rates) - What is deducted before a transfer is created
+- [<u>Marketplace Orders</u>](/user/sellers/orders) - The orders these transfers come from
+- [<u>Sellers</u>](/user/sellers/sellers) - The seller pages carrying the balance card
diff --git a/docs/user/settings/marketplace.mdx b/docs/user/settings/marketplace.mdx
index b9687ce9f8..02a1b0c489 100644
--- a/docs/user/settings/marketplace.mdx
+++ b/docs/user/settings/marketplace.mdx
@@ -1,62 +1,103 @@
---
-title: "Marketplace"
-description: "Who pays your sellers and how often, whether new sellers and their products are reviewed, and the tax on your commission."
+title: "Marketplace Settings"
+description: "Learn how to set how your marketplace pays its sellers, how sellers join it, and the tax on your commission."
---
-The Marketplace settings screen holds the decisions that shape how your marketplace runs: **who gets to trade, what goes on sale, what sellers hear from you, and how they get paid.**
+Marketplace settings are the rules that apply to every seller on your marketplace. They decide how sellers are paid, whether an admin needs to review sellers before they can trade, what files sellers may attach to their products, whether sellers receive emails from your store, and what tax is charged on your commission.
-To reach it, navigate to **Settings → Marketplace**.
+These settings are the defaults for the whole marketplace. An individual seller can carry their own payout schedule and their own minimum payout, set on that seller's page, and those will override the settings here for that seller alone.
-## What's on the screen
+To manage them, navigate to **Settings → Marketplace** in the admin dashboard.
-### Payouts
+<Note>The page holds one **Save** for everything on it, rather than one per section. Changing any field brings up **Discard** beside it, which returns every field to the values it was last saved with.</Note>
-| Setting | What it does |
-|---|---|
-| **Payout provider** | Who actually moves the money. Leave it unset and Spree keeps the books while you pay sellers yourself. |
-| **Settle sellers** | How often earnings are swept into a payout — daily, weekly, every two weeks, monthly, or only by hand. A seller can carry their own schedule, which wins. |
-| **Minimum payout** | What a seller's balance must reach before it is worth sending. Below it, the balance carries to the next period. |
+## Payouts
-### Seller admission
+![The Payouts section, with the provider, schedule and minimum payout](/docs/images/user/settings/marketplace/1-payouts.png)
-| Setting | What it does |
-|---|---|
-| **Approve sellers automatically** | Let a seller start trading the moment they finish the onboarding checklist, with nobody reviewing them. |
-| **Approve seller products automatically** | Put a seller's product on sale as soon as they submit it, without review. |
+How and when the marketplace pays its sellers.
-Both are off by default. What your marketplace lists is what it vouches for, so admitting sellers and listing their products are decisions worth making on purpose. Turn them on for an invite-only marketplace where you already know your sellers; leave them off for an open one.
+- **Paid through** - Who moves the money. **Your own books** means you send each payout yourself and record it as paid in the dashboard. **Stripe Connect** means the provider pays sellers, and each seller has to set up their own account with it before they can be paid.
+- **Settle sellers** - How often earnings are gathered into a payment: daily, weekly, every two weeks, monthly, or only when you say so. The default is monthly.
+- **Minimum payout** - The smallest balance worth sending. A seller owed less than this carries their balance into the next period instead. Zero pays whatever is owed.
-### Communication
+**Your own books** suits a marketplace with only a handful of sellers that you already pay by bank transfer, where you would rather keep the payments in your own accounting system than add a provider. It costs nothing per transfer, and the trade-off is that somebody has to make each payment manually and record it. **Stripe Connect** is more suitable for marketplaces with large numbers of sellers, where paying them all manually would be too time-consuming and costly.
-| Setting | What it does |
-|---|---|
-| **Send sellers transactional emails** | Whether Spree emails sellers about invitations, approvals and payouts. Turn it off if you send seller communications yourself. |
+The settlement schedule is a choice between the seller's cash flow and your own effort. **Daily** or **Weekly** suits a marketplace whose sellers are small businesses depending on the money arriving, particularly where you pay through a provider and each payment costs you nothing to make. **Monthly** suits fewer, larger payments and less reconciliation. **Only when you say so** suits a new marketplace where you want to look at every settlement before it goes out, or when a dedicated finance team pays on its own cycle.
-### Commission tax
+The minimum payout exists to avoid paying unnecessary transfer fees on lots of small payments. A balance below it rolls forward to the next period instead, so a seller is paid once the amount is worth sending. Leave it at zero where transfers cost you nothing.
-| Setting | What it does |
-|---|---|
-| **Default commission tax rate** | The tax charged on your commission when nothing more specific applies. Entered as a percentage. |
+<Note>Both the schedule and the minimum are defaults for the marketplace. An individual seller can carry their own, set on that seller's page, which suits a large seller you have agreed different terms with.</Note>
-This is tax on **your service to the seller**, not on the goods the shopper bought — a separate supply, assessed against the seller's billing address.
+<Note>**Stripe Connect** is offered only once your store already has Stripe set up as a payment method, because the account that charges your customers is the one that pays your sellers. Each seller then connects their own account as part of their checklist, and a seller without one cannot be paid. See [<u>Payment Methods</u>](/user/settings/payments).</Note>
-It is only a fallback. A commission rate carrying its own tax rate wins, and so does a connected tax service. Set it for the case where neither has an answer, so commission is never left untaxed by omission.
+## Seller Admission
-## How to set your payout terms
+![The Seller admission section, with both review switches](/docs/images/user/settings/marketplace/2-seller-admission.png)
-1. Go to **Settings → Marketplace**.
-2. Choose **Paid through**. On **Your own books**, Spree tracks what each seller is owed and you send the transfers yourself, marking each one paid.
-3. Choose how often to **Settle sellers**. Pick **Only when you say so** if you would rather run each payout by hand.
-4. Set a **Minimum payout**, or leave it at zero to pay whatever is owed each period.
-5. Click **Save**.
+Whether a person reviews a seller, or a seller's product, before either goes live.
-## Good to know
+- **Approve sellers automatically** - A seller starts trading the moment they finish their checklist, with nobody reviewing them.
+- **Publish seller products automatically** - A seller's product goes on sale the moment they submit it, with nobody reviewing it.
-- A seller can carry their own settlement schedule, which overrides the store-wide setting for that seller.
-- Setting a minimum does not cancel a small balance — it carries forward to the next period.
+Both switches are usually left off, which is what makes your seller requirements checklist a real gate rather than a formality. With both of them switched off, a seller finishing the checklist waits for your review, and each product they submit needs your approval before being published.
-## Related
+Turning **Approve sellers automatically** on suits an invite-only marketplace, where you have already decided who each seller is before sending the invitation and the checklist is there to collect their details rather than to vet them. It makes less sense where anyone can apply, because the checklist is then the only thing standing between an applicant and your storefront.
-- [<u>Sellers → Payouts</u>](/user/sellers/payouts)
-- [<u>Sellers → Commission Rates</u>](/user/sellers/commission-rates)
-- [<u>Settings → Seller Requirements</u>](/user/settings/seller-requirements)
+Turning **Publish seller products automatically** on suits established sellers listing a high volume of products, where reviewing each one would be a significant bottleneck. The risk is different from the one above: an unreviewed seller can be suspended before they sell anything, while an unreviewed product is on your storefront under your name the moment it is submitted.
+
+<Warning>Each switch removes a human decision. A workable middle setting on a growing marketplace is to review sellers but not their products, so you still choose who trades while a seller you have already approved can list freely.</Warning>
+
+## Seller Files
+
+![The Seller files section](/docs/images/user/settings/marketplace/3-seller-files.png)
+
+Whether sellers may attach downloadable files to their own products, which kinds of file those may be, and whether changing one on a product already on sale needs looking at again.
+
+- **Let sellers upload digital files** - Off by default. Switched on, sellers attach downloadable files to their own products and set the download limits on them. Left off, only your own team adds files, and a seller sees the ones you added without being able to change them.
+- **Accepted file types for sellers** - Which formats a seller may upload. Pick from the list, or type a content type such as `application/pdf` and press Enter to add one that is not there. A whole family is accepted as well, written as `audio/*`.
+- **Review file changes on products already on sale** - On by default. A seller who adds or replaces a file on an approved product sends that product back to review and off sale until you approve it again.
+
+Uploading is off to begin with because a file a shopper downloads carries your marketplace's name, which makes it something your marketplace vouches for in the same way a listing is. A marketplace selling digital goods through its sellers switches it on; one where the files are your own leaves it off.
+
+The accepted types are checked against each file's own signature rather than its name, so renaming a file does not get it past the list. The list starts with the usual document, archive, audio, video and image formats. Your own uploads are never restricted by it.
+
+<Note>**Review file changes on products already on sale** does nothing where **Publish seller products automatically** is switched on, because there is no review step for a product to go back to. A marketplace that reviews nothing accepts the file along with everything else.</Note>
+
+## Communication
+
+![The Communication section, with the seller email switch](/docs/images/user/settings/marketplace/4-communication.png)
+
+Whether your store sends sellers its own emails about approval, products and payouts. Emails to customers are not affected either way.
+
+It is on by default, and most marketplaces leave it on, because it is what tells a seller their invitation is waiting or their application has been approved without anyone writing to them.
+
+Turning it off might suit a few specific situations:
+- A marketplace with few enough sellers that you write to each one personally, where the store's own wording would read as impersonal beside yours.
+- A marketplace running seller communication through its own mailing or support system, where two sets of emails about the same event would confuse people.
+- A store being set up or migrated, where real sellers exist in the data and nobody wants them to receive anything until the marketplace is ready.
+
+<Warning>With this off, nothing tells a seller they have been approved, suspended or rejected. Invitations are the exception and are still sent, because without one nobody can reach the panel at all.</Warning>
+
+## Commission Tax
+
+![The Commission tax section](/docs/images/user/settings/marketplace/5-commission-tax.png)
+
+The tax charged on your commission, as a percentage, used when neither the commission rate itself nor your tax provider supplies a rate. Leave it at zero if you charge no tax on your fee.
+
+Your commission is a fee on the service you provide to the seller, which is a separate thing from the goods the seller sells to the shopper. Where that service is taxable, the tax on it is worked out on its own and never mixes with the tax the customer paid on the item.
+
+This matters most to marketplaces operating where VAT applies to a commission charged between businesses, which covers the EU and other VAT jurisdictions. A marketplace whose fee is not taxable leaves the figure at zero and nothing is charged on it.
+
+<Note>Commission tax is worked out against the seller's own jurisdiction rather than the shopper's, because the service is sold to the seller. A marketplace with sellers in several countries is therefore likely to need a figure per rate rather than one default. See [<u>Commission Rates</u>](/user/sellers/commission-rates).</Note>
+
+<Note>This figure is a fallback. A commission rate carrying its own tax figure uses that instead for the sales it charges, and where a tax provider is configured, it answers before this default is reached.</Note>
+
+<Warning>Whether your commission is taxable, and at what rate, depends on where you and your sellers are based. Always confirm the correct rates with your accountant before entering a figure here.</Warning>
+
+## Further Reading
+
+- [<u>Seller Requirements</u>](/user/settings/seller-requirements) - The checklist a seller completes before approval
+- [<u>Sellers</u>](/user/sellers/sellers) - The sellers themselves, and approving them
+- [<u>Commission Rates</u>](/user/sellers/commission-rates) - What the marketplace charges on each sale
+- [<u>Payouts</u>](/user/sellers/payouts) - Settling what sellers are owed
diff --git a/docs/user/settings/seller-requirements.mdx b/docs/user/settings/seller-requirements.mdx
index 4cde4157c3..de8a39faf7 100644
--- a/docs/user/settings/seller-requirements.mdx
+++ b/docs/user/settings/seller-requirements.mdx
@@ -1,55 +1,131 @@
---
title: "Seller Requirements"
-description: "Build the checklist sellers complete before they can be approved to sell on your marketplace."
+description: "Learn how to set the checklist a seller completes before they can be approved to trade on your marketplace."
---
-Seller requirements are **the checklist sellers complete before they can be approved**. Each item appears on the seller's own onboarding checklist, and the required ones gate approval.
+Seller requirements define the checklist a seller must work through before they can be approved and start selling on your marketplace. Each requirement is one thing you ask of them, such as accepting your terms, filling in the profile shoppers see, or uploading a document that you need to have on record.
-To reach it, navigate to **Settings → Seller requirements**, under the **Marketplace** group.
+The checklist is the same for every seller. A seller sees it in their own panel as a list of tasks with progress tracker, and you see the same list on that seller's page in the admin dashboard along with the state of each item. A requirement marked as required has to be done before the seller can be approved, and one left optional is shown to them as recommended.
-## What's on the screen
+To manage the checklist, navigate to **Settings → Seller Requirements** in the admin dashboard.
-A drag-ordered list of requirements — the order you set here is the order sellers work through. There is no sort control; drag the handle to reorder.
+## Reviewing the Checklist
-A new store starts with five requirements, each marked **Required** and **Active**:
+![The Seller requirements list, showing the built-in requirements](/docs/images/user/settings/seller-requirements/1-requirements-list.png)
-- **Accept terms**
-- **Complete profile**
-- **Billing address**
-- **Returns address**
-- **Minimum products**
+The list shows one row per requirement, in the order sellers work through them.
-## Add a requirement
+| Column | What it means |
+|---|---|
+| **Name** | What the seller sees on their checklist, with the instructions you wrote beneath it. |
+| **Type** | What kind of thing is being asked for. |
+| **Required** | Whether it has to be done before approval, or is only recommended. |
+| **Status** | Whether the requirement is being asked for at all. |
+
+Rows are dragged to reorder them, and the order they sit in is the order the seller sees.
+
+### Default Requirements
+
+A new Spree marketplace has seven requirements on the list by default. They cover what any seller needs in place before they can trade, so most marketplaces add to this list rather than building one from nothing.
+
+| Requirement | What the seller does | What you can set |
+|---|---|---|
+| **Accept terms** | Reads and accepts your marketplace terms. | The terms themselves, the date they take effect, and an optional link to a published copy. Sellers who accepted before that date are asked again, which is how a change of terms is put to sellers already trading. |
+| **Complete profile** | Fills in the public profile shoppers see. | Which parts are required: the About text, the logo, the cover photo and the contact email. |
+| **Billing address** | Gives the address commission invoices are made out to. | |
+| **Returns address** | Gives the address customer returns are sent to. | |
+| **Delivery method** | Offers at least one way to ship their orders. | Nothing, but this one can also be met from your side: a delivery method of your own that is shared with sellers satisfies it for every seller at once, which suits a marketplace that ships everything itself. |
+| **Shipping box** | Gives the size and weight of the box they pack orders in. | |
+| **Minimum products** | Lists at least a set number of products. | How many products that is. |
+
+A built-in requirement can be deleted like any other, and can be added again afterwards from the same type list. Switching it off is usually the better move where your marketplace simply does not need it, such as a shipping box or a returns address on a marketplace selling only digital goods, because switching off keeps anything sellers have already submitted.
+
+## How to Add a Requirement
+
+1. Click **Add requirement**.
+2. Choose a **Type**, which decides what the seller is asked to do.
+3. Enter the **Name** the seller sees on their checklist.
+4. Enter the **Instructions** telling them what you need and why.
+5. Fill in anything the type asks for, described below.
+6. Leave **Required** on if it must be done before approval, or switch it off to show it as recommended.
+7. Click **Save**.
+
+A new requirement is added to the bottom of the list, and appears immediately on the checklist of every seller who has not yet been approved.
+
+## Additional Requirement Types
+
+The seven default requirements cover what every seller needs in place before they can trade. Anything asked for beyond that is built from the types below, which are chosen when adding a requirement and decide what the seller is asked to do.
+
+Most types can only be used once on a checklist, because the thing they ask for is only worth asking for once. The four marked as repeatable below can be added as many times as needed, which is how a checklist ends up with two separate documents or several statements to confirm. A type that can only be used once is not offered when adding a requirement if it is already on the list, and becomes available again if that requirement is deleted. The default requirements all work this way.
+
+| Type | What the seller does | Can be used in multiple requirements |
+|---|---|---|
+| **Payout account** | Connects an account that can receive their payouts. | No |
+| **Required custom fields** | Fills in the custom fields you choose. | No |
+| **Seller policy** | Publishes their own store policies. | Yes |
+| **Seller confirmation** | Confirms a statement you write, such as holding the rights to sell what they list. | Yes |
+| **Manual check** | Confirms they are ready to be checked, and leaves whatever reference you asked them for. A member of your team then marks it done. | Yes |
+| **Document** | Uploads a file for you to read, such as a registration certificate. | Yes |
+
+**Seller confirmation**, **Manual check** and **Document** all give the seller a note box alongside the answer itself, so a reference, an explanation or anything else worth knowing arrives with what they send. **Document** also tells the seller which file types are accepted, which are PDF, JPEG, PNG, HEIC, WebP and Word.
-Click **Add requirement**. The panel opens with a single **Type** dropdown, reading *"Choose what to ask for."* It offers the kinds not already in use:
+Those three look much the same to the seller, and differ in what happens once they have answered. A seller confirmation is taken at the seller's word and counts as met the moment they confirm it. A manual check and a document both wait for somebody on your team to accept them, which is why a manual check suits anything only your team can verify, such as a tax number against a public register. See [<u>Onboarding</u>](/user/sellers/onboarding) for making those decisions.
-- **Delivery method**
-- **Shipping box**
-- **Payout account**
-- **Required custom fields**
-- **Seller policy**
-- **Seller confirmation**
-- **Manual check**
-- **Document**
+<Note>There is no plain text or tick box type. A written answer is collected with **Required custom fields**, and a statement the seller has to agree to is collected with **Seller confirmation**.</Note>
-## Edit a requirement
+### Custom Seller Fields
-Opening a requirement gives you three settings:
+**Required custom fields** is how a seller is asked to type something in, such as a registration number or a license reference. It works differently from the other types, because the fields themselves are not created here.
-| Setting | What the screen says |
+An existing custom field on seller records has to exist before a requirement can ask for it. Create the fields first under [<u>Custom Fields</u>](/user/settings/custom-fields), choosing sellers as the type of record they apply to, and then add a requirement of this type and pick which of those fields the seller has to fill in.
+
+Pick only the fields the seller should answer themselves. A custom field on seller records is not necessarily a question for the seller, because your own team may be using some of them to record things of its own, such as the account manager looking after a seller or a note from a review. Every field picked here appears in the seller's task for them to fill in, so adding one of those asks the seller for something that was never meant for them, and makes it something they have to answer before they can be approved.
+
+The fields become part of the seller's record rather than living only on the checklist, so what a seller enters stays readable on their page afterwards. That makes custom requirements ideal for storing important information that you may need to reference later, such as a company number that you check against a register.
+
+## What to Ask Sellers For
+
+The seven built-in requirements cover what any seller needs in order to trade. What you add on top depends on what you sell and what you are accountable for.
+
+Most marketplaces ask for some of the following, whatever they sell:
+
+- A company registration number and a tax registration number, as **Required custom fields**.
+- Proof of liability insurance, as a **Document**, where a seller's goods could cause harm.
+- A confirmation that the seller owns the rights to everything they list, as a **Seller confirmation**, which is the usual protection against counterfeit goods.
+- A published returns policy, as a **Seller policy**, so a shopper can read the terms before buying.
+
+Beyond that, what you ask follows your industry.
+
+| Marketplace | What it tends to ask for |
|---|---|
-| **Name** | *"What the seller sees on their checklist."* |
-| **Required** | *"Required items must be done before a seller can be approved. Others are shown as recommended."* |
-| **Active** | *"Switch off to stop asking for this without deleting it."* |
+| **Food and drink** | A food hygiene or food business registration certificate, and a confirmation that allergen information on every listing is accurate. |
+| **Cosmetics and personal care** | A product safety report or its reference number, and the responsible person named for the market being sold into. |
+| **Electronics** | A declaration of conformity for the market, and registration under electrical waste rules where they apply. |
+| **Supplements and health** | The registration or notification reference for the products being listed, and a confirmation that no medical claims are made. |
+| **Alcohol** | The seller's license to sell it, and a confirmation that they will carry out age checks on delivery. |
+| **Jewelry and precious metals** | Assay or hallmarking evidence, and a confirmation about the origin of materials. |
+| **Secondhand and resale** | A description of how authenticity is checked, which suits a **Manual check** reviewed by your team. |
+| **Handmade and craft** | A confirmation that the seller makes what they list themselves, where that is the point of the marketplace. |
+
+<Warning>A requirement records what a seller told you. It does not verify any of it, so a license number collected as a custom field is a number in a box until somebody checks it against the register. Use a **Manual check** for anything that has to be verified by a person, which makes the verification itself a step on the checklist rather than something to remember.</Warning>
+
+<Note>Requirements are the same for every seller. A marketplace selling across several of the categories above asks every seller for all of it, so it is worth keeping the list to what genuinely applies to all of them and handling the rest when you review each seller.</Note>
+
+## How to Edit a Requirement
+
+Choose **Edit** from the menu at the end of a row, which opens the same fields as creating one. Editing also offers an **Active** switch, which stops a requirement being asked for without deleting it or losing what sellers have already submitted.
+
+Editing a built-in requirement is where its own settings are changed, such as the terms sellers accept or the minimum number of products they have to list. Those settings are listed under [<u>Default Requirements</u>](#default-requirements).
+
+## How to Delete a Requirement
-## Good to know
+Choose **Delete** from the menu at the end of a row and confirm.
-- A requirement type can only be used once, so the **Add requirement** list shrinks as you add them.
-- Switching a requirement to inactive retires it without losing the record of sellers who already completed it.
-- Marking an item **Required** is what gates approval — anything left unrequired is shown to the seller as recommended.
+<Warning>Deleting a requirement also deletes everything sellers have already submitted for it, including uploaded documents. Switching it to inactive instead stops it being asked for while keeping what has been submitted.</Warning>
-## Related
+## Further Reading
-- [<u>Sellers → Onboarding</u>](/user/sellers/onboarding)
-- [<u>Sellers → Managing Sellers</u>](/user/sellers/managing-sellers)
-- [<u>Settings → Marketplace</u>](/user/settings/marketplace)
+- [<u>Onboarding</u>](/user/sellers/onboarding) - How a seller works through this checklist and gets approved
+- [<u>Marketplace Settings</u>](/user/settings/marketplace) - Whether sellers are approved automatically
+- [<u>Sellers</u>](/user/sellers/sellers) - The sellers themselves
+- [<u>Custom Fields</u>](/user/settings/custom-fields) - The fields a required custom fields requirement can ask for