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.

Add / update user guides + re-org dashboard nav and connect every das… (#14639)

Damian Legawieceaa998676da6
diff --git a/docs/developer/core-concepts/commissions.mdx b/docs/developer/core-concepts/commissions.mdx
index 47829288e6..18e323b13d 100644
--- a/docs/developer/core-concepts/commissions.mdx
+++ b/docs/developer/core-concepts/commissions.mdx
@@ -312,15 +312,17 @@ There is **no write path**. Lines are read-only in the API, and correcting a cha
## What this doesn't do
-Commission lines say what the marketplace charged. They don't move money.
+Commission lines say what the marketplace charged. They don't move money, and they don't say what a seller is owed.
-<Warning>
-Open source has **no payout ledger**. Paying sellers means connecting a provider such as Stripe Connect, or building against the commission lines and [payment splits](/developer/core-concepts/sellers#one-checkout-several-sellers). Scheduled payout runs, refund clawbacks and reconciliation are Enterprise features.
-</Warning>
+That is the [payout ledger's](/developer/core-concepts/sellers#payouts) job: when an order is fulfilled, a seller transfer is written for the sale *less these lines*, and payouts settle those transfers on the seller's schedule — by the built-in provider, which keeps the books and leaves the operator to pay by bank, or by Stripe Connect, which performs the transfer. A commission line is an input to that ledger, never a row in it.
+
+<Note>
+Refund clawbacks and netting across settlements, reconciliation and seller tax reporting are Spree Enterprise.
+</Note>
## Related
-- [Sellers](/developer/core-concepts/sellers) — marketplaces, order splitting and payment splits
+- [Sellers](/developer/core-concepts/sellers) — marketplaces, order splitting, and the payout ledger commission feeds
- [Taxes](/developer/core-concepts/taxes) — the tax vocabulary commission lines share
- [Fees](/developer/core-concepts/fees) — buyer-facing charges, which commissions are not
- [Promotions](/developer/core-concepts/promotions) — the same rules-and-record split, on the buyer side
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdx
index f836f7d666..363b849b8a 100644
--- a/docs/developer/core-concepts/payments.mdx
+++ b/docs/developer/core-concepts/payments.mdx
@@ -559,19 +559,23 @@ stateDiagram-v2
With **auto-capture** enabled (default for most gateways), the Payment goes directly from `checkout` → `processing` → `completed`. With **manual capture**, it stops at `pending` until an admin captures it.
-#### Order Payment States
+#### Order Payment Status
-Each payment update also recalculates the order's `payment_state`:
+Each payment update also recalculates the order's `payment_status`, derived from its payments and refunds against the order total:
-| Payment State | Description |
+| Payment status | Description |
|---------------|-------------|
-| `balance_due` | Payment is required for this order |
-| `failed` | The last payment for the order failed |
-| `credit_owed` | This order has been paid for in excess of its total |
-| `paid` | This order has been paid for in full |
+| `none` | Nothing has been authorized or captured |
+| `authorized` | Approved by the gateway, not yet captured |
+| `partially_paid` | Captured less than the order total |
+| `paid` | Captured payments cover the order total |
+| `partially_refunded` | Refunded in part; the customer has paid something net |
+| `refunded` | Refunds returned everything captured |
+| `overcharged` | Captured more than the order total — the customer is owed the difference |
+| `voided` | The order was canceled and its authorization released |
<Warning>
-You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase could indicate a problem with your payment gateway and most likely a serious problem affecting customer satisfaction. Check your payment gateway's dashboard for the most recent transactions if this is happening.
+Keep an eye on orders sitting at `authorized` or `partially_paid` long after placement — a sudden increase can indicate a problem with your payment gateway that is affecting customers. Check the gateway's own dashboard for recent transactions.
</Warning>
## Payment Sources
diff --git a/docs/developer/core-concepts/sellers.mdx b/docs/developer/core-concepts/sellers.mdx
index 29fde57af8..579fd09fcf 100644
--- a/docs/developer/core-concepts/sellers.mdx
+++ b/docs/developer/core-concepts/sellers.mdx
@@ -286,13 +286,92 @@ See [Commissions](/developer/core-concepts/commissions) for rate targeting, the
## Payouts
-Spree records what each seller earned and what the marketplace charged: the payment splits say what each seller's share of the money was, and the commission lines say what was deducted.
+Spree keeps a two-level ledger of what each seller is owed, and settles it on a schedule. Whether money actually moves is the payout provider's job; the books are kept either way.
-<Warning>
-**Actually moving money to sellers is not implemented in open source.** There is no payout or transfer ledger here — a seller carries payout *preferences* (how often, and a minimum amount), but nothing acts on them.
+```mermaid
+flowchart LR
+ F["order.fulfilled"] --> T["SellerTransfer<br/><i>earning</i>"]
+ R["refund.created"] --> RV["SellerTransfer<br/><i>refund_reversal</i>"]
+ T --> P["SellerPayout<br/>swept on the seller's schedule"]
+ RV --> P
+ P --> C["complete<br/>operator, or provider webhook"]
+```
-Paying vendors means connecting a provider such as Stripe Connect, or building against the payment splits and [commission lines](/developer/core-concepts/commissions). Scheduled payout runs, refund clawbacks, reconciliation and tax reporting are Enterprise features.
-</Warning>
+### Transfers — what an order earned
+
+A seller earns on **fulfillment**, not on payment: the marketplace holds the money until the goods ship, and a digital order fulfils immediately so it earns immediately. When `order.fulfilled` fires, a `Spree::SellerTransfer` of kind `earning` is written for the seller's sale less [commission](/developer/core-concepts/commissions), in the sale's currency.
+
+The amount is payment-source-agnostic — store credit and gift cards are how the customer paid, which is the platform's funding concern, not the seller's.
+
+A refund never edits an earning. `refund.created` writes a second row of kind `refund_reversal` against the same order, so what a seller has earned is always the sum of their transfers, and a reversal that lands after a payout closed falls into the next period rather than rewriting a settlement that already happened.
+
+### Payouts — what was sent
+
+On schedule, a seller's confirmed, unsettled earnings are batched into one `Spree::SellerPayout` per currency and handed to the provider. A payout names exactly which transfers it settled, which is what a seller needs to reconcile a deposit.
+
+Both records share one status set: `pending` → `processing` → `completed`, or `failed` / `unresolved`. **Completing is what debits the balance** — a balance is earnings less *completed* settlements — and nothing completes a payout automatically at creation, because "the money arrived" is a claim about the outside world. An operator running the built-in provider marks it paid once the bank transfer is sent; a connected provider marks it paid when its webhook says so. Either way it publishes `seller_payout.completed`.
+
+`unresolved` is deliberate: a send whose outcome nobody knows keeps its transfers rather than releasing them, since releasing is how the same earnings get sent twice.
+
+### Schedule and thresholds
+
+Each seller settles on their own interval — `daily`, `weekly`, `biweekly`, `monthly`, or `manual` — and only once their balance clears a minimum. Both fall back to the store's defaults (`default_payouts_schedule_interval`, `default_minimum_payout_amount`); below the minimum the balance simply carries forward.
+
+The scheduler is the host app's. Two jobs fan out per seller and the interval logic lives inside them, since a cron expression cannot say "weekly, but from whenever *this* seller was last paid":
+
+| Job | Run it | Does |
+|---|---|---|
+| `Spree::SellerPayouts::SweepDueJob` | daily | settles every seller who is due |
+| `Spree::SellerTransfers::ExecutePendingDueJob` | hourly | retries earnings a provider refused — usually a passing thing |
+
+`spree/spree-starter` ships both entries in `server/config/recurring.yml`. A seller on the `manual` interval is skipped by the sweep and settled by hand instead:
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Where the seller stands, one row per currency
+const { data: balances } = await adminClient.sellers.balances('sel_xxx')
+
+// Settle them now, whatever their schedule says
+await adminClient.sellers.settle('sel_xxx')
+
+// The built-in provider: record that the bank transfer went out
+await adminClient.sellerPayouts.complete('spo_xxx', { reference: 'TRN-2026-0912-0042' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/balances' \
+ -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/payouts' \
+ -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/seller_payouts/spo_xxx/complete' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "reference": "TRN-2026-0912-0042" }'
+```
+
+</CodeGroup>
+
+`GET /admin/seller_transfers` and `GET /admin/seller_payouts` list the ledger across every seller; the seller panel reads its own through `GET /seller/balances`, `/seller/transfers` and `/seller/payouts`, all read-only — the ledger is written by fulfilment and the sweep, never by the seller.
+
+### Payout providers
+
+A provider is a stateless class registered in `Spree.payout_providers` and chosen per store with the `payout_provider` preference. Core ships one:
+
+| Provider | Moves money? | Completion |
+|---|---|---|
+| `Spree::PayoutProvider::System` (default) | No — keeps the books | The operator marks each payout paid, with the bank reference |
+| Stripe Connect (`spree_stripe`) | Yes — transfers each earning to the seller's connected account as goods ship, tied to the charge that funds it | A Stripe webhook, when the money lands |
+
+The contract is small: `transfer!` credits one earning, `pay!` sends one settlement, `reverse!` takes back part of an earning after a refund, and every call carries an idempotency key derived from the ledger row so a retry finds the movement it already made. Providers that need the seller to hold an account with them answer `requires_payout_account?` and implement `onboarding_url` — which is what the **payout account** [onboarding requirement](#onboarding-requirements) drives. To pay sellers through rails of your own, see [Seller payouts](/developer/providers/payouts).
+
+See [Stripe Connect for marketplaces](/integrations/payments/stripe-connect) for the shipped provider.
+
+<Note>
+Refund clawbacks and netting across settlements, reconciliation, KYC operations and seller tax reporting (DAC7) are Spree Enterprise.
+</Note>
## The seller panel
diff --git a/docs/developer/providers/overview.mdx b/docs/developer/providers/overview.mdx
index 0f62ef8ce8..d76d34f168 100644
--- a/docs/developer/providers/overview.mdx
+++ b/docs/developer/providers/overview.mdx
@@ -34,6 +34,7 @@ Every connection point is a documented contract with a default implementation th
| WMS / 3PL / carriers | Fulfillment provider | [Shipping & WMS](/developer/providers/fulfillment) |
| Carrier rate shopping | Delivery rate provider | [Custom delivery rates](/developer/how-to/custom-delivery-rate-provider) |
| PSP | Payment gateway | [Custom payment method](/developer/how-to/custom-payment-method) |
+| Seller payouts | Payout provider | [Seller payouts](/developer/providers/payouts) |
| Tax engine | Tax provider | [Avalara](/integrations/tax/avalara) |
| Search | Search provider | [Custom search provider](/developer/how-to/custom-search-provider) |
| Identity provider (SSO) | OpenID Connect | [Identity & SSO](/developer/providers/sso) |
diff --git a/docs/developer/providers/payouts.mdx b/docs/developer/providers/payouts.mdx
new file mode 100644
index 0000000000..b708bc1df4
--- /dev/null
+++ b/docs/developer/providers/payouts.mdx
@@ -0,0 +1,333 @@
+---
+title: Seller Payouts
+description: Pay marketplace sellers through your own rails — a bank transfer API, a wallet, another PSP's platform product — by implementing the payout provider contract.
+---
+
+Spree keeps the marketplace's books on its own: what each seller earned as their orders shipped, and what has been settled to them. A **payout provider** is the part that actually moves the money. The built-in one moves nothing and leaves the operator to pay by bank; Stripe Connect moves it through connected accounts. This guide is for the third case — a provider of your own.
+
+Read [how the ledger works](/developer/core-concepts/sellers#payouts) first. Everything below assumes the vocabulary there: a *transfer* is one order's earning, a *payout* is a batch of them settled to the seller.
+
+## What a provider decides
+
+Core calls a provider at exactly three moments. Each verb takes the ledger row it is about and returns it:
+
+| Verb | When core calls it | What you do |
+|---|---|---|
+| `transfer!(seller_transfer)` | An order is fulfilled and the seller is payable | Credit the seller's earning — or, if your rails only move money at settlement, mark the row `completed` and do nothing else |
+| `pay!(seller_payout)` | A scheduled sweep or an operator settles a seller | Send the batch. Store the provider's own id in `reference`, and leave the status alone — a payout is completed when the money is confirmed to have landed, not when it was sent |
+| `reverse!(seller_transfer)` | A refund takes back part of an earning | Pull the money back if your rails can. Core writes the reversal row either way, so a provider that cannot claw back implements this as a no-op |
+
+Alongside the verbs, a provider tells core what it needs from sellers before it can pay them:
+
+| Method | Answers |
+|---|---|
+| `self.requires_payout_account?` | Must a seller hold an account with you first? When `true`, core will not credit a seller until they are marked payable |
+| `onboarding_url(seller, refresh_url:, return_url:)` | A fresh hosted link where the seller gives you what you need. Minted per call — these links expire. `nil` when you host nothing |
+| `onboarded?(seller)` | Will you accept money for this seller right now? Ask your API; the answer can change without anything happening in Spree |
+| `onboarding_state(seller)` | Why not yet: `:action` (the seller must do something), `:pending` (you are checking), `:rejected`, or `nil` |
+| `onboarding_message(seller)` | Your own words about what is outstanding. Best-effort and unlocalized |
+
+And three class-level descriptors: `display_name` (what the operator picks in settings), `reference_system` (the key a seller's account is filed under — a lowercase identifier, matching your `Spree::Integration` key if you ship one), and `available_for_store?(store)` (`false` until the store holds credentials for you). Leave `provider_key` alone: it is the full class name, and it is what the ledger's unique index on `(provider, reference)` keys on.
+
+Providers are stateless and built with no arguments. Anything request-specific arrives as a parameter.
+
+## Writing your own
+
+The example below settles sellers by bank transfer through a fictional payments API. It moves money only at payout time, so `transfer!` is pure bookkeeping.
+
+```ruby server/app/models/my_app/payout_provider.rb
+module MyApp
+ class PayoutProvider < Spree::PayoutProvider::Base
+ def self.display_name
+ 'Acme Bank Rails'
+ end
+
+ def self.reference_system
+ 'acme'
+ end
+
+ def self.requires_payout_account?
+ true
+ end
+
+ def self.available_for_store?(store)
+ store.integrations.active.exists?(type: 'MyApp::AcmeIntegration')
+ end
+
+ def onboarding_url(seller, refresh_url:, return_url:)
+ account_id = seller.payout_account_reference(self.class) ||
+ client(seller.store).accounts.create(email: seller.contact_email).id.tap do |id|
+ seller.set_payout_account_reference(self.class, id)
+ end
+
+ client(seller.store).onboarding_links.create(account: account_id, refresh_url:, return_url:).url
+ rescue Acme::Error => e
+ raise Spree::Core::GatewayError, e.message
+ end
+
+ def onboarded?(seller)
+ account = client(seller.store).accounts.retrieve(seller.payout_account_reference(self.class))
+ account.verified?
+ end
+
+ def transfer!(seller_transfer)
+ seller_transfer.update!(status: 'completed')
+ seller_transfer
+ end
+
+ def pay!(seller_payout)
+ seller = seller_payout.seller
+ transfer = client(seller.store).transfers.create(
+ amount: seller_payout.amount,
+ currency: seller_payout.currency,
+ destination: seller.payout_account_reference(self.class),
+ idempotency_key: idempotency_key(seller_payout)
+ )
+
+ seller_payout.update!(reference: transfer.id)
+ seller_payout
+ rescue Acme::TimeoutError, Acme::ServerError => e
+ raise Spree::Core::AmbiguousGatewayError, e.message
+ rescue Acme::Error => e
+ raise Spree::Core::GatewayError, e.message
+ end
+
+ def reverse!(seller_transfer)
+ seller_transfer.update!(status: 'completed')
+ seller_transfer
+ end
+
+ private
+
+ def client(store)
+ Acme::Client.new(api_key: store.integrations.active.find_by!(type: 'MyApp::AcmeIntegration').preferred_api_key)
+ end
+ end
+end
+```
+
+Credentials come from a [Spree integration](/developer/how-to/custom-delivery-rate-provider#1-store-credentials-in-an-integration), never from environment variables — a marketplace may run several stores, and each pays from its own account. The one the provider reads above holds the API key and the secret your webhooks are signed with:
+
+```ruby server/app/models/my_app/acme_integration.rb
+module MyApp
+ class AcmeIntegration < Spree::Integration
+ preference :api_key, :password
+ preference :webhook_secret, :password
+
+ def self.integration_group = 'payments'
+
+ def can_connect?
+ Acme::Client.new(api_key: preferred_api_key).ping
+ true
+ rescue Acme::Error => e
+ self.connection_error_message = e.message
+ false
+ end
+ end
+end
+```
+
+### Register it
+
+```ruby server/config/initializers/spree.rb
+Spree.integrations << 'MyApp::AcmeIntegration'
+Spree.payout_providers << MyApp::PayoutProvider
+```
+
+The operator then picks it under **Settings → Payouts**, which is the store's `payout_provider` preference. The picker is built from the registry, so your provider appears with the two built-in ones and reports whether the store can use it today:
+
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: providers } = await adminClient.payoutProviders.list()
+// [{ id: 'MyApp::PayoutProvider', name: 'Acme Bank Rails', available: true,
+// requires_payout_account: true, default: false }, ...]
+```
+
+```bash cURL
+curl https://your-store.com/api/v3/admin/payout_providers \
+ -H "X-Spree-API-Key: sk_xxx"
+```
+
+</CodeGroup>
+
+A store whose configured provider disappears from the registry — a gem removed, a class renamed — silently falls back to the built-in one so the ledger keeps recording. Rename with `def self.provider_key` pinned to the old name if you ever need to, or the rows written under the old name stop matching.
+
+## Errors decide what happens next
+
+Core reads two exceptions, and which one you raise decides whether the money is offered to your API again:
+
+| You raise | What it means | What core does |
+|---|---|---|
+| `Spree::Core::GatewayError` (or any other `StandardError`) | A definite refusal — the money did not move | An earning stays retryable and `SellerTransfers::ExecutePendingDueJob` asks again on its hourly run. A payout is marked `failed` and its earnings are released for the next sweep |
+| `Spree::Core::AmbiguousGatewayError` | Nobody knows — a timeout, a 5xx, an idempotency conflict | The row is parked as `unresolved`. Nothing automatic touches it again; an operator resolves it against your books, or your webhook does |
+
+Get this right. Raising a plain error on a timeout is how the same settlement is sent twice: the payout is failed, its earnings go back on the pile, and the next sweep batches them into a new payout with a new idempotency key — one your provider has never seen.
+
+## Idempotency
+
+Every call carries `idempotency_key(record)` — `spree-<prefixed id>` of the ledger row. Pass it to your API on every write. A crash between your API answering and Spree committing is retried, and the retry must find the movement it already made rather than make a second.
+
+If your rails have no idempotency keys, look the movement up by that key (or by the row's prefixed id in your own metadata) before creating it.
+
+## Seller accounts
+
+A seller's account with your provider is stored as an [external reference](/developer/providers/erp#addressing-records-by-your-keys) filed under your `reference_system`, so a marketplace that migrates between providers keeps every account on record:
+
+| Need | Call |
+|---|---|
+| Record the account you opened | `seller.set_payout_account_reference(MyApp::PayoutProvider, 'acct_123')` |
+| Read it back | `seller.payout_account_reference(MyApp::PayoutProvider)` |
+| Find the seller a webhook is about | `Spree::Seller.with_payout_account(store, MyApp::PayoutProvider, 'acct_123').first` |
+
+The reverse lookup is a uniquely indexed read, scoped to the store's own sellers — a webhook naming an account from another store finds nothing.
+
+## Onboarding
+
+When a store's provider requires an account, the operator adds the **Payout account** row to the seller [onboarding checklist](/developer/core-concepts/sellers#onboarding-requirements). That row reads your `onboarded?` and `onboarding_state`, and the seller panel's button asks for a link at the moment it is clicked:
+
+<CodeGroup>
+
+```typescript Seller SDK
+const { url } = await sellerClient.onboarding.payoutAccount({
+ refresh_url: 'https://sellers.your-store.com/onboarding?refresh=1',
+ return_url: 'https://sellers.your-store.com/onboarding',
+})
+// url is null when the provider hosts no onboarding of its own
+```
+
+```bash cURL
+curl -X POST https://your-store.com/api/v3/seller/onboarding/payout_account \
+ -H "Authorization: Bearer <seller_jwt>" \
+ -H "X-Spree-Seller-Id: sel_xxx" \
+ -H "Content-Type: application/json" \
+ -d '{"refresh_url": "https://sellers.your-store.com/onboarding?refresh=1", "return_url": "https://sellers.your-store.com/onboarding"}'
+```
+
+</CodeGroup>
+
+That request lands in your `onboarding_url`. A `Spree::Core::GatewayError` raised there becomes a 422 the panel can show; anything else is a crash.
+
+## Confirming from a webhook
+
+Two things only your provider can tell Spree, and both usually arrive as webhooks: that a seller became payable, and that a payout landed or bounced. The Stripe provider receives them through the shipped `/api/v3/webhooks/payouts/:payment_method_id` route, which works for any provider that is also a payment method and implements `handle_payout_webhook(raw_body, headers)` on its gateway. A standalone provider adds its own endpoint to the host app.
+
+Address it to the integration rather than the store: the integration is what holds the signing secret, and the store follows from it.
+
+```ruby server/config/routes.rb
+Rails.application.routes.draw do
+ post 'webhooks/acme/:integration_id', to: 'acme_webhooks#create'
+
+ mount Spree::Core::Engine, at: '/'
+end
+```
+
+```ruby server/app/controllers/acme_webhooks_controller.rb
+# Events from the payout provider: POST /webhooks/acme/:integration_id
+#
+# Handled inline rather than in a job — marking a seller payable or a payout
+# settled is a couple of database writes — and answered with a 5xx when they
+# fail, so the provider redelivers. A 200 for work that did not happen is a
+# settlement nobody will ever record.
+class AcmeWebhooksController < ActionController::API
+ include ActionController::RateLimiting
+
+ rate_limit to: 120, within: 1.minute, store: Rails.cache, by: -> { request.remote_ip }
+
+ def create
+ integration = Spree::Integration.active.find_by_prefix_id!(params[:integration_id])
+ event = verified_event(integration)
+
+ case event['type']
+ when 'account.updated' then account_updated(integration.store, event['data'])
+ when 'transfer.paid' then payout_settled(integration.store, event['data'], paid: true)
+ when 'transfer.failed' then payout_settled(integration.store, event['data'], paid: false)
+ end
+
+ head :ok
+ rescue Spree::Integration::WebhookSignatureError
+ head :unauthorized
+ rescue ActiveRecord::RecordNotFound
+ head :not_found
+ rescue StandardError => e
+ Rails.error.report(e, source: 'my_app.webhooks.acme')
+ head :internal_server_error
+ end
+
+ private
+
+ # Constant-time comparison against the secret this integration was given.
+ # Anything unsigned or signed for another store is a 401, so a
+ # misconfigured sender notices rather than being silently ignored.
+ def verified_event(integration)
+ expected = OpenSSL::HMAC.hexdigest('SHA256', integration.preferred_webhook_secret.to_s, request.raw_post)
+ given = request.headers['X-Acme-Signature'].to_s
+ raise Spree::Integration::WebhookSignatureError unless ActiveSupport::SecurityUtils.secure_compare(expected, given)
+
+ JSON.parse(request.raw_post)
+ rescue JSON::ParserError
+ raise Spree::Integration::WebhookSignatureError, 'Malformed webhook payload'
+ end
+
+ # The provider knows the account, not the seller. The reverse lookup is a
+ # uniquely indexed read scoped to this store, so an account id from another
+ # tenant finds nothing.
+ def seller_for(store, account_id)
+ Spree::Seller.with_payout_account(store, MyApp::PayoutProvider, account_id).first
+ end
+
+ # Whether the provider will now accept money for this seller. It can go
+ # back to false — expired documents, a closed account — and clearing the
+ # stamp makes Spree hold new earnings instead of promising money nothing
+ # can send. Becoming payable sends whatever they earned while unverified.
+ def account_updated(store, data)
+ seller = seller_for(store, data['account_id'])
+ return if seller.nil?
+
+ verified = data['verified'] == true
+ became_payable = verified && seller.payouts_enabled_at.nil?
+
+ seller.update!(payouts_enabled_at: verified ? (seller.payouts_enabled_at || Time.current) : nil)
+ Spree::SellerTransfers::ExecutePendingJob.perform_later(seller.id) if became_payable
+ end
+
+ # Matched on the reference stored in `pay!`, never on amount or recency: a
+ # redelivered event would otherwise skip the settlement it already completed
+ # and land on the next one owed. The workflow is idempotent against a second
+ # delivery and races safely with an operator marking the same payout paid.
+ def payout_settled(store, data, paid:)
+ seller = seller_for(store, data['account_id'])
+ return if seller.nil?
+
+ payout = seller.seller_payouts.find_by(provider: MyApp::PayoutProvider.provider_key, reference: data['transfer_id'])
+ return if payout.nil? || payout.completed?
+
+ if paid
+ Spree.seller_payout_complete_workflow.call(seller_payout: payout, reference: data['transfer_id'])
+ else
+ payout.fail!
+ end
+ end
+end
+```
+
+`fail!` releases the payout's earnings so the next sweep picks them up again. Completing publishes `seller_payout.completed`, which is what the seller's balance and their panel read.
+
+## What to test
+
+The Stripe provider's spec in the monorepo (`spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rb`) is the reference battery. The cases worth copying:
+
+- `pay!` passes the idempotency key and stores the provider's id as `reference`, leaving the status `pending`
+- A timeout raises `AmbiguousGatewayError`, a refusal raises `GatewayError` — the two the ledger tells apart
+- Amounts are sent in the units your API expects (`Spree::Money::Rounding.to_minor_units(amount, currency)` for cents)
+- `onboarded?` asks the API rather than reading the cached stamp
+
+<Note>
+Refund clawbacks netted across settlements, reconciliation against provider statements, KYC operations and seller tax reporting (DAC7) are Spree Enterprise. Open source ships the ledger, the contract, and the two providers above.
+</Note>
+
+## Related
+
+- [Sellers — payouts](/developer/core-concepts/sellers#payouts) — the ledger, the schedule, and the admin API around it
+- [Commissions](/developer/core-concepts/commissions) — what a seller's earning is net of
+- [Stripe Connect for marketplaces](/integrations/payments/stripe-connect) — the shipped provider that moves money
diff --git a/docs/docs.json b/docs/docs.json
index 39ff10f837..69f4fb6fa6 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -32,6 +32,14 @@
"library": "lucide"
},
"redirects": [
+ {
+ "source": "/user/orders/order-states",
+ "destination": "/user/orders/order-statuses"
+ },
+ {
+ "source": "/user/orders/order-adjustments",
+ "destination": "/user/orders/discounts-fees-and-taxes"
+ },
{
"source": "/developer/core-concepts/companies-and-catalogs",
"destination": "/developer/core-concepts/companies"
@@ -435,6 +443,62 @@
{
"source": "/user/customers/assign-store-credits",
"destination": "/user/loyalty/store-credits"
+ },
+ {
+ "source": "/user/manage-products/stock-levels",
+ "destination": "/user/inventory/stock-levels"
+ },
+ {
+ "source": "/user/manage-products/stock-transfers",
+ "destination": "/user/inventory/stock-transfers"
+ },
+ {
+ "source": "/user/manage-products/price-lists",
+ "destination": "/user/pricing/price-lists"
+ },
+ {
+ "source": "/user/manage-products/translations",
+ "destination": "/user/translations/translations"
+ },
+ {
+ "source": "/user/manage-products/product-taxonomies",
+ "destination": "/user/products/categories"
+ },
+ {
+ "source": "/user/returns/returns-processing",
+ "destination": "/user/orders/returns"
+ },
+ {
+ "source": "/user/vendors/vendor-management",
+ "destination": "/user/sellers/managing-sellers"
+ },
+ {
+ "source": "/user/vendors/vendor-onboarding-manual",
+ "destination": "/user/sellers/onboarding"
+ },
+ {
+ "source": "/user/vendors/vendor-onboarding-shopify",
+ "destination": "/user/sellers/onboarding"
+ },
+ {
+ "source": "/user/vendors/vendor-onboarding-woocommerce",
+ "destination": "/user/sellers/onboarding"
+ },
+ {
+ "source": "/user/vendors/commission-rates",
+ "destination": "/user/sellers/commission-rates"
+ },
+ {
+ "source": "/user/vendors/vendor-payouts",
+ "destination": "/user/sellers/payouts"
+ },
+ {
+ "source": "/user/vendors/multi-vendor-checkout",
+ "destination": "/user/sellers/orders"
+ },
+ {
+ "source": "/user/settings/marketplace",
+ "destination": "/user/sellers/payouts"
}
],
"contextual": {
@@ -592,6 +656,13 @@
"integrations/payments/razorpay"
]
},
+ {
+ "group": "Marketplace",
+ "pages": [
+ "developer/providers/payouts",
+ "integrations/payments/stripe-connect"
+ ]
+ },
{
"group": "Tax",
"pages": [
@@ -934,61 +1005,74 @@
},
{
"group": "Products",
+ "icon": "package",
"pages": [
- {
- "group": "Create & Edit Products",
- "pages": [
- "user/products/creating-products",
- "user/products/deleting-products",
- "user/products/editing-products",
- "user/products/editing-multi-variant-products",
- "user/products/cloning-products"
- ]
- },
- {
- "group": "Manage Products",
- "pages": [
- "user/manage-products/search-products",
- "user/manage-products/bulk-product-operations",
- "user/manage-products/price-lists",
- "user/manage-products/export-products",
- "user/manage-products/import-products",
- "user/manage-products/multi-currency-import-export",
- "user/manage-products/product-import-file-template",
- "user/manage-products/translations",
- "user/manage-products/stock-levels",
- "user/manage-products/stock-transfers",
- "user/manage-products/product-taxonomies",
- "user/manage-products/product-options",
- "user/manage-products/product-metafields"
- ]
- }
- ],
- "icon": "package"
+ "user/products/creating-products",
+ "user/products/editing-products",
+ "user/products/editing-multi-variant-products",
+ "user/products/cloning-products",
+ "user/products/deleting-products",
+ "user/manage-products/search-products",
+ "user/manage-products/bulk-product-operations",
+ "user/products/categories",
+ "user/products/collections",
+ "user/manage-products/product-options",
+ "user/manage-products/product-metafields",
+ "user/manage-products/import-products",
+ "user/manage-products/export-products",
+ "user/manage-products/product-import-file-template",
+ "user/manage-products/multi-currency-import-export"
+ ]
+ },
+ {
+ "group": "Inventory",
+ "icon": "warehouse",
+ "pages": [
+ "user/inventory/stock-levels",
+ "user/inventory/stock-transfers",
+ "user/inventory/purchase-orders",
+ "user/inventory/suppliers"
+ ]
+ },
+ {
+ "group": "Pricing",
+ "icon": "tag",
+ "pages": [
+ "user/pricing/price-lists"
+ ]
+ },
+ {
+ "group": "Catalogs",
+ "icon": "book-marked",
+ "pages": [
+ "user/catalogs/catalogs"
+ ]
+ },
+ {
+ "group": "Translations",
+ "icon": "languages",
+ "pages": [
+ "user/translations/translations"
+ ]
},
{
"group": "Orders",
"pages": [
- "user/orders/order-states",
+ "user/orders/order-statuses",
"user/orders/processing-orders",
"user/orders/creating-orders",
"user/orders/editing-orders",
- "user/orders/order-adjustments",
+ "user/orders/discounts-fees-and-taxes",
"user/orders/exporting-orders",
"user/orders/cancelling-orders",
"user/orders/refunding-orders",
- "user/orders/searching-orders"
+ "user/orders/searching-orders",
+ "user/orders/returns",
+ "user/orders/exchanges",
+ "user/orders/claims"
],
"icon": "shopping-cart"
},
- {
- "group": "Returns",
- "pages": [
- "user/settings/returns-configuration",
- "user/returns/returns-processing"
- ],
- "icon": "undo-2"
- },
{
"group": "Customers",
"pages": [
@@ -997,10 +1081,24 @@
"user/customers/edit-customer",
"user/customers/searching-customers",
"user/customers/exporting-customers",
- "user/customers/customer-groups"
+ "user/customers/customer-groups",
+ "user/customers/companies"
],
"icon": "users"
},
+ {
+ "group": "Sellers",
+ "icon": "store",
+ "pages": [
+ "user/sellers/sellers",
+ "user/sellers/onboarding",
+ "user/sellers/managing-sellers",
+ "user/sellers/products",
+ "user/sellers/orders",
+ "user/sellers/commission-rates",
+ "user/sellers/payouts"
+ ]
+ },
{
"group": "Loyalty",
"pages": [
@@ -1021,18 +1119,11 @@
"icon": "ticket-percent"
},
{
- "group": "Vendors",
+ "group": "Reports",
+ "icon": "chart-column",
"pages": [
- "user/settings/marketplace",
- "user/vendors/vendor-onboarding-shopify",
- "user/vendors/vendor-onboarding-woocommerce",
- "user/vendors/vendor-onboarding-manual",
- "user/vendors/vendor-management",
- "user/vendors/commission-rates",
- "user/vendors/vendor-payouts",
- "user/vendors/multi-vendor-checkout"
- ],
- "icon": "store"
+ "user/reports/reports"
+ ]
},
{
"group": "Settings",
@@ -1048,13 +1139,21 @@
"user/settings/shipping-methods",
"user/settings/tax",
"user/settings/locations",
- "user/settings/metafields"
+ "user/settings/metafields",
+ "user/settings/returns-configuration",
+ "user/settings/product-types",
+ "user/settings/package-types",
+ "user/settings/integrations",
+ "user/settings/api-keys",
+ "user/settings/webhooks",
+ "user/settings/allowed-origins"
],
"icon": "settings"
},
{
"group": "How-to Guides",
"pages": [
+ "user/how-to/selling-to-businesses",
"user/how-to/multi-currency-pricing",
"user/how-to/multiple-languages",
"user/how-to/multi-region-pricing",
@@ -2555,6 +2654,7 @@
{
"group": "How-to Guides",
"pages": [
+ "user/how-to/selling-to-businesses",
"user/how-to/multi-currency-pricing",
"user/how-to/multiple-languages",
"user/how-to/multi-region-pricing",
@@ -2567,56 +2667,71 @@
},
{
"group": "Products",
+ "icon": "package",
"pages": [
- {
- "group": "Create & Edit Products",
- "pages": [
- "user/products/creating-products",
- "user/products/deleting-products",
- "user/products/editing-products",
- "user/products/editing-multi-variant-products",
- "user/products/cloning-products"
- ]
- },
- {
- "group": "Manage Products",
- "pages": [
- "user/manage-products/search-products",
- "user/manage-products/bulk-product-operations",
- "user/manage-products/price-lists",
- "user/manage-products/export-products",
- "user/manage-products/import-products",
- "user/manage-products/multi-currency-import-export",
- "user/manage-products/product-import-file-template",
- "user/manage-products/translations",
- "user/manage-products/stock-levels",
- "user/manage-products/stock-transfers",
- "user/manage-products/product-taxonomies",
- "user/manage-products/product-options",
- "user/manage-products/product-metafields"
- ]
- }
+ "user/products/creating-products",
+ "user/products/editing-products",
+ "user/products/editing-multi-variant-products",
+ "user/products/cloning-products",
+ "user/products/deleting-products",
+ "user/manage-products/search-products",
+ "user/manage-products/bulk-product-operations",
+ "user/products/categories",
+ "user/products/collections",
+ "user/manage-products/product-options",
+ "user/manage-products/product-metafields",
+ "user/manage-products/import-products",
+ "user/manage-products/export-products",
+ "user/manage-products/product-import-file-template",
+ "user/manage-products/multi-currency-import-export"
+ ]
+ },
+ {
+ "group": "Inventory",
+ "icon": "warehouse",
+ "pages": [
+ "user/inventory/stock-levels",
+ "user/inventory/stock-transfers",
+ "user/inventory/purchase-orders",
+ "user/inventory/suppliers"
+ ]
+ },
+ {
+ "group": "Pricing",
+ "icon": "tag",
+ "pages": [
+ "user/pricing/price-lists"
+ ]
+ },
+ {
+ "group": "Catalogs",
+ "icon": "book-marked",
+ "pages": [
+ "user/catalogs/catalogs"
+ ]
+ },
+ {
+ "group": "Translations",
+ "icon": "languages",
+ "pages": [
+ "user/translations/translations"
]
},
{
"group": "Orders",
"pages": [
- "user/orders/order-states",
+ "user/orders/order-statuses",
"user/orders/processing-orders",
"user/orders/creating-orders",
"user/orders/editing-orders",
- "user/orders/order-adjustments",
+ "user/orders/discounts-fees-and-taxes",
"user/orders/exporting-orders",
"user/orders/cancelling-orders",
"user/orders/refunding-orders",
- "user/orders/searching-orders"
- ]
- },
- {
- "group": "Returns",
- "pages": [
- "user/settings/returns-configuration",
- "user/returns/returns-processing"
+ "user/orders/searching-orders",
+ "user/orders/returns",
+ "user/orders/exchanges",
+ "user/orders/claims"
]
},
{
@@ -2627,7 +2742,21 @@
"user/customers/edit-customer",
"user/customers/searching-customers",
"user/customers/exporting-customers",
- "user/customers/customer-groups"
+ "user/customers/customer-groups",
+ "user/customers/companies"
+ ]
+ },
+ {
+ "group": "Sellers",
+ "icon": "store",
+ "pages": [
+ "user/sellers/sellers",
+ "user/sellers/onboarding",
+ "user/sellers/managing-sellers",
+ "user/sellers/products",
+ "user/sellers/orders",
+ "user/sellers/commission-rates",
+ "user/sellers/payouts"
]
},
{
@@ -2648,16 +2777,10 @@
]
},
{
- "group": "Vendors",
+ "group": "Reports",
+ "icon": "chart-column",
"pages": [
- "user/settings/marketplace",
- "user/vendors/vendor-onboarding-shopify",
- "user/vendors/vendor-onboarding-woocommerce",
- "user/vendors/vendor-onboarding-manual",
- "user/vendors/vendor-management",
- "user/vendors/commission-rates",
- "user/vendors/vendor-payouts",
- "user/vendors/multi-vendor-checkout"
+ "user/reports/reports"
]
},
{
@@ -2674,7 +2797,14 @@
"user/settings/shipping-methods",
"user/settings/tax",
"user/settings/locations",
- "user/settings/metafields"
+ "user/settings/metafields",
+ "user/settings/returns-configuration",
+ "user/settings/product-types",
+ "user/settings/package-types",
+ "user/settings/integrations",
+ "user/settings/api-keys",
+ "user/settings/webhooks",
+ "user/settings/allowed-origins"
]
},
{
diff --git a/docs/images/user/orders/order-adjustments/1-orders-tab.png b/docs/images/user/orders/order-adjustments/1-orders-tab.png
deleted file mode 100644
index 68b7fa29eb..0000000000
Binary files a/docs/images/user/orders/order-adjustments/1-orders-tab.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/2-order-page.png b/docs/images/user/orders/order-adjustments/2-order-page.png
deleted file mode 100644
index c907fdb68f..0000000000
Binary files a/docs/images/user/orders/order-adjustments/2-order-page.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/3-new-adjustment.png b/docs/images/user/orders/order-adjustments/3-new-adjustment.png
deleted file mode 100644
index 37d6fea136..0000000000
Binary files a/docs/images/user/orders/order-adjustments/3-new-adjustment.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/4-refund.png b/docs/images/user/orders/order-adjustments/4-refund.png
deleted file mode 100644
index 03fb67085a..0000000000
Binary files a/docs/images/user/orders/order-adjustments/4-refund.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/5-refund-form.png b/docs/images/user/orders/order-adjustments/5-refund-form.png
deleted file mode 100644
index d1876c3343..0000000000
Binary files a/docs/images/user/orders/order-adjustments/5-refund-form.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/6-new-payment.png b/docs/images/user/orders/order-adjustments/6-new-payment.png
deleted file mode 100644
index 1a2155594c..0000000000
Binary files a/docs/images/user/orders/order-adjustments/6-new-payment.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/7-payment-form.png b/docs/images/user/orders/order-adjustments/7-payment-form.png
deleted file mode 100644
index 5fd25be53e..0000000000
Binary files a/docs/images/user/orders/order-adjustments/7-payment-form.png and /dev/null differ
diff --git a/docs/images/user/orders/order-adjustments/8-close-adjustment.png b/docs/images/user/orders/order-adjustments/8-close-adjustment.png
deleted file mode 100644
index 3c08b2496d..0000000000
Binary files a/docs/images/user/orders/order-adjustments/8-close-adjustment.png and /dev/null differ
diff --git a/docs/images/user/orders/order-states/orders-tab.png b/docs/images/user/orders/order-statuses/orders-tab.png
similarity index 100%
rename from docs/images/user/orders/order-states/orders-tab.png
rename to docs/images/user/orders/order-statuses/orders-tab.png
diff --git a/docs/images/user/products/taxonomies/1.tab.png b/docs/images/user/products/categories/1.tab.png
similarity index 100%
rename from docs/images/user/products/taxonomies/1.tab.png
rename to docs/images/user/products/categories/1.tab.png
diff --git a/docs/images/user/products/taxonomies/10.add-products.png b/docs/images/user/products/categories/10.add-products.png
similarity index 100%
rename from docs/images/user/products/taxonomies/10.add-products.png
rename to docs/images/user/products/categories/10.add-products.png
diff --git a/docs/images/user/products/taxonomies/11.select-products.png b/docs/images/user/products/categories/11.select-products.png
similarity index 100%
rename from docs/images/user/products/taxonomies/11.select-products.png
rename to docs/images/user/products/categories/11.select-products.png
diff --git a/docs/images/user/products/taxonomies/12.products-added.png b/docs/images/user/products/categories/12.products-added.png
similarity index 100%
rename from docs/images/user/products/taxonomies/12.products-added.png
rename to docs/images/user/products/categories/12.products-added.png
diff --git a/docs/images/user/products/taxonomies/13.sort-order.png b/docs/images/user/products/categories/13.sort-order.png
similarity index 100%
rename from docs/images/user/products/taxonomies/13.sort-order.png
rename to docs/images/user/products/categories/13.sort-order.png
diff --git a/docs/images/user/products/taxonomies/14.manual-ordering.png b/docs/images/user/products/categories/14.manual-ordering.png
similarity index 100%
rename from docs/images/user/products/taxonomies/14.manual-ordering.png
rename to docs/images/user/products/categories/14.manual-ordering.png
diff --git a/docs/images/user/products/taxonomies/15.nested-taxons.png b/docs/images/user/products/categories/15.nested-categories.png
similarity index 100%
rename from docs/images/user/products/taxonomies/15.nested-taxons.png
rename to docs/images/user/products/categories/15.nested-categories.png
diff --git a/docs/images/user/products/taxonomies/16.taxonomy-tree.png b/docs/images/user/products/categories/16.category-tree.png
similarity index 100%
rename from docs/images/user/products/taxonomies/16.taxonomy-tree.png
rename to docs/images/user/products/categories/16.category-tree.png
diff --git a/docs/images/user/products/taxonomies/17.move-taxons.png b/docs/images/user/products/categories/17.move-categories.png
similarity index 100%
rename from docs/images/user/products/taxonomies/17.move-taxons.png
rename to docs/images/user/products/categories/17.move-categories.png
diff --git a/docs/images/user/products/taxonomies/18.edit-taxonomies.png b/docs/images/user/products/categories/18.edit-categories.png
similarity index 100%
rename from docs/images/user/products/taxonomies/18.edit-taxonomies.png
rename to docs/images/user/products/categories/18.edit-categories.png
diff --git a/docs/images/user/products/taxonomies/19.renamed-taxonomy.png b/docs/images/user/products/categories/19.renamed-category.png
similarity index 100%
rename from docs/images/user/products/taxonomies/19.renamed-taxonomy.png
rename to docs/images/user/products/categories/19.renamed-category.png
diff --git a/docs/images/user/products/taxonomies/2.new-taxonomy.png b/docs/images/user/products/categories/2.new-category.png
similarity index 100%
rename from docs/images/user/products/taxonomies/2.new-taxonomy.png
rename to docs/images/user/products/categories/2.new-category.png
diff --git a/docs/images/user/products/taxonomies/20.taxonomy-created.png b/docs/images/user/products/categories/20.category-created.png
similarity index 100%
rename from docs/images/user/products/taxonomies/20.taxonomy-created.png
rename to docs/images/user/products/categories/20.category-created.png
diff --git a/docs/images/user/products/taxonomies/3.new-taxon.png b/docs/images/user/products/categories/3.new-category.png
similarity index 100%
rename from docs/images/user/products/taxonomies/3.new-taxon.png
rename to docs/images/user/products/categories/3.new-category.png
diff --git a/docs/images/user/products/taxonomies/4.taxon-type.png b/docs/images/user/products/categories/4.category-type.png
similarity index 100%
rename from docs/images/user/products/taxonomies/4.taxon-type.png
rename to docs/images/user/products/categories/4.category-type.png
diff --git a/docs/images/user/products/taxonomies/5.automatic-taxons.png b/docs/images/user/products/categories/5.automatic-categories.png
similarity index 100%
rename from docs/images/user/products/taxonomies/5.automatic-taxons.png
rename to docs/images/user/products/categories/5.automatic-categories.png
diff --git a/docs/images/user/products/taxonomies/6.condition-values.png b/docs/images/user/products/categories/6.condition-values.png
similarity index 100%
rename from docs/images/user/products/taxonomies/6.condition-values.png
rename to docs/images/user/products/categories/6.condition-values.png
diff --git a/docs/images/user/products/taxonomies/7.navigation.png b/docs/images/user/products/categories/7.navigation.png
similarity index 100%
rename from docs/images/user/products/taxonomies/7.navigation.png
rename to docs/images/user/products/categories/7.navigation.png
diff --git a/docs/images/user/products/taxonomies/8.navigation-filtering.png b/docs/images/user/products/categories/8.navigation-filtering.png
similarity index 100%
rename from docs/images/user/products/taxonomies/8.navigation-filtering.png
rename to docs/images/user/products/categories/8.navigation-filtering.png
diff --git a/docs/images/user/products/taxonomies/9.seo.png b/docs/images/user/products/categories/9.seo.png
similarity index 100%
rename from docs/images/user/products/taxonomies/9.seo.png
rename to docs/images/user/products/categories/9.seo.png
diff --git a/docs/integrations/payments/stripe-connect.mdx b/docs/integrations/payments/stripe-connect.mdx
new file mode 100644
index 0000000000..5d39774474
--- /dev/null
+++ b/docs/integrations/payments/stripe-connect.mdx
@@ -0,0 +1,100 @@
+---
+title: "Stripe Connect for Marketplaces"
+sidebarTitle: Stripe Connect
+description: "Pay your sellers through Stripe Connect — hosted Express onboarding, a transfer to each seller as their goods ship, and settlements confirmed by webhook."
+---
+
+Stripe Connect is the payout provider that ships with Spree's Stripe integration. You charge customers on your own Stripe account, each seller holds a connected Express account, and Spree moves every seller's share across as their orders ship. Read [how the payout ledger works](/developer/core-concepts/sellers#payouts) first — this page covers only what Stripe adds to it.
+
+## Prerequisites
+
+- A [Stripe payment method](/integrations/payments/stripe) on the store, active, with its keys entered. Connect uses the same account and credentials — there is nothing separate to connect.
+- Connect enabled on that Stripe account (Stripe Dashboard → **Connect** → Get started). Spree creates Express accounts, so pick the platform profile Stripe suggests for marketplaces.
+- Sellers on the store. If you have none yet, [invite one](/user/sellers/onboarding).
+
+## Turn it on
+
+Go to **Settings → Payouts** and choose **Stripe Connect** as the payout provider. The option is only offered once an active Stripe payment method exists on the store. The schedule and minimum on the same page decide when Spree settles each seller.
+
+The same setting through the Admin API:
+
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: providers } = await adminClient.payoutProviders.list()
+// find the row with id 'SpreeStripe::PayoutProvider' — `available` says whether this store can use it
+
+await adminClient.store.update({
+ preferred_payout_provider: 'SpreeStripe::PayoutProvider',
+ preferred_default_payouts_schedule_interval: 'weekly',
+ preferred_default_minimum_payout_amount: 50,
+})
+```
+
+```bash cURL
+curl -X PATCH https://your-store.com/api/v3/admin/store \
+ -H "X-Spree-API-Key: sk_xxx" \
+ -H "Content-Type: application/json" \
+ -d '{"preferred_payout_provider": "SpreeStripe::PayoutProvider", "preferred_default_payouts_schedule_interval": "weekly", "preferred_default_minimum_payout_amount": 50}'
+```
+
+</CodeGroup>
+
+Then add the **Payout account** row to your [seller requirements](/user/sellers/onboarding) so a seller cannot be approved before Stripe can pay them. Without it a seller is approved, sells, and their earnings sit pending until they connect an account.
+
+## Seller onboarding
+
+A seller connects from their panel. The panel asks Spree for a link, Spree creates an Express account for the seller if they have none and asks Stripe for a hosted onboarding link, and the seller lands on Stripe's own pages to give identity and bank details. Spree never handles either.
+
+The account is created with the platform paying Stripe's fees and owning disputes (what makes this a marketplace), the transfers capability requested, the Express dashboard, and — deliberately — a **manual payout schedule**. Spree decides when a seller is settled, so Stripe must not also be paying their balance out on a clock of its own.
+
+The seller's account id is stored as an external reference on the seller under the `stripe` system, so a marketplace that later changes providers keeps it on record.
+
+Three things are worth knowing about "done":
+
+- **Stripe decides, not the form.** A seller who finished typing may still be under review for days. The onboarding checklist asks Stripe each time it is rendered, and shows the seller one of three states: something to do, being checked, or refused — with Stripe's own reason where it gives one.
+- **`account.updated` is the signal.** When Stripe flips `payouts_enabled`, the webhook stamps the seller payable and immediately sends any earnings that were waiting. It can also flip back — expired documents, a closed account — and Spree then stops crediting the seller rather than promise money nothing can send.
+- **The stamp is a cache.** If the webhook never arrived (a local tunnel that was down, an endpoint not yet registered), the next checklist render asks Stripe directly and corrects it.
+
+## Webhooks
+
+Connect events arrive on a separate endpoint from your payment events, because Stripe scopes them separately: events raised inside sellers' connected accounts come on their own subscription with their own signing secret. Spree registers it with Stripe the first time a seller asks for an onboarding link, at:
+
+```
+https://your-store.com/api/v3/webhooks/payouts/<payment method id>
+```
+
+subscribed to `account.updated`, `payout.paid` and `payout.failed`. The endpoint id and signing secret are stored on the payment method. Nothing to do in production.
+
+For local development Stripe cannot reach your machine, so forward the connected-account events with the Stripe CLI and give Spree the secret it prints:
+
+```bash
+stripe listen --forward-connect-to localhost:3000/api/v3/webhooks/payouts/<payment method id>
+export STRIPE_CONNECT_SIGNING_SECRET=whsec_...
+```
+
+`STRIPE_SIGNING_SECRET` covers the payments endpoint the same way; the two are different secrets.
+
+## How the money moves
+
+**On fulfillment**, Spree records the seller's earning — their sale less commission — and creates a Stripe transfer to their connected account. The transfer names the customer's charge as its `source_transaction`, so it settles when that charge does rather than out of your platform balance: a marketplace should not have to float its sellers. The order number goes on the transfer group, and the ledger row's id on the metadata, so both sides reconcile. A seller who is not payable yet keeps the earning pending; it is sent when they become payable, or on the hourly retry.
+
+**On the schedule**, a sweep batches the seller's confirmed earnings into a payout and asks Stripe — acting as the connected account — to pay the seller's bank. The payout stays **pending** in Spree with Stripe's `po_…` id as its reference until `payout.paid` arrives, which completes it and debits the seller's balance. `payout.failed` marks it failed and releases the earnings for the next sweep.
+
+**On a refund**, Spree writes a reversal row against the seller so the books are right. The Stripe transfer itself is not reversed in open source, and a negative balance is not netted against future earnings — that money operation is Spree Enterprise.
+
+Every Stripe call carries an idempotency key derived from the ledger row, so a retried request finds the movement it already made. When Stripe's answer is lost — a timeout, a 5xx — Spree parks the row as **unresolved** instead of retrying, because the key only protects a retry for as long as Stripe remembers it. Resolve those against the Stripe Dashboard: mark the payout complete with its reference if the money went, or fail it if it did not.
+
+## What sellers see
+
+Their panel shows earnings as transfers, settlements as payouts, and a balance per currency — read-only, since Spree and Stripe write both sides. For the bank side (what Stripe actually paid out, and to which account) they use the Express dashboard Stripe gives every connected account.
+
+## Test mode
+
+Use test keys on the Stripe payment method and everything above runs against Stripe's test environment, including Express onboarding with Stripe's test identity data and simulated `payout.paid` events. Connect must be enabled on the test account too.
+
+## Related
+
+- [Payouts](/user/sellers/payouts) — the operator's view: balances, the queue, marking payouts complete
+- [Seller payouts](/developer/providers/payouts) — the provider contract, if Stripe is not your rails
+- [Stripe payments](/integrations/payments/stripe) — the payment method Connect builds on
diff --git a/docs/integrations/payments/stripe.mdx b/docs/integrations/payments/stripe.mdx
index 37e50c4bdf..e81e1b4195 100644
--- a/docs/integrations/payments/stripe.mdx
+++ b/docs/integrations/payments/stripe.mdx
@@ -1,12 +1,12 @@
---
title: "Connect Stripe payments to Spree Commerce"
sidebarTitle: Stripe
-description: "Set up Spree's native Stripe integration to accept cards and alternative payment methods, automate payouts, and power marketplace split payments on Enterprise."
+description: "Set up Spree's native Stripe integration to accept cards and alternative payment methods, and pay marketplace sellers through Stripe Connect."
---
Stripe is a widely used payment processor that enables secure and seamless transactions for online businesses. It supports multiple payment methods, automates payouts, and ensures a smooth checkout experience for customers.
-<Tip>In [Spree Enterprise Edition](https://spreecommerce.org/pricing/), Stripe can also be used to power marketplace payments, enabling automated vendor payouts, split payments, and secure transaction handling.</Tip>
+<Tip>Running a marketplace? The same Stripe account pays your sellers through [Stripe Connect](/integrations/payments/stripe-connect).</Tip>
## Installation
@@ -123,13 +123,4 @@ See [<u>Settings → Tax</u>](/user/settings/tax) for more on configuring tax ra
## Stripe Connect for Marketplaces
-Spree Commerce [Enterprise Edition](https://spreecommerce.org/spree-commerce-version-comparison-community-edition-vs-enterprise-edition/) comes with a fully automated Stripe Connect integration for [multi-vendor marketplace use cases](https://spreecommerce.org/marketplace-ecommerce/):
-
-- Automated split payments between marketplace and vendors
-- Support for multiple payment methods including cards and digital wallets
-- Configurable marketplace fees and commission structures
-- Automated payouts to vendors
-- Comprehensive transaction reporting
-- Built-in fraud prevention tools
-
-Feel free to [reach out](https://spreecommerce.org/get-started/) to learn more.
+Stripe Connect is the payout provider that ships with this integration: each seller onboards to an Express account through Stripe's hosted pages, their share of every order is transferred as it ships, and settlements are confirmed by webhook. Setup and the money flow are on their own page — [Stripe Connect for marketplaces](/integrations/payments/stripe-connect).
diff --git a/docs/use-case/b2b/b2b-admin-capabilities.mdx b/docs/use-case/b2b/b2b-admin-capabilities.mdx
index 7a15f66c58..15b018fe3c 100644
--- a/docs/use-case/b2b/b2b-admin-capabilities.mdx
+++ b/docs/use-case/b2b/b2b-admin-capabilities.mdx
@@ -17,7 +17,7 @@ The following admin capabilities are available out of the box.
### Pricing
-- Build [<u>**Price Lists**</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) with Customer Group rules to ensure each segment always sees their correct contracted pricing
+- Assign a [<u>**Catalog**</u>](https://spreecommerce.org/docs/user/catalogs/catalogs) to each customer group or company, so every segment always sees their correct contracted pricing
- Combine Customer Group and Market rules on a single price list to deliver region-specific wholesale pricing in the correct currency
- Set volume pricing rules that activate based on order quantity
- Schedule price lists for a defined period or leave them open-ended
diff --git a/docs/use-case/b2b/b2b-capabilities.mdx b/docs/use-case/b2b/b2b-capabilities.mdx
index d24add95d0..3e5e15a997 100644
--- a/docs/use-case/b2b/b2b-capabilities.mdx
+++ b/docs/use-case/b2b/b2b-capabilities.mdx
@@ -16,12 +16,12 @@ The following B2B capabilities are available in Spree's free Community Edition a
Price Lists let you create and manage custom pricing for specific customer segments. You can:
- Offer different prices to different buyer groups (e.g., retail vs. wholesale vs. distributor tiers)
-- Combine rules — target a specific customer group *and* a specific market — to apply regional wholesale pricing automatically
+- Give a market its own catalog, and assign catalogs to customer groups and companies, to apply regional wholesale pricing automatically
- Apply volume pricing rules that activate based on order quantity
- Schedule time-limited pricing or leave it open-ended
- Manage everything without duplicating product records or writing any code
-See [<u>Products → Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for the full reference.
+See [<u>Products → Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) for the full reference.
### Customer Groups
@@ -49,7 +49,7 @@ Spree supports gated storefront configurations that require buyers to log in bef
### What You Can Build with Community Edition
-With [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists), [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups), [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets), and gated storefronts, you can build real B2B scenarios today:
+With [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists), [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups), [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets), and gated storefronts, you can build real B2B scenarios today:
- **Wholesale pricing** — retail and wholesale customers on the same storefront, each seeing their own contracted prices
- **Multi-tier distributor pricing** — independent price lists for different distributor tiers or named accounts
diff --git a/docs/use-case/b2b/b2b-commerce-model.mdx b/docs/use-case/b2b/b2b-commerce-model.mdx
index 3eca86bb67..9be3de1c99 100644
--- a/docs/use-case/b2b/b2b-commerce-model.mdx
+++ b/docs/use-case/b2b/b2b-commerce-model.mdx
@@ -43,23 +43,21 @@ B2B platforms typically feature:
- **Regional Wholesale Expansion** — A single storefront serves wholesale buyers in multiple markets, each seeing wholesale prices in their local currency.
- **B2B2C Hybrid Stores** — Retail and trade customers shop side-by-side on one storefront, with pricing automatically applied based on account type.
- **Trade-Only Portals** — Gated storefronts where unapproved visitors cannot see products or prices until their account has been verified.
-- **Buyer Organizations** — Multiple users (buyers, managers, finance) operate under one company account with shared order history. *(Coming in Spree 6.0)*
+- **Buyer Organizations** — Multiple buyers operate under one company account, with its sub-units, address book and shared order history.
## How Spree Supports B2B Commerce
### Community Edition
-With [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists), [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups), [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets), and gated storefronts, you can configure working B2B scenarios directly in the Spree admin — no development required:
+With [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists), [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups), [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets), and gated storefronts, you can configure working B2B scenarios directly in the Spree admin — no development required:
- Offer wholesale pricing to registered trade accounts while retail visitors see standard prices
- Create independent price lists for different wholesalers or distributor tiers
-- Combine Customer Group and Market rules to deliver region-specific wholesale pricing in the correct currency
+- Assign a catalog to a customer group or a company to deliver that buyer their own assortment and prices, in their own currency
- Gate your storefront so only approved, logged-in buyers can browse products and prices
- Run combined B2C and B2B from a single storefront, with no separate portal or login system needed
-### Coming in Spree 6.0
-
-The open-source roadmap includes buyer organizations (company accounts with locations and contacts) and B2B catalogs (curated per-segment product assortments).
+Buyer organizations and catalogs are part of this — [<u>companies</u>](https://spreecommerce.org/docs/user/customers/companies) model a business buyer and its sub-units, and a [<u>catalog</u>](https://spreecommerce.org/docs/user/catalogs/catalogs) is the agreement that says what they see and what they pay.
### Enterprise Edition
@@ -70,7 +68,7 @@ For complex procurement requirements, Spree Enterprise Edition adds role-based o
- **Custom Pricing Logic** — B2B pricing often includes tiers, discounts, and customer-specific contracts. Spree's Price Lists engine handles this natively in the admin, no development required.
- **Multi-Region Complexity** — Serving wholesale buyers across multiple markets, currencies, and tax regimes requires flexible pricing infrastructure. Spree's Markets and Price List rules handle this without custom code.
- **Gated Access** — Restricting catalog and pricing visibility to approved accounts is a standard requirement for trade portals. This is supported out of the box in Community Edition.
-- **Role-Based Buyer Structures** — Supporting multi-user organizations with shared accounts is coming in Spree 6.0 for open-source.
+- **Multi-User Organizations** — A company account with several buyers, its own address book and shared order history is supported in Community Edition. Role-based approval chains are Enterprise Edition.
- **ERP & Fulfillment Integration** — Role-based approval chains and pre-built ERP connectors are available in Enterprise Edition.
<Columns cols={2}>
diff --git a/docs/user/catalogs/catalogs.mdx b/docs/user/catalogs/catalogs.mdx
new file mode 100644
index 0000000000..87d358eba4
--- /dev/null
+++ b/docs/user/catalogs/catalogs.mdx
@@ -0,0 +1,85 @@
+---
+title: "Catalogs"
+description: "Give a company or customer group its own product range, prices and order terms."
+---
+
+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.
+
+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.
+
+## The two ways a catalog is used
+
+The single most useful thing to understand is that an **empty product list means something different from a full one**.
+
+<Tabs>
+ <Tab title="Pricing overlay">
+ **No products added.** Nothing is hidden — the audience browses your normal range — but they pay this catalog's prices.
+
+ 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.
+
+ This is what you want for a buyer with a contracted range — the twelve SKUs in their agreement and nothing else.
+ </Tab>
+</Tabs>
+
+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.
+
+## Creating a catalog
+
+**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.
+
+You can also create a bare catalog and fill it in afterwards — the same cards are on the catalog page.
+
+## Who sees it
+
+A catalog reaches nobody until you assign an audience. Assign it to:
+
+- a **company** — which covers that company and every division beneath it, or
+- a **customer group**.
+
+<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>
+
+## What they pay
+
+A catalog prices through its own price list, set up on the catalog page. Each product row shows where its price comes from:
+
+| 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 |
+
+A percentage is the quickest way to express "this customer gets 15% off everything", with no rows to maintain as your prices change.
+
+<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>
+
+## Order terms
+
+Catalogs can also carry the commercial terms of the agreement — how much a buyer must order:
+
+- 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
+
+Leave them blank and buyers may order any quantity, any total.
+
+## Going live
+
+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.
+
+**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.
+
+<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>
+
+## Related
+
+- [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
diff --git a/docs/user/customers/companies.mdx b/docs/user/customers/companies.mdx
new file mode 100644
index 0000000000..fdc1281e89
--- /dev/null
+++ b/docs/user/customers/companies.mdx
@@ -0,0 +1,72 @@
+---
+title: "Companies"
+description: "Set up business customers as organizations — with members, delivery sites, tax registrations and their own pricing."
+---
+
+A company is a business customer. Where a retail customer is one person, a business buyer is a person acting *for* an organization — one with other buyers, several delivery sites, a VAT number, and a finance team who wants to see everything anyone ordered.
+
+Companies model that. And because real organizations are not flat, a company can be a **tree**: a parent with subsidiaries, divisions or regional units, each with its own people and addresses.
+
+To manage companies, open **Companies** under Customers.
+
+## Companies and divisions
+
+Every node in the tree is one of two kinds. The difference is about tax, not hierarchy:
+
+| Kind | What it is |
+|---|---|
+| Company | A legal entity of its own, with its own tax registrations |
+| Division | An organizational unit inside a legal entity. It shares that entity's tax identity |
+
+The top of a tree is always a company. Trees go up to five levels deep.
+
+Use **Add sub-unit** on a company's page to build the tree beneath it. Delivery sites are *not* sub-units — ten warehouses do not mean ten nodes. Nodes are for organizational and legal structure; where goods go is an address.
+
+## Members
+
+A member is a customer who can buy for the company. Add one with **Add member** and an email address:
+
+- An email that already has a customer account becomes a member straight away.
+- An unknown email becomes an **invitation**, valid for 30 days, and the person gets an email with a link. Accepting it either signs them in or creates their account, and ends as a membership.
+
+Pending invitations are listed on the company page until they are accepted or you revoke them.
+
+Membership reaches downward. Someone added at "Acme Europe" can buy for every division beneath it without being added to each one. Add someone at the top of the tree and they cover the whole group.
+
+<Note>
+In Spree open source, every member can do everything within their standing — buy, see the orders of their node and everything below it, and manage the address book and members. Roles, order approvals and spending limits are part of Spree Enterprise.
+</Note>
+
+Removing a member stops them buying for the company. Their customer account is not affected.
+
+## Address book
+
+A company keeps its own addresses — ship-to sites and billing addresses — separate from any individual member's. Each is labelled, and one of each kind can be marked as the default the buyer starts from at checkout.
+
+## Tax
+
+Tax registrations and exemption certificates belong to legal entities only, so a division's page has no tax cards. A division's purchases are taxed through its legal entity — the nearest company above it.
+
+That lookup stops at the first company, whether or not it holds a registration. A subsidiary with no VAT number of its own therefore has none: it never quietly borrows its parent's, because in most places that would be a false declaration.
+
+Exemption certificates are scoped to the country or state that issued them, and stop applying when they expire.
+
+## Purchase order numbers
+
+Turn on **Require a PO number** and buyers from the company must supply their purchase order number before they can check out. The number is kept on the order, shown on the order page and in the confirmation email, and can be searched for.
+
+## Giving a company its own range and prices
+
+What a company sees and pays is set through a [Catalog](/user/catalogs/catalogs) assigned to it. Assigning to a node covers everything beneath it, so one assignment at the top prices the whole group.
+
+Company assignments win over customer-group ones. A buyer whose company — or any company above it — has a catalog gets those catalogs, and their customer groups are not consulted.
+
+## Deleting a company
+
+Deleting a node removes its whole subtree. It is refused once any order exists beneath it — order history is kept, even when an org chart is tidied up.
+
+## Related
+
+- [Selling to businesses](/user/how-to/selling-to-businesses) — the whole B2B setup, end to end
+- [Catalogs](/user/catalogs/catalogs) — what a company sees and pays
+- [Customer Groups](/user/customers/customer-groups) — the other audience a catalog can be assigned to
diff --git a/docs/user/customers/customer-groups.mdx b/docs/user/customers/customer-groups.mdx
index b2ac4414ee..7405daf33f 100644
--- a/docs/user/customers/customer-groups.mdx
+++ b/docs/user/customers/customer-groups.mdx
@@ -10,7 +10,7 @@ Customer Groups let you segment your customers into defined lists, which can the
On their own, groups are just lists. The value comes from what you attach to them — and how Spree uses group membership to automatically personalise what each buyer sees.
-**Pricing tiers** — By pairing a customer group with a [<u>Price List</u>](https://spreecommerce.org/docs/user/manage-products/price-lists), every member of that group automatically sees their correct prices the moment they log in. The Price List can override base prices across your entire catalog, or just on specific products. You can have as many groups and price lists as you need — one per customer tier, one per named account, or one per region — and Spree applies the right one without any manual work. When you add a new customer to a group, they inherit the pricing immediately.
+**Pricing tiers** — By assigning a [<u>Catalog</u>](https://spreecommerce.org/docs/user/catalogs/catalogs) to a customer group, every member of that group automatically sees their correct prices the moment they log in. The catalog can price your entire range, or restrict the group to specific products at their own prices. You can have as many groups and catalogs as you need — one per customer tier, one per named account — and Spree applies the right one without any manual work. When you add a new customer to a group, they inherit the pricing immediately. A buyer whose company has a catalog of its own gets that instead: company assignments win over group ones.
**Exclusive promotions** — Promotion rules can be restricted to specific customer groups, so a discount code or automatic offer only applies to the customers it's meant for. Useful for loyalty rewards, trade-only offers, or onboarding incentives for new wholesale accounts.
@@ -24,7 +24,7 @@ An industrial supplier runs three buyer types from a single storefront:
- **Dealer** — authorized dealers with a deeper discount tier and access to exclusive product bundles
- **VIP** — high-volume accounts with individually negotiated pricing
-Each group has its own Price List. When a buyer logs in, Spree checks their group membership and applies the correct prices automatically.
+Each group is assigned its own catalog. When a buyer logs in, Spree checks their group membership and applies the matching catalog automatically.
<Note>For a full walkthrough of this setup, see [<u>Set Up Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing).</Note>
@@ -71,5 +71,5 @@ To remove customers from a group, select the checkboxes next to the customers yo
## Next Steps
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — create pricing rules that target specific customer groups
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — create pricing rules that target specific customer groups
- [<u>Set Up Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — step-by-step guide to building wholesale pricing tiers with customer groups
diff --git a/docs/user/how-to/multi-currency-pricing.mdx b/docs/user/how-to/multi-currency-pricing.mdx
index 750856def1..4e5b23f93e 100644
--- a/docs/user/how-to/multi-currency-pricing.mdx
+++ b/docs/user/how-to/multi-currency-pricing.mdx
@@ -76,4 +76,4 @@ If a product does not appear after switching to EUR, check that a EUR price has
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — charge different prices within the same currency for different markets
- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — reference for setting up price overrides and rules
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — reference for setting up price overrides and rules
diff --git a/docs/user/how-to/multi-region-pricing.mdx b/docs/user/how-to/multi-region-pricing.mdx
index 4a52d09153..0eea9bf5d9 100644
--- a/docs/user/how-to/multi-region-pricing.mdx
+++ b/docs/user/how-to/multi-region-pricing.mdx
@@ -14,7 +14,7 @@ In this guide, we'll walk through a common scenario — a store with an existing
Before you start, you should have:
- At least one active market already configured with EUR as its currency. In this example, a Germany market with EUR is already set up and your products have EUR prices.
-- Familiarity with how Price Lists work. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+- Familiarity with how Price Lists work. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) for a full reference.
## 1. Create Markets for France and Spain
@@ -101,5 +101,5 @@ If a product shows the base EUR price instead of the regional price, check that:
## Next Steps
- [<u>Set Up Multi-Currency Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing) — sell in different currencies for different regions
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, volume pricing, and customer group pricing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, volume pricing, and customer group pricing
- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets
diff --git a/docs/user/how-to/multiple-languages.mdx b/docs/user/how-to/multiple-languages.mdx
index 86892f195c..10497c6a91 100644
--- a/docs/user/how-to/multiple-languages.mdx
+++ b/docs/user/how-to/multiple-languages.mdx
@@ -92,5 +92,5 @@ Repeat this process for each policy you want to make available in additional lan
## Next Steps
- [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring markets and locales
-- [<u>Products → Translations</u>](https://spreecommerce.org/docs/user/manage-products/translations) — full reference for the translations overview and bulk importer
+- [<u>Products → Translations</u>](https://spreecommerce.org/docs/user/translations/translations) — full reference for the translations overview and bulk importer
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — configure market-specific pricing alongside your language setup
diff --git a/docs/user/how-to/regional-volume.mdx b/docs/user/how-to/regional-volume.mdx
index 07b0a900ae..0aead7ae9d 100644
--- a/docs/user/how-to/regional-volume.mdx
+++ b/docs/user/how-to/regional-volume.mdx
@@ -99,5 +99,5 @@ If the expected discount is not being applied, check that:
- [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing) — volume discounts without a regional split
- [<u>Set Up Regional Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/regional-wholesale) — combine market and customer group rules for regional wholesale pricing
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, match logic, and price editing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, match logic, and price editing
- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets
diff --git a/docs/user/how-to/regional-wholesale.mdx b/docs/user/how-to/regional-wholesale.mdx
index efe43ec97e..c90e0945cd 100644
--- a/docs/user/how-to/regional-wholesale.mdx
+++ b/docs/user/how-to/regional-wholesale.mdx
@@ -121,5 +121,5 @@ If wholesale prices are not appearing, check that:
- [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — wholesale pricing without regional splits
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — regional pricing without a wholesale overlay
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, match logic, and price editing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, match logic, and price editing
- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets
diff --git a/docs/user/how-to/schedule-sale-pricing.mdx b/docs/user/how-to/schedule-sale-pricing.mdx
index 38a8129abd..aa98b61388 100644
--- a/docs/user/how-to/schedule-sale-pricing.mdx
+++ b/docs/user/how-to/schedule-sale-pricing.mdx
@@ -25,7 +25,7 @@ Before you start, make sure:
- Your products are set up with base prices in both USD and EUR
- You have a **United States** market and an **EU** (or equivalent European) market configured. See [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) for setup instructions.
-- You're familiar with how Price Lists work. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+- You're familiar with how Price Lists work. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) for a full reference.
## 1. Create the US Black Friday Price List
@@ -107,6 +107,6 @@ If the sale price isn't showing, check that:
## Next Steps
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, scheduling, and price editing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, scheduling, and price editing
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — apply different prices per market on a permanent basis
- [<u>Set Up Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — combine market and customer group rules for B2B pricing
diff --git a/docs/user/how-to/selling-to-businesses.mdx b/docs/user/how-to/selling-to-businesses.mdx
new file mode 100644
index 0000000000..d0f8a68d58
--- /dev/null
+++ b/docs/user/how-to/selling-to-businesses.mdx
@@ -0,0 +1,101 @@
+---
+title: "Sell to Businesses"
+description: "Set up a wholesale or trade customer end to end — the company, its buyers, and the catalog that decides what they see and pay."
+---
+
+Selling to a business is different from selling to a person. The buyer acts for an organization with several people, several delivery addresses and a negotiated deal — their own prices, sometimes their own range, often a minimum order. Spree models that with two things working together:
+
+- a **Company** — who the buyer is, who else can buy for them, where goods go, and how they are taxed
+- a **Catalog** — the agreement: what that company sees, what they pay, and how much they must order
+
+This guide walks through setting up one trade customer from scratch. Once it is in place, every buyer at that company logs in to the same storefront as everyone else and simply sees their own deal.
+
+<Note>
+This is the Spree 6 way to give a customer segment its own pricing. Earlier versions did it with a **Customer Group** rule on a price list; that rule keeps working on lists that already have it, but is not offered for new lists. A catalog does the same job and more — it can also restrict the range and set order minimums.
+</Note>
+
+## Prerequisites
+
+Your products should already exist with their normal prices. If you sell in more than one currency, set base prices in each currency first — see [Set Up Multi-Currency Pricing](/user/how-to/multi-currency-pricing).
+
+## 1. Create the company
+
+Navigate to **Customers → Companies** and click **Add company**. Give it a name and keep the kind as **Company** — that is a legal entity, which is what a root always is.
+
+If the business has divisions or subsidiaries that buy separately, open the company and use **Add sub-unit** to build them beneath it. A **Division** shares its parent's tax identity; a nested **Company** has registrations of its own. Delivery sites are not sub-units — they go in the address book in a moment.
+
+See [Companies](/user/customers/companies) for the full reference.
+
+## 2. Add the buyers
+
+On the company page, click **Add member** and enter the buyer's email address.
+
+- If they already have a customer account, they become a member immediately.
+- If not, they receive an invitation by email. It is valid for 30 days, and accepting it creates their account and their membership in one step.
+
+Add people at the level they buy for. Someone added to the top-level company can buy for every division beneath it — you do not need to add them to each one.
+
+## 3. Add delivery and billing addresses
+
+Still on the company page, use **Add address** in the address book to record where goods go and where invoices go. Label each one — "Northern Warehouse", "Head Office" — and mark one ship-to and one bill-to address as the default. Buyers choose from this book at checkout instead of typing addresses.
+
+## 4. Record tax details
+
+If the company is tax-registered, add its registration — a VAT number, an ABN — on the company page. If it holds an exemption certificate, add that too, scoped to the country or state that issued it.
+
+These live on the legal entity only. A division is taxed through the company above it, so its page has no tax cards.
+
+## 5. Create their catalog
+
+Navigate to **Products → Catalogs** and click **Add catalog**. The wizard asks five things:
+
+- **Details** — name the agreement so you recognise it later, e.g. `Acme wholesale`.
+- **Audience** — assign the company you just created. Assigning the top-level company covers every division beneath it.
+- **Products** — decide what the deal covers:
+ - **Leave it empty** and the company browses your whole range at the catalog's prices.
+ - **Add products** and the company sees *only* those products.
+- **Pricing** — what they pay. Either enter an amount per product, or set a percentage adjustment — "15% off everything" — with no rows to maintain as your prices change.
+- **Review** — nothing is created until you finish.
+
+The distinction in the Products step is the one thing worth pausing on: adding the first product does not add one item to what the company sees. It switches the catalog into restricting mode, and they now see only that item.
+
+See [Catalogs](/user/catalogs/catalogs) for the full reference, including where each product's price comes from.
+
+## 6. Set order terms (optional)
+
+Open the catalog and find the **Commercial terms** card. Here you can set:
+
+- a **minimum order quantity** and **order multiple** — per product, or for the whole catalog
+- an **order minimum** — the least a whole order must come to, per currency
+
+Leave them blank and buyers may order any quantity, any total. Set them and the storefront enforces them: quantity steppers move by the multiple, and an order below the minimum cannot be placed.
+
+## 7. Require a PO number (optional)
+
+If the company's finance team needs a purchase order number on every order, open the company and turn on **Require a PO number**. Their buyers must supply it before checking out, and it is shown on the order, in the confirmation email and in order search.
+
+## 8. Activate the catalog
+
+Catalogs are created switched off, so nobody sees a half-finished agreement. When it is ready, open it and click **Activate**. From that moment the company's buyers see its range and its prices.
+
+**Deactivate** stops it applying without losing anything, so you can switch a deal off and on again.
+
+## 9. Gate the storefront (optional)
+
+A public storefront shows prices to everyone. For a trade-only store, change the sales channel's storefront access so that prices are hidden until a buyer logs in, or the whole storefront requires a login. This is set on the channel under **Settings → Sales Channels**, and can also be set store-wide as a default.
+
+## What the buyer sees
+
+A buyer at the company logs in to your normal storefront. If they belong to more than one company, they pick which one they are buying for on the cart and at checkout. From there:
+
+- products and prices are the catalog's, not the shop's
+- the address step offers the company address book instead of their personal one
+- any minimums apply, and a PO number is asked for if the company requires one
+- their orders — and the orders of every node beneath their standing — appear in the company's order history
+
+## Next steps
+
+- [Companies](/user/customers/companies) — members, the tree, addresses and tax in depth
+- [Catalogs](/user/catalogs/catalogs) — the two ways a catalog is used, and where prices come from
+- [Customer Groups](/user/customers/customer-groups) — pricing for a segment of individual customers rather than a company
+- [Price Lists](/user/pricing/price-lists) — regional, volume and scheduled pricing that applies to everyone
diff --git a/docs/user/how-to/volume-pricing.mdx b/docs/user/how-to/volume-pricing.mdx
index c2b4a2b22e..c596b8a613 100644
--- a/docs/user/how-to/volume-pricing.mdx
+++ b/docs/user/how-to/volume-pricing.mdx
@@ -9,7 +9,7 @@ In Spree, you set this up using Price Lists with a Volume rule. Each pricing tie
In this guide, we'll set up two tiers: a mid-volume tier (21–50 units) and a high-volume tier (51–100 units).
-<Note>A single price list can also carry per-variant **quantity breaks**: a lower unit price from a given quantity up, set in the price edit form or imported from a CSV. Use separate price lists, as below, when whole assortments or rules differ between tiers; use quantity breaks when the same list should simply charge less per unit at volume. See [Price Lists](/user/manage-products/price-lists#quantity-breaks).</Note>
+<Note>A single price list can also carry per-variant **quantity breaks**: a lower unit price from a given quantity up, set in the price edit form or imported from a CSV. Use separate price lists, as below, when whole assortments or rules differ between tiers; use quantity breaks when the same list should simply charge less per unit at volume. See [Price Lists](/user/pricing/price-lists#quantity-breaks).</Note>
<Note>This guide focuses on volume-based pricing. If you need to combine volume pricing with customer group or regional rules — for example, offering wholesale volume discounts only to registered trade customers — see [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) instead.</Note>
@@ -17,7 +17,7 @@ In this guide, we'll set up two tiers: a mid-volume tier (21–50 units) and a h
Before you start, you should have your products uploaded and set up with base prices. Volume pricing overrides those base prices when the quantity conditions are met — products without a base price will not be affected.
-Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) for a full reference.
## 1. Create the First Volume Price List (21–50 Units)
@@ -89,6 +89,6 @@ If the expected price is not being applied, check that:
## Next Steps
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, product selection, and price editing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, product selection, and price editing
- [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — offer tiered pricing to specific customer segments
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — combine regional and volume rules for market-specific discounts
diff --git a/docs/user/how-to/wholesale-pricing.mdx b/docs/user/how-to/wholesale-pricing.mdx
index b9a3c070d6..6f0337aee0 100644
--- a/docs/user/how-to/wholesale-pricing.mdx
+++ b/docs/user/how-to/wholesale-pricing.mdx
@@ -13,7 +13,7 @@ In Spree, you do this by creating a Customer Group for your wholesale buyers, th
Before you start, you should have your products set up with base prices. Wholesale pricing overrides those base prices for customers in the relevant group — all other customers continue to see the standard price.
-Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) for a full reference.
## 1. Create a Customer Group
@@ -90,6 +90,6 @@ If the expected price is not showing, check that:
## Next Steps
- [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups) — full reference for creating and managing customer groups
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, product selection, and price editing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — full reference for rules, product selection, and price editing
- [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing) — add quantity-based tiers on top of your wholesale pricing
- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — apply regional price variations within a customer group
diff --git a/docs/user/inventory/purchase-orders.mdx b/docs/user/inventory/purchase-orders.mdx
new file mode 100644
index 0000000000..b5a5343a2b
--- /dev/null
+++ b/docs/user/inventory/purchase-orders.mdx
@@ -0,0 +1,66 @@
+---
+title: "Purchase Orders"
+description: "Order stock from a supplier, track what is on its way, and receive it into a warehouse."
+---
+
+A purchase order is how you buy stock from a supplier. It records what you asked for, what it costs, which warehouse it is coming to and when it was promised — then, as deliveries arrive, what actually turned up.
+
+Buying from a supplier is different from moving stock you already own. If goods are travelling between your own warehouses, use a [Stock Transfer](/user/inventory/stock-transfers) instead — it has no supplier, no cost per unit and no promised date.
+
+To manage purchase orders, open **Purchase Orders** under Inventory.
+
+## Creating one
+
+Click **New Purchase Order** and fill in:
+
+| Field | What it means |
+|---|---|
+| Supplier | Who you are buying from — a [Supplier](/user/inventory/suppliers) you have set up |
+| Deliver to | The warehouse the goods are coming to |
+| Currency | What the line costs are priced in |
+| Expected | The day the supplier promised |
+| Supplier reference | The supplier's own order number, so you can match paperwork later |
+| Notes | Anything your team needs to know |
+
+Then add lines — a product variant, how many, and what each unit costs.
+
+<Note>
+The currency is fixed once the order is opened, because every line cost is priced in it. Choose it before you mark the order as ordered.
+</Note>
+
+## The lifecycle
+
+A purchase order moves through a few states, and each one means something specific for your stock figures.
+
+| Status | What it means |
+|---|---|
+| Draft | Being put together. Nothing has been ordered and stock is unaffected |
+| Ordered | Sent to the supplier. The units now count as **incoming** on the Inventory page |
+| Partially received | Some deliveries have arrived, more are expected |
+| Received | Everything ordered has arrived |
+| Over-received | More arrived than was ordered — worth checking before you close it |
+| Cancelled | Called off. Anything still outstanding stops counting as incoming |
+
+Use **Mark as ordered** once the order is placed with the supplier. That is the moment the goods start showing as on their way. **Back to draft** reverses it if you sent it too early.
+
+## Receiving a delivery
+
+When goods arrive, click **Receive**. Each delivery is recorded as its own stock receipt — numbered, dated, and carrying the packing-slip reference — so an order that arrives in three shipments has three receipts against it.
+
+For each line, record what you accepted. If something was refused — damaged, wrong item, short — record that too, with a reason. Accepted units are added to the destination warehouse's on-hand count and stop being counted as incoming.
+
+Because each receipt is kept separately, the order's history shows what arrived when, rather than one final number.
+
+## Closing an order short
+
+Sometimes a supplier simply will not send the rest. **Close short** finishes the order with less than you ordered and asks for a reason. The order is marked received and noted as closed short, and the outstanding units stop counting as incoming — so your inventory figures stop promising stock that is not coming.
+
+## Importing and exporting
+
+Purchase orders export to CSV, one row per line — the file you send a supplier.
+
+They import from one too. Rows sharing a reference become a single draft order, naming the [supplier](/user/inventory/suppliers), warehouse and SKU by name. A name that does not exist fails that row rather than quietly creating something, so a typo is visible instead of becoming a new supplier.
+
+## What it costs you
+
+Stock received through a purchase order carries what the units cost into the stock history. That is what makes "what did this inventory cost us" answerable later, without reconstructing it from supplier invoices.
diff --git a/docs/user/manage-products/stock-levels.mdx b/docs/user/inventory/stock-levels.mdx
similarity index 95%
rename from docs/user/manage-products/stock-levels.mdx
rename to docs/user/inventory/stock-levels.mdx
index 9961d798c4..2f78d4f129 100644
--- a/docs/user/manage-products/stock-levels.mdx
+++ b/docs/user/inventory/stock-levels.mdx
@@ -32,7 +32,7 @@ Click the **On hand** figure on any row to correct it in place:
The change is recorded in the product's stock history with the reason you picked, beside every other movement on that shelf.
-<Warning>A correction is for what you have counted. Stock that arrives from a supplier belongs on a purchase order, and stock moving between your own warehouses belongs on a [stock transfer](/user/manage-products/stock-transfers), so that the delivery is recorded and the **Incoming** figure stays right.</Warning>
+<Warning>A correction is for what you have counted. Stock that arrives from a supplier belongs on a purchase order, and stock moving between your own warehouses belongs on a [stock transfer](/user/inventory/stock-transfers), so that the delivery is recorded and the **Incoming** figure stays right.</Warning>
## Adding incoming stock
diff --git a/docs/user/manage-products/stock-transfers.mdx b/docs/user/inventory/stock-transfers.mdx
similarity index 100%
rename from docs/user/manage-products/stock-transfers.mdx
rename to docs/user/inventory/stock-transfers.mdx
diff --git a/docs/user/inventory/suppliers.mdx b/docs/user/inventory/suppliers.mdx
new file mode 100644
index 0000000000..6612cfdc3d
--- /dev/null
+++ b/docs/user/inventory/suppliers.mdx
@@ -0,0 +1,35 @@
+---
+title: "Suppliers"
+description: "Keep a list of who you buy stock from, ready to name on a purchase order."
+---
+
+A supplier is someone you buy stock from. Keeping them as records means a [Purchase Order](/user/inventory/purchase-orders) names its supplier once, and the supplier's contact details and address travel with it.
+
+To manage suppliers, open **Suppliers** under Inventory.
+
+## Adding a supplier
+
+Click **New supplier** and fill in:
+
+| Field | What it is for |
+|---|---|
+| Name | How the supplier appears on purchase orders. Must be unique |
+| Contact name | Who you deal with there |
+| Email, phone | How to reach them |
+| Address | Where they are. A complete address — street, city and country — is what lets a purchase order be posted to them |
+| Notes | Anything your team should know — account numbers, lead times, who to ask for |
+
+## On purchase orders
+
+Every purchase order names a supplier, and the supplier's page lists the orders placed with them.
+
+When importing purchase orders from a CSV file, each row names its supplier by name. The name has to match a supplier that already exists — a name that does not is refused rather than creating a new supplier from a typo.
+
+## Removing a supplier
+
+A supplier can be deleted only while nothing has been ordered from them. Once a purchase order exists, the supplier is kept: the orders naming it have to keep meaning something.
+
+## Related
+
+- [Purchase Orders](/user/inventory/purchase-orders) — buying stock from a supplier
+- [Inventory](/user/inventory/stock-levels) — where received stock lands
diff --git a/docs/user/manage-products/multi-currency-import-export.mdx b/docs/user/manage-products/multi-currency-import-export.mdx
index 2c36635389..d2bb5ddd5d 100644
--- a/docs/user/manage-products/multi-currency-import-export.mdx
+++ b/docs/user/manage-products/multi-currency-import-export.mdx
@@ -64,4 +64,4 @@ Spree will automatically detect which rows are full product rows and which are p
- [<u>Import Products</u>](https://spreecommerce.org/docs/user/manage-products/import-products) — Full guide to importing product data
- [<u>Export Products</u>](https://spreecommerce.org/docs/user/manage-products/export-products) — Full guide to exporting your product catalog
- [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — Configure markets and currencies for your store
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — Set customer- or volume-specific pricing on top of your base prices
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists) — Set customer- or volume-specific pricing on top of your base prices
diff --git a/docs/user/manage-products/product-import-file-template.mdx b/docs/user/manage-products/product-import-file-template.mdx
index e4daa4046f..400ef7731f 100644
--- a/docs/user/manage-products/product-import-file-template.mdx
+++ b/docs/user/manage-products/product-import-file-template.mdx
@@ -47,7 +47,7 @@ For an example of **how to structure multi-variant products**, please download t
| option2_value | The value of the 2nd product option |
| option3_name | The name of the 3rd product option |
| option3_value | The value of the 3rd product option |
-| category1 | The 1st [category](https://spreecommerce.org/docs/user/manage-products/product-taxonomies) to which the product should be assigned|
+| category1 | The 1st [category](https://spreecommerce.org/docs/user/products/categories) to which the product should be assigned|
| category2 | The 2nd category to which the product should be assigned |
| category3 | The 3rd category to which the product should be assigned |
| metafield.namespace.key | The value for the product metafield [namespace.key](https://spreecommerce.org/docs/user/settings/metafields)|
diff --git a/docs/user/manage-products/product-taxonomies.mdx b/docs/user/manage-products/product-taxonomies.mdx
deleted file mode 100644
index 98fe7a2fa2..0000000000
--- a/docs/user/manage-products/product-taxonomies.mdx
+++ /dev/null
@@ -1,199 +0,0 @@
----
-title: "Taxonomies"
-description: "Learn how to create and manage product taxonomies in the Spree Commerce dashboard."
----
-
-Taxonomies let you organize products into groups like categories, brands, or collections.
-
-Taxons are individual nodes or items within a taxonomy, representing specific groups like a category, subcategory, or brand.
-
-A well-designed taxonomy enhances search functionality, improves user experience, and boosts sales by guiding customers through a logical and intuitive shopping journey.
-
-To set up taxonomies for your store, navigate to the Taxonomies tab of the admin dashboard, found under Products.
-
-![](/docs/images/user/products/taxonomies/1.tab.png)
-
-Here you will see three automatically created taxonomies that are commonly used in ecommerce:
-
-- Categories - Groups of products based on type or purpose for easy navigation
-- Brands - Organizes products by their manufacturer or label
-- Collections - Curated groups of products based on themes or trends
-
-## Add a New Taxonomy
-
-To add a new Taxonomy, such as a Category, Collection, or Brand, click **New Taxon** in the top right corner.
-
-This will redirect you to the Taxonomy creation page where you simply need to type in a name.
-
-![](/docs/images/user/products/taxonomies/2.new-taxonomy.png)
-
-Enter the name, and click the **Create** to finalize creation of the taxonomy and you'll be redirected to a page that allows you to manage the new taxonomy.
-
-![](/docs/images/user/products/taxonomies/20.taxonomy-created.png)
-
-## Add Taxons
-
-With the taxonomy created, you can start adding taxons to organize your product catalog more effectively.
-
-To add a taxon, either click **New Taxon** in the top right corner or (in the case of an empty taxonomy), click **Add One** in the middle of the page.
-
-![](/docs/images/user/products/taxonomies/3.new-taxon.png)
-
-This opens up the taxon editor page which allows you to define the taxon and add media.
-
-### Presentation
-
-There are four sections that affect how the taxon is presented on the storefront:
-
-- Name - Add a name to be displayed on the frontend and backend
-- Description - Add text describing the taxon, optionally displayed on the storefront
-- Image - Upload a complimentary image to be displayed on the taxons storefront page
-- Square Image - Upload a complimentary square image to optionally be displayed in page sections featuring that taxon
-
-### Taxon Type
-
-Taxon Type allows you to choose between a manual taxon or an automatic taxon.
-
-![](/docs/images/user/products/taxonomies/4.taxon-type.png)
-
-#### Manual Taxons
-
-As the name suggests, you must add products manually, either by assigning products to the taxon in bulk, curating them one by one, or by adding the appropriate values to the category column when importing a product file.
-
-#### Automatic Taxons
-
-Allows you to automatically (and dynamically) populate the taxon based on various conditions.
-
-![](/docs/images/user/products/taxonomies/5.automatic-taxons.png)
-
-You can choose whether the products must match all conditions or any of the conditions you define.
-
-The condition types are as follows:
-
-- Product tag - products will only be included if they have a matching tag
-- Available on - products will only be included if they were made available within the specified time frame
-- Sale - products will only be included if they are marked down (i.e., a Compare At Amount is set)
-- Product vendor - products will only be included if they are from a particular vendor
-
-Once you’ve selected the condition type, you can select the value from the dropdown that the condition should be equal to, not equal to, contain, or not contain
-
-![](/docs/images/user/products/taxonomies/6.condition-values.png)
-
-Feel free to add more conditions to further curate the taxon by clicking **Add One**.
-
-### Navigation
-
-Here you can select where the new taxon should be nested.
-
-![](/docs/images/user/products/taxonomies/7.navigation.png)
-
-The dropdown list will show a list of all taxons available within the taxonomy you're currently managing. Simply select the taxon you’d like to nest the new taxon in.
-
-Start typing the name of the taxon you’d like to nest within to filter the results.
-
-![](/docs/images/user/products/taxonomies/8.navigation-filtering.png)
-
-### Search Engine Listing
-
-Here you can set the meta title, meta description, and the slug for the new taxon.
-
-![](/docs/images/user/products/taxonomies/9.seo.png)
-
-### Create Taxon
-
-Once you’ve added the name and defined the taxon type, click **Create** at the bottom of the page to create the taxon, and you’ll receive a notification that the taxon was successfully created.
-
-### Add Products
-
-Once the taxon is created, you can add products to the taxon directly in taxon editor page by clicking **Add Products**, if and only if you chose the manual Taxon Type.
-
-This will open a window that allows you to search for and select the products you’d like to add.
-
-![](/docs/images/user/products/taxonomies/10.add-products.png)
-
-Start typing to show suggested products, then simply check the boxes of the products you’d like to add and then click **Add selected products**
-
-![](/docs/images/user/products/taxonomies/11.select-products.png)
-
-You should now see those products listed in the Products section of the taxon editor.
-
-<Note>You can remove individual products by clicking on the **red trash can button** in the far right column.</Note>
-
-![](/docs/images/user/products/taxonomies/12.products-added.png)
-
-### Sort Order
-
-For merchandising purposes, you may want to change the order in which products in a taxon are presented in the storefront.
-
-To do so, you can select the sort order from the dropdown menu in the Products section of the taxon editor.
-
-![](/docs/images/user/products/taxonomies/13.sort-order.png)
-
-If you choose manual sort order, you can rearrange the ordering by clicking on the 6 dots on the far left and drag and dropping the products into the desired order.
-
-![](/docs/images/user/products/taxonomies/14.manual-ordering.png)
-
-<Note>Make sure to click **Update** at the bottom of the page if you want to save any changes you’ve made to taxon.</Note>
-
-## Build A Taxonomy Tree
-
-If you’d like to create multiple levels of the taxonomy tree, you can add subtaxons (i.e. nested taxons) to an existing taxon.
-
-Simply click on the 3 dots on the far left of the taxon's row and select **New Nested Taxon**.
-
-![](/docs/images/user/products/taxonomies/15.nested-taxons.png)
-
-The rest of the process is the same as adding any other taxon.
-
-With some careful consideration, time and little effort, you can create a very deep and detailed taxonomy tree.
-
-![](/docs/images/user/products/taxonomies/16.taxonomy-tree.png)
-
-If you’d like to reorganize your taxonomy later, you can do so by drag and dropping taxons into their new positions.
-
-![](/docs/images/user/products/taxonomies/17.move-taxons.png)
-
-## Import Taxons
-
-Taxons can be automatically imported if you add the appropriate values to the category columns in a product import file. Just make sure to use the correct naming convention for the taxons to make sure nesting is respected after import, e.g.:
-
-- Categories -\> Fashion -\> Men
-- Categories -\> Fashion -\> Women -\> Footwear
-- Categories -\> Electronics -\> TVs
-- Categories -\> Nutrition -\> Supplements -\> Vitamins
-
-To learn more about imports, please refer to the [Import Products](https://spreecommerce.org/docs/user/manage-products/import-products) article.
-
-## Editing Taxonomies
-
-If you’d like to change the name of a taxonomy, navigate back to the main Taxonomies tab.
-
-![](/docs/images/user/products/taxonomies/18.edit-taxonomies.png)
-
-Find the taxonomy you’d like to rename, and click **Edit** on the far-right side.
-
-![](/docs/images/user/products/taxonomies/19.renamed-taxonomy.png)
-
-Enter the new taxonomy name and click **Update** to save changes.
-
-## Editing Taxons
-
-To edit a taxon, find the taxon you’d like to edit in its respective taxonomy, and click the **Edit** button on the taxon's row.
-
-Feel free to edit the name and description, swap out images, change the nesting, and update search engine listing settings. Make sure to click **Update** to save your changes.
-
-<Note>You cannot edit the Taxon Type of a taxon once created. If you want to change a taxon from manual to automatic (or vice versa), delete the old taxon and create another one with the same name.</Note>
-
-## Translations
-
-If you’re store is multi-language, you can add translations for both taxonomies and taxons.
-
-To learn more about translations, please refer to another support article.
-
-## Real-Life Examples of Categories, Collections, and Brands
-
-1. [Industry-Specific Taxonomy Needs](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-taxonomies-categories-collections-and-brands/#Industry-Specific)
-2. [Multiple Category Trees](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-taxonomies-categories-collections-and-brands/#Multiple-Category-Trees)
-3. [Collection Merchandising](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-taxonomies-categories-collections-and-brands/#Collection-Merchandising)
-4. [Taxonomy Visibility & Product Discovery](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-taxonomies-categories-collections-and-brands/#Taxonomy-Visibility-Product-Discovery)
-5. [Taxonomy Tools](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-taxonomies-categories-collections-and-brands/#Taxonomy-Tools)
diff --git a/docs/user/orders/cancelling-orders.mdx b/docs/user/orders/cancelling-orders.mdx
index 0f82d45663..bbb774c4a2 100644
--- a/docs/user/orders/cancelling-orders.mdx
+++ b/docs/user/orders/cancelling-orders.mdx
@@ -11,7 +11,7 @@ Spree allows you to cancel orders directly from the admin dashboard in just a fe
Navigate to the **Orders** tab of the admin dashboard.
-![Spree Commerce Orders tab showing order states](/docs/images/user/orders/cancelling-orders/1-cancelling-orders.png)
+![Spree Commerce Orders tab showing order statuses](/docs/images/user/orders/cancelling-orders/1-cancelling-orders.png)
Find and click on the order you want to cancel to open its detail page.
@@ -31,8 +31,8 @@ Once confirmed, the order will be cancelled and its status will be updated autom
### Order Status
-- The order’s shipment state will be updated to Cancelled.
-- The payment state may also change to Void or Refunded, depending on whether payment has already been captured.
+- The order’s status becomes **Canceled** and its fulfillment status **Canceled** — allocated stock is released and unshipped parcels are stood down.
+- Its payment status becomes **Voided** if the payment was only authorised, or **Refunded** once the captured amount has been given back.
### Payment Refunds
@@ -42,9 +42,9 @@ Refunds are not always automatic. Whether the payment is refunded depends on:
- The payment method used
- Whether the payment had already been captured
-If the payment state does not change to Refunded, you'll need to issue a refund manually.
+If the payment status does not change to Refunded, you'll need to issue a refund manually.
Learn more about refunds and returns here:
- [<u>Refunding Orders</u>](https://spreecommerce.org/docs/user/orders/refunding-orders)
-- [<u>Returns Processing</u>](https://spreecommerce.org/docs/user/returns/returns-processing)
+- [<u>Returns Processing</u>](https://spreecommerce.org/docs/user/orders/returns)
diff --git a/docs/user/orders/claims.mdx b/docs/user/orders/claims.mdx
new file mode 100644
index 0000000000..c730b47728
--- /dev/null
+++ b/docs/user/orders/claims.mdx
@@ -0,0 +1,44 @@
+---
+title: "Claims"
+description: "Handle a delivery that went wrong — damaged, missing or the wrong item — with a refund, a replacement, or both."
+---
+
+A claim is a customer reporting a problem with what arrived: the item was damaged, never turned up, or was the wrong product. Unlike a [Return](/user/orders/returns) or [Exchange](/user/orders/exchanges), nothing has to come back — you decide what to do once you have seen the evidence.
+
+Claims belong to the order they are about. Find them all under **Orders → Claims**, or on the order itself.
+
+## Opening a claim
+
+On the order, click **New claim**, pick the items affected, and record the reason from the claim-reasons list — "arrived damaged", "never arrived", "wrong item sent". Customers can open claims from their account and attach photographs as evidence, which is usually what you will want to look at before deciding.
+
+## The steps
+
+| Status | What it means |
+|---|---|
+| Open | Reported, waiting on you |
+| Approved | You accept the claim; how to resolve it is still to be decided |
+| Resolved | Refund sent, replacement shipped, or both |
+| Denied | The claim did not hold up |
+| Canceled | Withdrawn |
+
+## Resolving a claim
+
+What to do about a claim is decided when you **Resolve** it, not when it is opened — merchants usually decide once they have seen the photos. Choose how:
+
+| Resolution | What happens |
+|---|---|
+| Refund | Money back, with no items required in return |
+| Replacement | The item is shipped again — the same variant, or a different one |
+| Refund and replacement | Both |
+
+For a refund, set the **refund amount** and where it goes: the original payment method or store credit. For a replacement, choose what to **send a replacement for** — Spree creates a new shipment on the original order, so the customer does not place a second one.
+
+## Denying or cancelling
+
+**Deny** a claim that does not hold up. The customer receives neither a refund nor a replacement, and the claim is closed with that decision on record. **Cancel** withdraws it instead.
+
+## Related
+
+- [Returns](/user/orders/returns) — the customer sends items back for a refund
+- [Exchanges](/user/orders/exchanges) — the customer sends items back for different ones
+- [Returns & reasons](/user/settings/returns-configuration) — managing the claim-reasons list
diff --git a/docs/user/orders/discounts-fees-and-taxes.mdx b/docs/user/orders/discounts-fees-and-taxes.mdx
new file mode 100644
index 0000000000..7899f201b6
--- /dev/null
+++ b/docs/user/orders/discounts-fees-and-taxes.mdx
@@ -0,0 +1,63 @@
+---
+title: "Discounts, Fees and Taxes"
+description: "The three kinds of line that change an order's total besides its items — what each is, which ones you can add or remove, and how to settle the difference afterwards."
+---
+
+An order's total is its items plus delivery, and then three kinds of line on top: **discounts** take money off, **fees** add a charge, and **taxes** are worked out from the rest. Each has its own card on the order page, and each behaves differently — a discount can come from a promotion or be added by hand, a fee is always yours to add, and taxes are never edited directly.
+
+## Discounts
+
+Money taken off the order. The **Discounts** card lists every discount with its source:
+
+- **Promotion** — applied by one of your [promotions](/user/promotions/create-a-promotion), with the code the customer used when there was one. These are managed by the promotion, not by hand: to remove one, remove the code from the order (on a draft) or change the promotion.
+- **Manual** — added by your team on this order, for a goodwill gesture, a price match, or a correction.
+
+To add one, click **Add discount** and fill in:
+
+- **Label** — what the customer sees on their order, such as "Loyalty discount".
+- **Type** — a fixed **Amount**, or a **Percent** of what it applies to. A percentage shows you the estimated amount before you save.
+- **Applies to** — the **whole order**, or one line item. A whole-order discount is spread across the items in proportion to their price.
+
+A manual discount can be deleted from its row menu; a promotion discount cannot.
+
+<Note>Discounts and fees can be added to placed orders, not only drafts. The order's totals are recalculated straight away, and its [payment status](/user/orders/order-statuses#payment-status) changes to match.</Note>
+
+## Fees
+
+A charge on top of the items — never a credit; a credit is a discount. Click **Add fee** and give it a **label**, a **kind** and an **amount**. The kind says what the charge is for and lets you report on fees later:
+
+| Kind | Typical use |
+|---|---|
+| Surcharge | A general extra charge |
+| Handling | Packing or special handling |
+| Gift wrap | Wrapping requested by the customer |
+| Cash on delivery | The carrier's COD charge |
+| Payment | A payment-method fee where the law allows one |
+| Duty | Customs duty on an international order — usually written by a duties provider rather than by hand |
+
+Fees are taxable: the tax lines are recalculated to include them, using the same rates as the items. A fee can be deleted from its row menu.
+
+## Taxes
+
+The **Taxes** card shows what tax was charged, grouped by rate — the amount comes from your [tax setup](/user/settings/tax) or a connected tax provider, applied to the delivery address. You cannot edit a tax line; change the address, the items, the fees or the tax rates and the lines are recalculated.
+
+Two things the card tells you when something is off:
+
+- **"No tax rate matched this address"** — the order is taxable but nothing in your tax settings covers where it is going.
+- A **certificate** note — the buyer's company holds a tax exemption for that region, and the exemption was applied.
+
+## Settling the difference
+
+Changing an order's total after the customer paid leaves a gap, and the order's payment status shows which way:
+
+- Added a fee, or removed a discount → the order reads **Partially paid**. Collect the rest with **New payment** in the Payments card, charging the customer's saved method or recording a payment taken elsewhere.
+- Added a discount → the order reads **Overcharged**. Give the difference back with **Refund** on the payment. See [refunding orders](/user/orders/refunding-orders).
+
+Once the totals match again the order returns to **Paid**.
+
+## Related
+
+- [Order statuses](/user/orders/order-statuses) — what Partially paid and Overcharged mean
+- [Editing orders](/user/orders/editing-orders) — changing the items themselves
+- [Promotions](/user/promotions/create-a-promotion) — the source of promotion discounts
+- [Tax settings](/user/settings/tax) — the rates behind the tax lines
diff --git a/docs/user/orders/exchanges.mdx b/docs/user/orders/exchanges.mdx
new file mode 100644
index 0000000000..8939ad32e8
--- /dev/null
+++ b/docs/user/orders/exchanges.mdx
@@ -0,0 +1,49 @@
+---
+title: "Exchanges"
+description: "Swap what a customer bought for a different size, colour or product — items come back, replacements go out."
+---
+
+An exchange is a [Return](/user/orders/returns) that ends by sending different items instead of refunding: the customer sends back the medium and gets the large. It belongs to the order it came from, and you will find all exchanges under **Orders → Exchanges**, as well as on the order itself.
+
+## When to use one
+
+Use an exchange when the customer wants a *different* item and is sending the original back. If they want their money, that is a return. If the delivery went wrong — damaged, missing, wrong item — and you would replace it without asking for anything back, that is a [Claim](/user/orders/claims).
+
+## Opening an exchange
+
+On the order, click **New exchange**. For each line being swapped, choose the item coming back, how many, and the **replacement variant** going out in its place — another size or colour of the same product, or a different product entirely.
+
+Record the reason from the return-reasons list; exchanges and returns share it.
+
+Customers can also open exchanges from their account, if your storefront offers it. Those arrive as **Requested**.
+
+## The steps
+
+| Status | What it means |
+|---|---|
+| Requested | Opened, waiting on you |
+| Approved | You have authorised it — the customer can send the goods back |
+| Received | The goods arrived and you recorded what turned up |
+| Fulfilled | The replacements have shipped |
+| Canceled | Called off before the goods were received |
+
+**Approve** it, then when the parcel arrives, **Receive items** — enter the quantity that actually came back per line, and whether each is resellable. Resellable items return to stock; damaged ones do not.
+
+Then **Ship replacement**. Spree creates the replacement shipment on the original order for the quantities that were actually received — not what was promised — and checks the replacements are in stock first. The customer does not have to place a second order.
+
+## The price difference
+
+Replacements are not always worth the same as what came back. Spree works out the **price difference**:
+
+- If the replacements are worth **less**, the difference goes back to the customer — to store credit or their original payment method, your choice.
+- If they are worth **more**, Spree records the difference but does **not** charge the customer automatically. Collecting that balance is up to you, so nobody's card is charged without their agreement.
+
+## Cancelling
+
+An exchange can be cancelled at any point before the goods are received. Cancelling restocks nothing and moves no money.
+
+## Related
+
+- [Returns](/user/orders/returns) — money back instead of different items
+- [Claims](/user/orders/claims) — when the delivery went wrong
+- [Returns & reasons](/user/settings/returns-configuration) — the reason list exchanges share with returns
diff --git a/docs/user/orders/exporting-orders.mdx b/docs/user/orders/exporting-orders.mdx
index 12d13a7ee8..91d59a4cfa 100644
--- a/docs/user/orders/exporting-orders.mdx
+++ b/docs/user/orders/exporting-orders.mdx
@@ -21,7 +21,7 @@ Click the **Export** button in the top-right corner, and a popup will appear
Next, choose which records to export:
-- **Filtered Records** - Exports only the orders currently visible based on your applied filters (e.g., date range, payment state).
+- **Filtered Records** - Exports only the orders currently visible based on your applied filters (e.g., date range, payment status).
- **All** - Exports the entire order history.
Once selected, click **Export**, annd a download link for the CSV file will be sent to the email address associated with your admin user account.
diff --git a/docs/user/orders/order-adjustments.mdx b/docs/user/orders/order-adjustments.mdx
deleted file mode 100644
index dc0cdf642a..0000000000
--- a/docs/user/orders/order-adjustments.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: "Order Adjustments"
-description: "Learn how to create and settle order adjustments in Spree Commerce."
----
-
-# Order Adjustments
-
-Order adjustments let you manually add a charge or credit to an existing order - ideal for handling things like special fees, discounts, or post-purchase updates.
-
-## How to Create an Adjustment
-
-To create an order adjustment, navigate to the **Orders** tab in the admin dashboard.
-
-![The Order management tab in Spree Commerce](/docs/images/user/orders/order-adjustments/1-orders-tab.png)
-
-Find the order you'd like to adjust and click on it to open the order page.
-
-![A customer order page in Spree commerce](/docs/images/user/orders/order-adjustments/2-order-page.png)
-
-Scroll to the **Adjustments** section and click **New Adjustment** to open the adjustment creation form.
-
-![Adding an adjustment to an order in Spree Commerce](/docs/images/user/orders/order-adjustments/3-new-adjustment.png)
-
-Fill out the form:
-
-- **Label** - A name for the adjustment (e.g., "Custom Discount", "Packaging Fee")
-- **Amount** - Use a **positive value** for a charge or a **negative value** for a credit.
-
-Finally, click **Create** to add the new adjustment.
-
-## Handling the Payment or Refund
-
-Once the adjustment has been created, it will need to be settled manually. Depending on whether it’s a charge or credit, follow one of the steps below:
-
-### Credit (Negative Amount)
-
-To manually refund the adjustment amount, click the **three-dot menu** next to the payment and select **Refund**.
-
-![Refunding a payment in Spree Commerce](/docs/images/user/orders/order-adjustments/4-refund.png)
-
-This will open a refund form where you can enter the amount to be refunded.
-
-![The Spree Commerce refund form](/docs/images/user/orders/order-adjustments/5-refund-form.png)
-
-After entering the amount and selecting a refund reason, click **Create** to process the refund.
-
-<Note>Refund behavior depends on the payment method used - some refunds can be processed automatically, while others may require manual handling.</Note>
-
-### Charge (Positive Amount)
-
-There are two methods to charge a customer in the event of a positive adjustment.
-
-### Automatated Payment
-
-To charge a customer, click **New Payment** in the Payments section.
-
-![Adding a new payment to an order in Spree Commerce](/docs/images/user/orders/order-adjustments/6-new-payment.png)
-
-This will open the payment form where you can select the amount to charge the customer and the payment method to be charged.
-
-![The Spree Commerce payment form](/docs/images/user/orders/order-adjustments/7-payment-form.png)
-
-Click **Create** after entering the details. The customer’s payment method will then be automatically charged for the outstanding balance.
-
-## Close the Adjustment
-
-Once the adjustment has been handled, click the **three-dot menu** next to the adjustment, and select **Close** to mark the adjustment as finalized.
-
-![Closing an order adjustment in Spree Commerce](/docs/images/user/orders/order-adjustments/8-close-adjustment.png)
-
-<Note>Closing an adjustment helps track which ones have been settled, especially when managing refunds or manual charges.</Note>
diff --git a/docs/user/orders/order-states.mdx b/docs/user/orders/order-states.mdx
deleted file mode 100644
index 2c3a7f7128..0000000000
--- a/docs/user/orders/order-states.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: "Order States"
-description: "Learn how to use order states to track and manage orders in Spree Commerce."
----
-
-Effective order management is essential for any ecommerce business - it ensures timely processing, accurate fulfillment, and a smooth customer experience. In Spree, Order States help you track and manage each stage of an order, so you can quickly identify next steps or potential issues.
-
-To review order states, navigate to the **Orders** tab of the admin dashboard.
-
-![Spree Commerce dashboard showing various order states](/docs/images/user/orders/order-states/orders-tab.png)
-
-You’ll see a list of all orders placed in your store, with two key columns:
-
-- **Payment State** - shows the current payment status
-- **Shipment State** - shows the current shipping status
-
-Together, these determine the overall state of the order.
-
-## Payment States
-
-The **Payment State** indicates the current status of payments associated with the order. An order can have multiple payments, but Spree will show the relevant state based on the most recent or net balance.
-
-| **Payment State** | **Description** |
-| ---------------------- | ------------------------------------------------------------------------- |
-| Paid | The order total has been fully paid |
-| Balance Due | The total payments are less than the order total |
-| Credit Owed | The total payments exceed the order total (e.g. after removing items) |
-| Refunded | The order has been fully refunded |
-| Partially Refunded | One or more refunds have been issued, but the order is not fully refunded |
-| Failed | The most recent payment attempt failed |
-
-<Note>You cannot manually set the payment state. It updates automatically based on actions like capturing payments, issuing refunds, or adjusting the order total.</Note>
-
-## Shipment States
-
-The **Shipment State** reflects the current status of all shipments tied to an order. Orders can have one or multiple shipments depending on stock locations or backorders.
-
-| **Shipment State** | **Description** |
-| ------------------ | ---------------------------------------------------------------------------------------------------------- |
-| Shipped | All associated shipments have been marked as shipped |
-| Partial | At least one shipment is shipped, but others are not / or some items are marked sold but not in a shipment |
-| Ready | All shipments are packed and ready to be shipped |
-| Backorder | At least one shipment contains inventory that is currently backordered |
-| Pending | Shipments are created but not ready to be fulfilled (e.g., awaiting payment) |
-| Cancelled | The order has been cancelled |
-
-<Note>Like payment state, shipment state is managed automatically based on order and fulfillment actions.</Note>
-
-## Using Order States Effectively
-
-Understanding these states makes it easier to manage operations and know exactly what action to take.
-
-Here are some common scenarios:
-
-| **Payment State** | **Shipment State** | **Suggested Action** |
-| ---------------- | ----------------- | -------------------------------------------------- |
-| Paid | Shipped | No action needed – order is complete |
-| Paid | Ready | Ship the order |
-| Balance Due | Pending | Capture payment or request payment from customer |
-| Credit Owed | Partial | Refund the owed amount |
-| Failed | Pending | Review payment method or contact the customer |
-
-
-## Next Steps
-
-Now that you're familiar with how order states work, we recommend checking out related docs for deeper insights:
-
-- [<u>Processing Orders</u>](https://spreecommerce.org/docs/user/orders/processing-orders) - Learn how to capture payments and ship orders
-- [<u>Cancelling Orders</u>](https://spreecommerce.org/docs/user/orders/cancelling-orders) - Learn how to cancel orders
-- [<u>Creating Orders</u>](https://spreecommerce.org/docs/user/orders/creating-orders) - Learn how to create orders manually as an admin
-- [<u>Returns Processing</u>](https://spreecommerce.org/docs/user/returns/returns-processing) - Learn how to process returns
diff --git a/docs/user/orders/order-statuses.mdx b/docs/user/orders/order-statuses.mdx
new file mode 100644
index 0000000000..f62e148e8b
--- /dev/null
+++ b/docs/user/orders/order-statuses.mdx
@@ -0,0 +1,72 @@
+---
+title: "Order Statuses"
+description: "What an order's status, payment status and fulfillment status mean, how each changes, and what to do next."
+---
+
+Every order carries three statuses. One says where the order itself is in its life; the other two roll up what has happened to its money and its goods. You never set any of them by hand — each changes when something happens: a customer checks out, a payment is captured, a parcel goes out, a refund is issued.
+
+They are the first columns on the **Orders** page, and the quick filters above the table let you narrow the list to any of their values.
+
+![Spree Commerce dashboard showing order statuses](/docs/images/user/orders/order-statuses/orders-tab.png)
+
+## Order status
+
+An order is one of three things:
+
+| Status | Meaning |
+|---|---|
+| **Draft** | Your team started it on a customer's behalf and has not placed it yet. Drafts live under **Orders → Drafts**, can be edited freely, and carry no payment or fulfillment status until placed. See [creating orders](/user/orders/creating-orders). |
+| **Placed** | The order is real: a customer checked out, or a team member placed a draft. Stock is allocated, the customer has their confirmation, and payment and fulfillment start being tracked. |
+| **Canceled** | Cancelled by your team. Allocated stock is released, any unshipped parcels are stood down, and an uncaptured payment is voided. See [cancelling orders](/user/orders/cancelling-orders). |
+
+There is nothing to advance. A placed order does not move to "complete" — its payment and fulfillment statuses say how far along it is.
+
+## Payment status
+
+What has been collected against the order, worked out from its payments and refunds and compared with the order total.
+
+| Status | Meaning |
+|---|---|
+| **Unpaid** | Nothing has been authorised or captured yet. |
+| **Authorized** | The customer's payment method has approved the amount, but it has not been taken. Your store's capture setting decides whether that happens at checkout, when the goods ship, or by hand. |
+| **Partially paid** | Some money has been captured, but less than the order total — a deposit, or a fee added after payment. |
+| **Paid** | Captured payments cover the order total. |
+| **Partially refunded** | A refund has been issued, and the customer has still paid something net. |
+| **Refunded** | Refunds have given back everything that was captured. |
+| **Overcharged** | Captured payments exceed the order total — usually because items were removed or a discount was added after the customer paid. The customer is owed the difference. |
+| **Voided** | The order was cancelled and its authorisation released, or its captured money fully returned. |
+
+A refund reduces both sides of the comparison, so an order refunded for a removed item still reads **Paid** rather than **Partially refunded** once the total matches what the customer kept.
+
+## Fulfillment status
+
+What has happened to the goods, rolled up from the order's fulfillments (its parcels, pickups or downloads).
+
+| Status | Meaning |
+|---|---|
+| **Unfulfilled** | Nothing has gone out yet. Also shown when every parcel so far was cancelled but the order is still live — the goods are still owed. |
+| **Partial** | Some parcels are out, others are not. |
+| **Fulfilled** | Everything has been handed over — shipped, collected, or delivered digitally. |
+| **Delivered** | The carrier, or your team, has confirmed every parcel reached the customer. This starts the returns window. |
+| **Backorder** | At least one item was sold without stock on hand. Ships once stock arrives. |
+| **Canceled** | The order was cancelled and every parcel stood down. |
+
+Cancelled parcels are ignored while any other parcel is live, so an order whose second parcel was recalled is still described by the first.
+
+## What to do next
+
+| Payment | Fulfillment | Suggested action |
+|---|---|---|
+| Paid | Fulfilled or Delivered | Nothing — the order is done. |
+| Paid | Unfulfilled | Ship it. See [processing orders](/user/orders/processing-orders). |
+| Authorized | Unfulfilled | Capture the payment, or ship and let capture-on-dispatch take it. |
+| Unpaid or Partially paid | Any | Collect the balance — take a new payment from the order page, or ask the customer to pay. |
+| Overcharged | Any | Refund the difference. See [refunding orders](/user/orders/refunding-orders). |
+| Any | Backorder | Restock the item, or tell the customer when it will ship. |
+
+## Related
+
+- [Processing orders](/user/orders/processing-orders) — capturing payment and shipping
+- [Discounts, fees and taxes](/user/orders/discounts-fees-and-taxes) — the changes that move an order's total after it was paid
+- [Cancelling orders](/user/orders/cancelling-orders)
+- [Returns](/user/orders/returns) — what the returns window opens once an order is delivered
diff --git a/docs/user/orders/processing-orders.mdx b/docs/user/orders/processing-orders.mdx
index e2558fe466..bada2546c7 100644
--- a/docs/user/orders/processing-orders.mdx
+++ b/docs/user/orders/processing-orders.mdx
@@ -23,7 +23,7 @@ Some businesses (especially B2C) choose to auto-capture payments when an order i
<Note>If you are auto-capturing payments, proceed to Order Fulfillment.</Note>
-If the order has a Balance Due payment status, follow one of the options below:
+If the order still owes money — a **Partially paid** or **Authorized** payment status — follow one of the options below:
### Option 1: Manually Capture an Existing Payment
@@ -81,7 +81,7 @@ To add tracking details to the shipment:
Double-check that everything is correct and click **Ship** to complete the order.
-The order’s shipment status will update to **Shipped**, and the customer will receive a confirmation email with tracking details.
+The order’s fulfillment status will update to **Fulfilled**, and the customer will receive a confirmation email with tracking details.
## Order Completed
@@ -89,7 +89,7 @@ The order’s shipment status will update to **Shipped**, and the customer will
At this point, the order will have:
-- **Payment State**: Paid
-- **Shipment State**: Shipped
+- **Payment status**: Paid
+- **Fulfillment status**: Fulfilled — and **Delivered** once the carrier confirms it arrived
This means the order has been successfully processed and is now complete from your business’ point of view. All that’s left is for the customer to receive their shipment.
diff --git a/docs/user/orders/refunding-orders.mdx b/docs/user/orders/refunding-orders.mdx
index a7c85858d6..83316489a5 100644
--- a/docs/user/orders/refunding-orders.mdx
+++ b/docs/user/orders/refunding-orders.mdx
@@ -32,9 +32,9 @@ On the refund page, you’ll be able to:
Once complete, click **Create** to process the refund.
-The order’s payment state will be updated to reflect the refund:
+The order’s [payment status](/user/orders/order-statuses#payment-status) will be updated to reflect the refund:
- **Refunded** for full refunds
-- **Partially Refunded** if only a portion was refunded
+- **Partially refunded** if only a portion was refunded
<Warning>Refund behavior depends on the payment method. Some providers (like Stripe) automatically process refunds. Others (like offline/manual payments) may require you to issue the refund manually outside of Spree. Always double-check which payment method was used and whether the refund was successfully processed through your payment provider</Warning>
diff --git a/docs/user/returns/returns-processing.mdx b/docs/user/orders/returns.mdx
similarity index 57%
rename from docs/user/returns/returns-processing.mdx
rename to docs/user/orders/returns.mdx
index c4439ffee0..b68cc35f5a 100644
--- a/docs/user/returns/returns-processing.mdx
+++ b/docs/user/orders/returns.mdx
@@ -1,21 +1,18 @@
---
-title: "Returns Processing"
-description: "Learn how to process returns, exchanges, and claims in Spree Commerce."
+title: "Returns"
+description: "Process a return from request to refund — approve it, receive the goods, restock what can be resold, and refund the customer."
---
-Spree 6 handles everything that happens after a sale with three records, each covering a different situation:
+A return is the customer sending items back and getting their money back. It belongs to the order it came from, so opening the order shows the whole story in one place.
-- **Return** — the customer sends items back and gets their money back.
-- **Exchange** — the customer sends items back and gets different items instead, such as another size or colour.
-- **Claim** — something went wrong with the delivery. The item arrived damaged, never arrived, or was the wrong product. You can send a replacement, refund the customer, or both, without asking for the original item back.
-
-Each one belongs directly to an order, so opening an order shows you everything that has happened to it.
+Returns sit beside two related records — an [Exchange](/user/orders/exchanges), where the customer gets different items instead of money, and a [Claim](/user/orders/claims), where something went wrong with the delivery and nothing need come back. Find all three under **Orders** in the dashboard.
<Note>
This replaces the older three-step flow of Return Authorization, Customer Return, and Reimbursement. One record now covers the whole operation from request through to refund.
</Note>
-## Returns
+## Processing a return
+
### 1. Open the return
@@ -47,29 +44,10 @@ Once the refund goes through, the customer receives an email confirming it.
A return can be cancelled at any point before the goods are received. Cancelling restocks nothing.
</Note>
-## Exchanges
-
-An exchange follows the same path as a return — open, approve, receive — but instead of refunding the customer at the end, you fulfil the replacement items.
-
-When you fulfil an exchange, Spree creates the replacement shipment for the quantities that were actually received, and checks the replacements are in stock first.
-
-If the replacement items are worth less than what came back, the difference is returned to the customer as store credit or refunded to their original payment method. If the replacements are worth more, Spree records the difference but does not charge the customer automatically — collecting that balance is up to you, so nobody's card is charged without them agreeing to it.
-
-## Claims
-
-A claim starts when a customer reports a problem. Claims record what went wrong — damaged, missing, wrong item, or another reason you define — and the customer can attach photographs as evidence.
-
-When you resolve a claim you choose what to do:
-
-- **Refund** — money back, with no items required in return.
-- **Replacement** — ship the item again, either the same variant or a different one.
-- **Refund and replacement** — both.
-
-You can also deny a claim if it does not hold up, or cancel it.
## Where to find them
-Returns, exchanges, and claims each have their own section in the dashboard, so you can see everything in progress across all orders. Individual records also appear on the order they belong to, giving you the full history of that order in one place.
+Returns, exchanges, and claims each have their own page under Orders in the dashboard, so you can see everything in progress across all orders. Individual records also appear on the order they belong to, giving you the full history of that order in one place.
## Reasons
@@ -85,3 +63,9 @@ They are kept separate because they answer different questions, and mixing them
Spree does not enforce a return window, restocking fee, or final-sale rule out of the box. Every merchant's policy differs, and the rules often vary by country for legal reasons.
Instead, your developers can attach your policy to the point where a return is created. A common setup enforces the policy for customers opening returns themselves, while still letting your staff override it — so a supervisor can accept a return outside the window for a good customer without needing a code change.
+
+## Related
+
+- [Exchanges](/user/orders/exchanges) — swapping items rather than refunding
+- [Claims](/user/orders/claims) — damaged, missing or wrong deliveries
+- [Returns & reasons](/user/settings/returns-configuration) — the reason lists staff pick from
diff --git a/docs/user/orders/searching-orders.mdx b/docs/user/orders/searching-orders.mdx
index c8b1af2337..0db5433115 100644
--- a/docs/user/orders/searching-orders.mdx
+++ b/docs/user/orders/searching-orders.mdx
@@ -46,7 +46,7 @@ Spree’s new table system allows you to customize and sort your order view.
![Apply sorting to orders in the Spree Commerce dashboard](/docs/images/user/orders/searching-orders/4-sorting.png)
-You can sort orders by clicking on the Sort dropdown above the table, and selecting the column you’d like to sort by (such as Order Number, Total, Payment State, etc.).
+You can sort orders by clicking on the Sort dropdown above the table, and selecting the column you’d like to sort by (such as Order Number, Total, Payment status, etc.).
At the bottom of the dropdown, select whether you prefer Ascending or Descending order.
@@ -73,10 +73,10 @@ Filters have been significantly improved and now support **operators** and **AND
You can create filter groups using the following fields:
- Order Number
-- Payment State
-- Shipment State
+- Payment status
+- Fulfillment status
- Total
-- State
+- Status (Draft, Placed, Canceled)
- Email
- First Name
- Last Name
@@ -101,9 +101,9 @@ Each filter condition also includes an operator, allowing you to define exactly
For example:
- Total greater than 500
-- Payment State is any of Paid, Refunded
+- Payment status is any of Paid, Refunded
- Promotion is not empty
-- Shipment State does not equal Fulfilled
+- Fulfillment status does not equal Fulfilled
### Using AND / OR Groups
@@ -112,7 +112,7 @@ For example:
For example:
-- Orders where **Payment State = Balance Due AND Shipment State = Ready**
+- Orders where **Payment status = Partially paid AND Fulfillment status = Unfulfilled**
- Orders where **Promotion = SUMMER2025 OR Promotion = VIPDISCOUNT**
This flexibility makes it much easier to identify specific subsets of orders for follow-up, reporting, or operational tasks.
diff --git a/docs/user/manage-products/price-lists.mdx b/docs/user/pricing/price-lists.mdx
similarity index 94%
rename from docs/user/manage-products/price-lists.mdx
rename to docs/user/pricing/price-lists.mdx
index 4946bc212e..020e3abea1 100644
--- a/docs/user/manage-products/price-lists.mdx
+++ b/docs/user/pricing/price-lists.mdx
@@ -44,12 +44,14 @@ You can add multiple rules with Match Any or Match All logic.
Available Rule Types:
-- **User** - Apply pricing only for specific users.
-- **Customer Group** - Apply pricing to a specific customer group.
- **Market** - Apply pricing to customers shopping in a specific market.
- **Volume** - Apply pricing when order quantity falls within a min–max range.
- **Zone** - Apply pricing to customers in a specific tax/shipping zone.
+<Note>
+Pricing for a particular customer group or company is no longer a price list rule. Create a [Catalog](/user/catalogs/catalogs) and assign it to the group or company instead — it carries its own price list, and can also restrict what they see and set order minimums. Price lists that already use a **Customer Group** or **User** rule keep working; those rules are simply not offered for new lists.
+</Note>
+
To add a rule, simply click **Add Rule**, select a rule type, and configure its criteria.
### Add Products
diff --git a/docs/user/products/categories.mdx b/docs/user/products/categories.mdx
new file mode 100644
index 0000000000..aa3e2d7ed3
--- /dev/null
+++ b/docs/user/products/categories.mdx
@@ -0,0 +1,157 @@
+---
+title: "Categories"
+description: "Organize products into a browsable tree of categories in the Spree Commerce dashboard."
+---
+
+Categories are how you file products into a browsable tree — Fashion, then Men, then Footwear. A product can sit in several categories, and each category can hold subcategories as deep as your range needs.
+
+Categories are the shelves of your store. For groupings that cut across them — "Summer 2025", "Best Sellers", "Under $50" — use [Collections](/user/products/collections), which can fill themselves from rules.
+
+A well-planned category tree improves search, guides customers through a logical shopping journey, and is what most storefront navigation is built from.
+
+To set up categories, open the **Categories** tab of the admin dashboard, found under Products.
+
+![](/docs/images/user/products/categories/1.tab.png)
+
+Here you will see three automatically created categories that are commonly used in ecommerce:
+
+- Categories - Groups of products based on type or purpose for easy navigation
+- Brands - Organizes products by their manufacturer or label
+- Collections - Curated groups of products based on themes or trends
+
+## Add a category
+
+To add a category, click **New Category** in the top right corner — or, on an empty list, **Add One** in the middle of the page.
+
+![](/docs/images/user/products/categories/3.new-category.png)
+
+This opens up the category editor page which allows you to define the category and add media.
+
+### Presentation
+
+There are four sections that affect how the category is presented on the storefront:
+
+- Name - Add a name to be displayed on the frontend and backend
+- Description - Add text describing the category, optionally displayed on the storefront
+- Image - Upload a complimentary image to be displayed on the categories storefront page
+- Square Image - Upload a complimentary square image to optionally be displayed in page sections featuring that category
+
+### Automatic grouping
+
+Categories are curated by hand. If you want a grouping that fills itself — everything on sale, everything tagged `organic` — create a [Collection](/user/products/collections) instead.
+
+### Navigation
+
+Here you can select where the new category should be nested.
+
+![](/docs/images/user/products/categories/7.navigation.png)
+
+The dropdown list will show a list of all categories available within the category you're currently managing. Simply select the category you’d like to nest the new category in.
+
+Start typing the name of the category you’d like to nest within to filter the results.
+
+![](/docs/images/user/products/categories/8.navigation-filtering.png)
+
+### Search Engine Listing
+
+Here you can set the meta title, meta description, and the slug for the new category.
+
+![](/docs/images/user/products/categories/9.seo.png)
+
+### Create Category
+
+Once you’ve added the name and defined the category type, click **Create** at the bottom of the page to create the category, and you’ll receive a notification that the category was successfully created.
+
+### Add Products
+
+Once the category is created, you can add products to the category directly in category editor page by clicking **Add Products**, if and only if you chose the manual Category Type.
+
+This will open a window that allows you to search for and select the products you’d like to add.
+
+![](/docs/images/user/products/categories/10.add-products.png)
+
+Start typing to show suggested products, then simply check the boxes of the products you’d like to add and then click **Add selected products**
+
+![](/docs/images/user/products/categories/11.select-products.png)
+
+You should now see those products listed in the Products section of the category editor.
+
+<Note>You can remove individual products by clicking on the **red trash can button** in the far right column.</Note>
+
+![](/docs/images/user/products/categories/12.products-added.png)
+
+### Sort Order
+
+For merchandising purposes, you may want to change the order in which products in a category are presented in the storefront.
+
+To do so, you can select the sort order from the dropdown menu in the Products section of the category editor.
+
+![](/docs/images/user/products/categories/13.sort-order.png)
+
+If you choose manual sort order, you can rearrange the ordering by clicking on the 6 dots on the far left and drag and dropping the products into the desired order.
+
+![](/docs/images/user/products/categories/14.manual-ordering.png)
+
+<Note>Make sure to click **Update** at the bottom of the page if you want to save any changes you’ve made to category.</Note>
+
+## Build A Category Tree
+
+If you’d like to create multiple levels of the category tree, you can add subcategories (i.e. nested categories) to an existing category.
+
+Simply click on the 3 dots on the far left of the category's row and select **New Nested Category**.
+
+![](/docs/images/user/products/categories/15.nested-categories.png)
+
+The rest of the process is the same as adding any other category.
+
+With some careful consideration, time and little effort, you can create a very deep and detailed category tree.
+
+![](/docs/images/user/products/categories/16.category-tree.png)
+
+If you’d like to reorganize your category later, you can do so by drag and dropping categories into their new positions.
+
+![](/docs/images/user/products/categories/17.move-categories.png)
+
+## Import Categories
+
+Categories can be automatically imported if you add the appropriate values to the category columns in a product import file. Just make sure to use the correct naming convention for the categories to make sure nesting is respected after import, e.g.:
+
+- Categories -\> Fashion -\> Men
+- Categories -\> Fashion -\> Women -\> Footwear
+- Categories -\> Electronics -\> TVs
+- Categories -\> Nutrition -\> Supplements -\> Vitamins
+
+To learn more about imports, please refer to the [Import Products](https://spreecommerce.org/docs/user/manage-products/import-products) article.
+
+## Renaming a category
+
+If you’d like to change the name of a category, navigate back to the main Categories tab.
+
+![](/docs/images/user/products/categories/18.edit-categories.png)
+
+Find the category you’d like to rename, and click **Edit** on the far-right side.
+
+![](/docs/images/user/products/categories/19.renamed-category.png)
+
+Enter the new category name and click **Update** to save changes.
+
+## Editing a category
+
+To edit a category, find it in the tree and click **Edit** on its row.
+
+Feel free to edit the name and description, swap out images, change the nesting, and update search engine listing settings. Make sure to click **Update** to save your changes.
+
+
+## Translations
+
+If your store is multi-language, you can add translations for both categories and collections.
+
+To learn more, see the [Translations](/user/translations/translations) guide.
+
+## Real-Life Examples of Categories, Collections, and Brands
+
+1. [Industry-Specific Category Needs](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-categories-categories-collections-and-brands/#Industry-Specific)
+2. [Multiple Category Trees](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-categories-categories-collections-and-brands/#Multiple-Category-Trees)
+3. [Collection Merchandising](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-categories-categories-collections-and-brands/#Collection-Merchandising)
+4. [Category Visibility & Product Discovery](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-categories-categories-collections-and-brands/#Category-Visibility-Product-Discovery)
+5. [Category Tools](https://spreecommerce.org/improving-product-discovery-and-conversions-with-product-categories-categories-collections-and-brands/#Category-Tools)
diff --git a/docs/user/products/collections.mdx b/docs/user/products/collections.mdx
new file mode 100644
index 0000000000..4577c1b84c
--- /dev/null
+++ b/docs/user/products/collections.mdx
@@ -0,0 +1,64 @@
+---
+title: "Collections"
+description: "Group products for merchandising — by hand or from rules that keep the group up to date."
+---
+
+Collections are flat groups of products used for merchandising: "Summer 2025", "Best Sellers", "Gifts Under $50". Unlike [Categories](/user/products/categories), they have no hierarchy and a product can belong to as many as you like.
+
+The useful part is that a collection can fill itself. Set rules once, and products join and leave as their tags, price or availability change — no list to maintain.
+
+To manage collections, open the **Collections** tab of the admin dashboard, found under Products.
+
+## Create a collection
+
+Click **New Collection**, give it a name, and save. You will land on the collection editor, where you decide how its products are chosen.
+
+## Choosing the products
+
+A collection is either curated by hand or driven by rules. The switch is **Set members automatically from rules**.
+
+<Tabs>
+ <Tab title="Curated by hand">
+ Leave the switch off and pick products yourself with **Add products**. Search, tick the ones you want, and they are added when you save.
+
+ Use this when the grouping is an editorial decision — a homepage feature, a gift guide — that no rule could express.
+
+ You can also set the order products appear in. Choose **Manual** sorting and drag rows into place; any other sort order is applied for you.
+ </Tab>
+ <Tab title="Filled from rules">
+ Turn the switch on and describe what belongs. Products matching the rules appear immediately and refresh on their own afterwards.
+
+ Choose whether products must match **all** conditions or **any** of them, then add one or more rules:
+
+ | Rule | Matches products that |
+ |---|---|
+ | Tag | carry a given product tag |
+ | On sale | are marked down — a compare-at price is set |
+ | Available on | were published within a date range |
+
+ Each rule takes a condition — *is equal to*, *is not equal to*, *contains*, *does not contain* — and a value.
+
+ The product list becomes read-only: the rules own membership, so there is nothing to curate by hand.
+ </Tab>
+</Tabs>
+
+<Note>
+Switching a collection from rules back to hand-picked clears nothing, but the products it had been matching are no longer members until you add them. Decide which way a collection works before you build a storefront page around it.
+</Note>
+
+## Storefront listing
+
+Collections have their own page on the storefront, so each one gets a name, description, images and search engine listing settings — the same fields a category has. The slug is what appears in the URL.
+
+## Translations
+
+If your store sells in more than one language, collection names and descriptions can be translated. See [Translations](/user/translations/translations).
+
+## Categories or collections?
+
+Both group products, and stores normally use both.
+
+- **Categories** are the shelves — a browsable tree a customer navigates. Fashion → Men → Footwear.
+- **Collections** cut across the shelves — everything on sale, everything new this season, everything under $50.
+
+A pair of trainers sits in one place in the category tree and may appear in several collections at once.
diff --git a/docs/user/reports/reports.mdx b/docs/user/reports/reports.mdx
new file mode 100644
index 0000000000..6def787caf
--- /dev/null
+++ b/docs/user/reports/reports.mdx
@@ -0,0 +1,69 @@
+---
+title: "Reports"
+description: "Answer questions about sales, payments and stock with saved reports you can group, filter, compare and export."
+---
+
+Reports answer questions about your store: what sold, where the money came from, what moved through the warehouse. Every report is built from the same two ingredients — **metrics** (the numbers) and a way to **group** them — so once you can read one, you can read them all.
+
+Find them under **Reports** in the dashboard.
+
+## Built-in reports
+
+Every store comes with a set of ready-made reports. They cover the questions most merchants ask first:
+
+| Area | Reports |
+|---|---|
+| Sales | Sales over time · Net sales over time · Sales by channel · Sales by market · Sales by country · Top products · Top categories · Top customers · Top companies · Product margin · Returns over time · First-time vs returning · Orders by payment status · Orders by fulfillment status |
+| Payments | Payments over time · Payments by method · Failed payments |
+| Stock | Stock movement over time · Sell-through by variant |
+| Marketplace | Seller payouts |
+
+Built-in reports are marked **Built-in** and cannot be edited directly. Use **Save a copy** to make your own version and change it.
+
+## Reading a report
+
+Open a report and it runs for the selected time range. What you see depends on how the report is grouped:
+
+- grouped by **time** — a chart, with one point per day, week or month
+- grouped by anything else — a ranked list, such as products by net sales
+- grouped by **nothing** — the totals
+
+Switch **Compare with previous period** on to see each figure against the same span before it.
+
+## Building your own
+
+Click **New report** and choose:
+
+- **Metrics** — at least one. Pick from the same vocabulary the built-in reports use: total sales, orders, average order value, net sales, units sold, gross profit, payments received, units shipped and so on.
+- **Group by** — the axis: a time interval, or a dimension such as product, category, channel, market, country, customer, company, seller or payment method. Or none, for totals only.
+- **Time range** — a preset, or a custom range.
+- **Filters** — narrow the rows, for instance to one channel or one market.
+- **Sort** and **Rows** — order the list and cap how many rows come back.
+
+Save it and it appears in the list for anyone on your team who can read reports.
+
+<Note>
+A report draws from one area at a time — sales, payments or stock. They are anchored on different moments (when the order completed, when the payment was taken, when stock moved), so a payment total beside a units-received count would be two reports wearing one table. The builder keeps them apart.
+</Note>
+
+## Money and currency
+
+A report answers in **one currency** — the one you choose, or the store's default. Amounts are never converted between currencies, so a store selling in several has as many answers as it has currencies. Percentages read the way a merchant reads them: a margin of 42.5%, not 0.425.
+
+## What the sales figures mean
+
+The built-in sales reports follow one chain, so a figure means what the same word means anywhere else:
+
+- **Gross sales** − discounts − returns = **Net sales**
+- Net sales + shipping + duties + fees + taxes = **Total sales**
+
+**Returns** counts money refunded in the period the refund was issued, not the period of the original sale.
+
+## Exporting
+
+**Export CSV** downloads the report's rows as a file. Exports run in the background and you are emailed when the file is ready.
+
+## Related
+
+- [Exporting orders](/user/orders/exporting-orders) — row-level order data rather than aggregates
+- [Sales Channels](/user/settings/sales-channels) and [Markets](/user/settings/markets) — the dimensions many reports group by
diff --git a/docs/user/sellers/commission-rates.mdx b/docs/user/sellers/commission-rates.mdx
new file mode 100644
index 0000000000..ea7ad320da
--- /dev/null
+++ b/docs/user/sellers/commission-rates.mdx
@@ -0,0 +1,68 @@
+---
+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."
+---
+
+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.
+
+Find them under **Sellers → Commission rates**.
+
+## A rate
+
+| Field | Meaning |
+|---|---|
+| 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 |
+
+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.
+
+## The list is the precedence
+
+This is the most important thing to understand, and it is deliberately simple.
+
+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.
+
+Two consequences:
+
+- **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.
+
+If nothing matches, **no commission is charged**. A marketplace with no rate covering a sale charges nothing rather than inventing a default nobody set.
+
+## Rules
+
+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.
+
+| Rule | Matches when the item is |
+|---|---|
+| 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 |
+
+So "electronics from these three sellers" is two rules on one rate.
+
+## What the fee is charged on
+
+- **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.
+
+## Tax on your commission
+
+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.
+
+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.
+
+## What gets recorded
+
+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.
+
+Sellers see their commission on each earning in their panel.
+
+## Related
+
+- [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
diff --git a/docs/user/sellers/managing-sellers.mdx b/docs/user/sellers/managing-sellers.mdx
new file mode 100644
index 0000000000..0a5909e2ea
--- /dev/null
+++ b/docs/user/sellers/managing-sellers.mdx
@@ -0,0 +1,39 @@
+---
+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
new file mode 100644
index 0000000000..9c64b126db
--- /dev/null
+++ b/docs/user/sellers/onboarding.mdx
@@ -0,0 +1,70 @@
+---
+title: "Onboarding"
+description: "Invite a seller, set the checklist they complete before they can sell, and approve them when it is done."
+---
+
+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.
+
+## The lifecycle
+
+| 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 |
+
+Only an **approved** seller can sell.
+
+## 1. Invite a seller
+
+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.
+
+## 2. The checklist
+
+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**.
+
+Every store starts with seven, all required:
+
+| 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 |
+
+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.
+
+For each one you choose:
+
+- **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.
+
+<Note>
+With no requirements at all, a seller can ask to be reviewed straight away.
+</Note>
+
+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).
+
+## 3. Review and approve
+
+When the seller finishes, they submit for review and move to **Ready for review**. Open their page:
+
+- 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.
+
+Your developers can turn on automatic approval, so a seller who completes every required item is approved the moment they submit.
+
+## Related
+
+- [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
diff --git a/docs/user/sellers/orders.mdx b/docs/user/sellers/orders.mdx
new file mode 100644
index 0000000000..d83a86e1b9
--- /dev/null
+++ b/docs/user/sellers/orders.mdx
@@ -0,0 +1,32 @@
+---
+title: "Marketplace Orders"
+description: "One checkout across several sellers becomes one order per seller — paid once, shipped separately, settled separately."
+---
+
+This is what makes a marketplace different from a shop, and it is worth understanding before anything else.
+
+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.
+
+| Level | Owns |
+|---|---|
+| Order group | The customer, the addresses, the single payment, the combined total |
+| Order | One seller's items, its fulfillments, its own money lines |
+
+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.
+
+## In the dashboard
+
+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.
+
+A basket with only one seller's products, or only your own, produces a single order with no group.
+
+## Who does what
+
+- **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.
+
+## Related
+
+- [Payouts](/user/sellers/payouts) — how a shipped order turns into money owed
+- [Processing Orders](/user/orders/processing-orders) — the order page in general
diff --git a/docs/user/sellers/payouts.mdx b/docs/user/sellers/payouts.mdx
new file mode 100644
index 0000000000..9a5d483b8d
--- /dev/null
+++ b/docs/user/sellers/payouts.mdx
@@ -0,0 +1,69 @@
+---
+title: "Payouts"
+description: "What each seller has earned, what they are owed, and how it reaches them — by hand, or through Stripe Connect."
+---
+
+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.
+
+## Transfers — the ledger
+
+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.
+
+A seller's page sums this into a **Balance** card:
+
+| Figure | Meaning |
+|---|---|
+| Earned | Everything recorded in their favour |
+| Pending | Earned, not yet included in a payout |
+| Owed | Ready to pay |
+| Paid | Already paid out |
+
+## Payouts — settlements
+
+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.
+
+| Status | Meaning |
+|---|---|
+| 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 |
+
+## The schedule
+
+Under **Settings → Payouts** you set the defaults:
+
+- **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.
+
+A seller can have their own schedule and minimum, set on their page under **Payouts and tax**; leave them blank to inherit the defaults.
+
+## How the money moves
+
+**Settings → Payouts** also chooses the **payout provider** — the thing that actually sends money.
+
+<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.
+
+ 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.
+
+ 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**.
+
+ Requires an active Stripe payment method under Settings → Payments. Setup is on the [Stripe Connect](/integrations/payments/stripe-connect) page.
+ </Tab>
+</Tabs>
+
+<Note>
+Refund clawbacks and netting across payouts, reconciliation, and seller tax reports are part of Spree Enterprise.
+</Note>
+
+## Related
+
+- [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
diff --git a/docs/user/sellers/products.mdx b/docs/user/sellers/products.mdx
new file mode 100644
index 0000000000..796d0326df
--- /dev/null
+++ b/docs/user/sellers/products.mdx
@@ -0,0 +1,36 @@
+---
+title: "Seller Products"
+description: "Sellers list their own products and submit them; you review each one before it goes 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.
+
+Sellers do not publish. They **submit**, and you decide.
+
+## The review queue
+
+A product a seller has submitted arrives with the status **Proposed**. Filter the Products list by that status to see everything waiting.
+
+Open one and you have two choices:
+
+- **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.
+
+The product page shows who decided, and when.
+
+Stores that trust their sellers can have submissions approved automatically — ask your developers to switch it on.
+
+## What sellers manage themselves
+
+From their panel, a seller looks after everything about how their products reach the customer:
+
+- **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.
+
+Delivery profiles and zones stay yours; a seller assigns a profile to each product rather than defining them.
+
+## Related
+
+- [Products](/user/products/creating-products) — the product editor, which is the same for a seller's products
+- [Managing sellers](/user/sellers/managing-sellers) — the seller behind the product
diff --git a/docs/user/sellers/sellers.mdx b/docs/user/sellers/sellers.mdx
new file mode 100644
index 0000000000..9859107858
--- /dev/null
+++ b/docs/user/sellers/sellers.mdx
@@ -0,0 +1,40 @@
+---
+title: "Sellers"
+description: "Run a marketplace — other businesses list on your store, ship their own orders, and get paid their share."
+---
+
+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 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.
+
+## What a seller owns
+
+| Theirs | Yours |
+|---|---|
+| 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 |
+
+## Where things live
+
+Sellers has its own section of the dashboard, and two settings pages beside it:
+
+- **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 → Payouts** — how and when sellers are paid
+
+## The shape of a marketplace sale
+
+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).
+
+## Related
+
+- [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
diff --git a/docs/user/settings/allowed-origins.mdx b/docs/user/settings/allowed-origins.mdx
new file mode 100644
index 0000000000..6720340ab3
--- /dev/null
+++ b/docs/user/settings/allowed-origins.mdx
@@ -0,0 +1,33 @@
+---
+title: "Allowed Origins"
+description: "The web addresses allowed to call your store's API from a browser — needed when your storefront or dashboard runs on its own domain."
+---
+
+Browsers refuse to let a page on one domain call an API on another unless the API says that domain is allowed. Allowed origins is that list: the addresses of your own sites that may talk to your store's API from a browser.
+
+Find it under **Settings → Allowed origins**.
+
+## When you need it
+
+You need an entry whenever something of yours runs on a **different domain** from the API:
+
+- a storefront at `https://www.mystore.com` calling an API at `https://api.mystore.com`
+- the admin dashboard hosted separately from Spree, for instance on a CDN
+- a mobile web app or a checkout widget embedded in another site
+
+If your storefront or dashboard is served from the same domain as the API, no entry is needed.
+
+## Adding one
+
+Click **Add allowed origin** and enter the address exactly as the browser sees it — scheme and host, such as `https://www.mystore.com`. No path, and the scheme matters: `http://` and `https://` are different origins.
+
+For local development, `http://localhost` matches any port, so one entry covers `localhost:3000`, `localhost:4000` and so on.
+
+## What else it protects
+
+Allowed origins also guard the links your store puts in emails. When a storefront asks for a password-reset or newsletter-confirmation email and says where the link should point, that address must be on this list — otherwise the link is dropped rather than sent. That stops a forged request from pointing your customers at a site you do not control.
+
+## Related
+
+- [API Keys](/user/settings/api-keys) — a publishable key still needs its origin allowed to work from a browser
+- [Deploying the dashboard](/developer/dashboard/deployment) — the cross-origin setup in full
diff --git a/docs/user/settings/api-keys.mdx b/docs/user/settings/api-keys.mdx
new file mode 100644
index 0000000000..6c22e6b83d
--- /dev/null
+++ b/docs/user/settings/api-keys.mdx
@@ -0,0 +1,37 @@
+---
+title: "API Keys"
+description: "Authorise storefronts, apps and integrations to call your store's API — and scope each key to exactly what it needs."
+---
+
+API keys are how anything outside the dashboard talks to your store: your storefront, a mobile app, an ERP sync, a reporting tool. Each key identifies the store and says what the caller may do.
+
+Find them under **Settings → API keys**.
+
+## Two kinds of key
+
+| Kind | Prefix | Used by | Safe to expose? |
+|---|---|---|---|
+| Publishable | `pk_` | Your storefront and other customer-facing apps | Yes — it only permits what a shopper could do anyway |
+| Secret | `sk_` | Server-to-server integrations calling the admin side | **Never.** Treat it like a password |
+
+A publishable key can be tied to a **sales channel**, so orders placed with it are attributed to that channel automatically. Leave the channel blank and the key works for all of them.
+
+## Scopes
+
+A secret key carries a list of **scopes** — read or write, per resource — that gate which operations it may perform. A key for a stock sync needs to write stock and read products, and nothing else. Grant only what the integration needs; there is no benefit to a broad key and real cost if it leaks.
+
+The scope picker offers starting points — read only, full access, or a role-shaped set such as order manager — that you can then narrow. Every resource an extension adds to your store becomes scopeable here too.
+
+## Creating a key
+
+Click **New key**, choose the kind, name it after what will use it, and — for a secret key — pick its scopes. The secret value is shown **once**, when the key is created. Copy it into your integration then; it cannot be shown again.
+
+## Rotating and revoking
+
+The list shows when each key was last used, which is how you spot ones that are dead. Revoke a key and every call made with it is refused immediately. To rotate, create the replacement first, move the integration over, then revoke the old one.
+
+## Related
+
+- [Sales Channels](/user/settings/sales-channels) — the channel a publishable key can be bound to
+- [Webhooks](/user/settings/webhooks) — the other direction: your store calling your systems
+- [Users](/user/settings/users) — staff access, which is separate from API keys
diff --git a/docs/user/settings/integrations.mdx b/docs/user/settings/integrations.mdx
new file mode 100644
index 0000000000..576640242b
--- /dev/null
+++ b/docs/user/settings/integrations.mdx
@@ -0,0 +1,35 @@
+---
+title: "Integrations"
+description: "Connect the external services your providers need — carriers, tax engines, and more — with credentials stored once per store."
+---
+
+Integrations are where you connect an outside service to your store: a carrier account for live shipping rates and labels, a tax engine, a fulfillment service. Each one holds the credentials that service needs, stored once per store, and every provider that uses that service reads them from here.
+
+Find them under **Settings → Integrations**.
+
+## What you will see
+
+Integrations arrive with **provider extensions**. Install a provider — the EasyPost provider, for example — and its integration appears on this page, grouped by what it does: Shipping, Tax, or Other. A store with no providers installed sees an empty page, and that is normal.
+
+Each integration shows its connection status:
+
+| Status | Meaning |
+|---|---|
+| Not connected | No credentials entered yet |
+| Connected (inactive) | Credentials saved and verified, but switched off |
+| Active | In use by providers |
+
+## Connecting one
+
+Open the integration and enter what the service asks for — typically an API key, sometimes an account identifier or a choice between a test and a live environment. Secrets are masked once saved.
+
+Turning an integration **active** verifies the connection first. If the service cannot be reached with those credentials, the switch is refused and the error tells you what the service said, so a mistyped key never silently breaks shipping or tax at checkout.
+
+## Where it is used
+
+Once active, the integration is picked from wherever a provider needs it. A delivery method that quotes live carrier rates points at the carrier integration; a market that uses an external tax engine points at the tax integration. Those pickers link back here, so there is one place credentials live and one place to rotate them.
+
+## Related
+
+- [Shipping Methods](/user/settings/shipping-methods) — delivery methods that quote through a carrier integration
+- [Tax](/user/settings/tax) — choosing a tax provider per market
diff --git a/docs/user/settings/marketplace.mdx b/docs/user/settings/marketplace.mdx
deleted file mode 100644
index be0e139f07..0000000000
--- a/docs/user/settings/marketplace.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
----
-title: "Marketplace Configuration"
-description: "Learn how to configure marketplace-wide settings for your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>Marketplace settings are only available in Spree Enterprise Edition with the multi-vendor module enabled.</Warning>
-
-The Marketplace settings page is the central place to configure how vendors operate on your marketplace by default. It's where you set the default commission rate new vendors will be invited under, how often vendors get paid, what merchants see when they install your Shopify app, and the terms of service every vendor agrees to. Most of these defaults can be overridden at a more granular level later (per vendor, category, or product), so think of this page as setting the baseline that everything else builds on.
-
-To configure marketplace settings, navigate to **Settings → Marketplace** in the admin dashboard.
-
-![The Marketplace settings page showing the commission rate, payouts, Shopify app, and terms of service sections](/docs/images/user/settings/marketplace/1-marketplace-overview.png)
-
-## Vendor Commission Rate
-
-This is the default percentage of each sale that your marketplace retains from a vendor's revenue. It applies to all newly invited vendors and can be overridden later per vendor, per category-vendor pairing, or per individual product.
-
-- **Commission Rate** - the percentage taken from each sale. Used as the default for all newly invited vendors.
-
-<Warning>Changing this value only affects newly invited vendors. Existing vendors keep their current commission rate — to update an existing vendor's rate, edit it from their vendor profile.</Warning>
-
-## Vendor Payouts
-
-This setting controls how frequently vendors can receive payouts through their Stripe dashboard. Vendors can choose to follow the marketplace default or set their own schedule from their vendor profile.
-
-- **Preferred Vendor Payouts Schedule Interval** - how often vendors are paid by default.
- - Daily
- - Weekly
- - Bi-weekly
- - Monthly
-
-<Note>Changing this option also updates the payout schedule for any existing vendors whose schedule is set to **Use marketplace default interval**. Vendors who have a specific schedule set won't be affected.</Note>
-
-## Shopify App
-
-If your marketplace uses the Shopify integration to onboard Shopify vendors, this image is displayed to Shopify merchants when they install your app. A clear, branded image helps vendors recognize the marketplace they're connecting to.
-
-- **Upload New Media** - the image shown on the Shopify install screen.
- - **Recommended size:** 600 × 300 pixels.
-
-<Note>For more on the broader Shopify vendor onboarding flow, see [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify).</Note>
-
-## Vendor Terms of Service
-
-The terms of service displayed to vendors when they accept their invitation to join the marketplace. Vendors must agree to these terms before they can complete onboarding. The editor supports rich formatting including headings, bold, italic, links, lists, quotes, and code blocks.
-
-- **Vendor Terms of Service** - the full terms vendors must agree to at invitation time.
-
-<Note>Updating the terms doesn't require existing vendors to re-accept — only vendors invited after the change will see the new version at sign-up.</Note>
-
-## Saving Changes
-
-After making any updates, click **Update** at the bottom of the page to save your changes, otherwise any changes you've made will not be saved.
diff --git a/docs/user/settings/markets.mdx b/docs/user/settings/markets.mdx
index 5bb1e68627..ec35d10561 100644
--- a/docs/user/settings/markets.mdx
+++ b/docs/user/settings/markets.mdx
@@ -72,4 +72,4 @@ bottom of the page.
- [<u>Zones</u>](https://spreecommerce.org/docs/user/settings/zones)
- [<u>Tax</u>](https://spreecommerce.org/docs/user/settings/tax)
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists)
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists)
diff --git a/docs/user/settings/package-types.mdx b/docs/user/settings/package-types.mdx
new file mode 100644
index 0000000000..70b802a287
--- /dev/null
+++ b/docs/user/settings/package-types.mdx
@@ -0,0 +1,39 @@
+---
+title: "Package Types"
+description: "The boxes, envelopes, cartons and pallets your goods ship in — with the dimensions and weights carrier quotes are built on."
+---
+
+Package types describe what you pack into: the mailer your parcels go out in, the cartons your products come in, the pallets a wholesale order leaves on. Their size and weight feed shipping quotes, so getting them right is what keeps carrier rates honest.
+
+Find them under **Settings → Package types**.
+
+## Kinds
+
+| Kind | Typical use |
+|---|---|
+| Box | A parcel |
+| Envelope | Documents, flat items |
+| Carton | A case of units, as it arrives from a supplier or ships wholesale |
+| Pallet | Many cartons, for freight |
+| Container | A shipping container |
+
+## Adding one
+
+Click **Add package type** and give it a name, a kind, and its geometry:
+
+- **Length, width, height** and their unit. Used for carrier dimensional weight, and for the cubic-metre tiers freight shipping compares.
+- **Empty weight** — the packaging itself, added to whatever it holds.
+- **Max weight** — what it can carry.
+
+## The default box
+
+Mark one package type as the **default box**. It is the packaging your parcel quotes are built on: its size and empty weight are added to every rate a carrier returns. There is one default at a time; marking another demotes the previous one.
+
+## For marketplaces
+
+Sellers keep their own package types in the seller panel, alongside the marketplace's. A seller can pack into the operator's standard cartons rather than measuring them again, or record their own — and each seller has their own default box for their own quotes.
+
+## Related
+
+- [Shipping Methods](/user/settings/shipping-methods) — the delivery methods that use these dimensions when quoting
+- [Purchase Orders](/user/inventory/purchase-orders) — stock arriving in cartons
diff --git a/docs/user/settings/product-types.mdx b/docs/user/settings/product-types.mdx
new file mode 100644
index 0000000000..7bd80a2fda
--- /dev/null
+++ b/docs/user/settings/product-types.mdx
@@ -0,0 +1,37 @@
+---
+title: "Product Types"
+description: "Templates for the kinds of thing you sell — so a new pair of shoes starts with the right options, categories and fields already in place."
+---
+
+Merchants who sell more than one kind of thing end up repeating themselves. Every pair of shoes needs Size and Colour, belongs under Footwear, and wants a Material field. Every book needs an ISBN and an author.
+
+A product type captures that once. Creating a product from a type gives it the right option types, the right categories, the right delivery profile, and a form that asks for the fields that kind of product actually needs.
+
+Find them under **Settings → Product types**.
+
+## Creating a type
+
+Click **New product type**, name it — "Footwear", "Books" — and choose what it seeds:
+
+| Setting | What a new product of this type gets |
+|---|---|
+| Option types | Its variant axes, such as Size and Colour |
+| Categories | Where it is filed by default |
+| Delivery profile | How it ships |
+| Custom fields | Which fields its edit form asks for, and which are marked required |
+
+## A type is a template, not a rule
+
+This is the part that decides how to think about them. A type is applied **when a product is created**. After that, the product is its own record:
+
+- Editing the type later does not change products already made from it. Add an option type to Footwear and existing shoes are untouched.
+- A product can be moved to a different type, or detached from its type, without losing anything.
+- **Required** on a custom field is advice to the person filling in the form, not a rule the server enforces.
+
+If you do want to push a type's option types and categories onto the products that already carry it, use **Apply to products**. It previews how many products will change, and only ever *adds* — it never removes what a product already has.
+
+## Related
+
+- [Creating Products](/user/products/creating-products) — choosing a type when a product is created
+- [Product Options](/user/manage-products/product-options) — the option types a product type seeds
+- [Custom Fields](/user/settings/metafields) — the field definitions a type can ask for
diff --git a/docs/user/settings/returns-configuration.mdx b/docs/user/settings/returns-configuration.mdx
index baf66c879f..e8065cd7a3 100644
--- a/docs/user/settings/returns-configuration.mdx
+++ b/docs/user/settings/returns-configuration.mdx
@@ -56,4 +56,4 @@ Rather than guessing, Spree gives your developers a place to attach your own pol
Once your reasons are set up, you are ready to handle returns, exchanges, and claims.
-To learn how, see [Returns → Returns Processing](/user/returns/returns-processing).
+To learn how, see [Returns → Returns Processing](/user/orders/returns).
diff --git a/docs/user/settings/sales-channels.mdx b/docs/user/settings/sales-channels.mdx
index 8eda27507a..ad815b7468 100644
--- a/docs/user/settings/sales-channels.mdx
+++ b/docs/user/settings/sales-channels.mdx
@@ -109,4 +109,4 @@ Opening an individual order shows the channel attribution in the order summary p
- [Spree Storefront API docs](https://spreecommerce.org/docs/api-reference/storefront)
- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets)
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists)
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists)
diff --git a/docs/user/settings/webhooks.mdx b/docs/user/settings/webhooks.mdx
new file mode 100644
index 0000000000..1d75bfb888
--- /dev/null
+++ b/docs/user/settings/webhooks.mdx
@@ -0,0 +1,43 @@
+---
+title: "Webhooks"
+description: "Have your store notify your other systems the moment something happens — an order placed, a product updated, a return received."
+---
+
+A webhook is your store calling out. When something happens — an order is placed, a payment succeeds, stock runs out — Spree sends the details to a URL you choose, so your warehouse system, accounting tool or CRM learns about it immediately rather than polling.
+
+Find them under **Settings → Webhooks**.
+
+## Adding an endpoint
+
+Click **Add webhook endpoint** and give it:
+
+- **URL** — where to send events. It must be reachable from your Spree server over HTTPS.
+- **Subscriptions** — which events to send. Pick individual events such as `order.placed`, or a whole family with a wildcard such as `order.*` for everything about orders.
+
+Each endpoint gets its own **signing secret**, shown once. Give it to whoever builds the receiving side — they use it to check each delivery really came from your store and was not tampered with.
+
+## Testing
+
+Use **Send test** to fire a sample event at the endpoint straight away. It shows up in the delivery log like any other, so you can confirm the receiver is wired up before real orders depend on it.
+
+## The delivery log
+
+Every attempt is recorded. **View deliveries** on an endpoint lists them with the event, the response code your system returned and how long it took. Open a delivery to see the exact payload that was sent and the response body that came back — the first place to look when a receiver misbehaves.
+
+| Status | Meaning |
+|---|---|
+| Pending | Queued, not yet sent |
+| Succeeded | Your endpoint answered with a success code |
+| Failed | Your endpoint answered with an error |
+| Error | Could not be delivered at all — a timeout, a DNS failure |
+
+A failed delivery is retried automatically, up to five times with increasing gaps between attempts, which rides out a brief outage on your side. After that it stays failed; **Redeliver** sends it again by hand once the receiver is fixed.
+
+## Disabling an endpoint
+
+**Disable** stops deliveries without deleting the endpoint or its history — useful while a receiver is being rebuilt. **Re-enable** when it is back. Deleting an endpoint removes its delivery history too.
+
+## Related
+
+- [API Keys](/user/settings/api-keys) — the other direction: your systems calling your store
+- [Webhooks for developers](/developer/core-concepts/webhooks) — payload format, signature verification and the full event list
diff --git a/docs/user/manage-products/translations.mdx b/docs/user/translations/translations.mdx
similarity index 100%
rename from docs/user/manage-products/translations.mdx
rename to docs/user/translations/translations.mdx
diff --git a/docs/user/user-quickstart-guide.mdx b/docs/user/user-quickstart-guide.mdx
index def5d922a0..fdf171a357 100644
--- a/docs/user/user-quickstart-guide.mdx
+++ b/docs/user/user-quickstart-guide.mdx
@@ -56,7 +56,7 @@ There are three ways to populate your store’s catalog:
- [<u>Add products manually</u>](https://spreecommerce.org/docs/user/products/creating-products) (ideal for small catalogs or testing)
- Import products using CSV (essential for large catalogs)
-- [<u>Invite vendors to add their own products</u>](https://spreecommerce.org/docs/user/vendors/invite-vendor) (for marketplaces - Spree Enterprise only)
+- [<u>Invite vendors to add their own products</u>](https://spreecommerce.org/docs/user/sellers/onboarding) (for marketplaces - Spree Enterprise only)
Click the **Add Products** button to start adding manually, or refer to the relevant articles based on your method.
@@ -115,7 +115,7 @@ See [<u>Shipping Methods</u>](https://spreecommerce.org/docs/user/settings/shipp
Once you’ve completed the basic setup, you’re ready to explore more advanced features and tailor your store to your business model. Here’s some recommended reading:
- [**<u>Learn how to manage orders</u>**](https://spreecommerce.org/docs/user/orders/processing-orders) - process payments, fulfill shipments, create and edit orders
-- [**<u>Learn how to process returns</u>**](https://spreecommerce.org/docs/user/returns/returns-processing) - configure returns flow, authorize returns, reimburse customers
+- [**<u>Learn how to process returns</u>**](https://spreecommerce.org/docs/user/orders/returns) - configure returns flow, authorize returns, reimburse customers
- [**<u>Launch a B2B storefront</u>**](https://spreecommerce.org/docs/use-case/b2b/b2b-commerce-model) - offer net terms, tiered pricing, company accounts, and purchase flows optimized for wholesale
- [**<u>Build a multi-vendor marketplace</u>**](https://spreecommerce.org/docs/use-case/marketplace/model) - invite third-party vendors to sell through your platform
- [**<u>Create a multi-tenant platform</u>**](https://spreecommerce.org/docs/use-case/multi-tenant/multi-tenant-model)  power multiple stores or clients from a single backend
diff --git a/docs/user/vendors/commission-rates.mdx b/docs/user/vendors/commission-rates.mdx
deleted file mode 100644
index 824e0a7ad3..0000000000
--- a/docs/user/vendors/commission-rates.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "Commission Rates"
-description: "Learn how to set and override commission rates across your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>Multi-vendor capabilities are only available in Spree Enterprise Edition.</Warning>
-
-Your commission rate is the percentage of each sale that your marketplace retains from a vendor's revenue — it's how the marketplace itself makes money, so getting it right matters. But "right" rarely means a single rate that fits every vendor and every product, which is why Spree lets you set commission rates at three different levels.
-
-You can start with a single default rate for the whole marketplace, override it for specific vendors when you bring them on, and then fine-tune it even further at the individual product level. The most specific rule always wins, so you can layer overrides confidently without worrying about conflicts.
-
-## 1. Default Marketplace Commission Rate
-
-The default rate is the baseline that applies to every newly invited vendor unless overridden. It's configured under **Settings → Marketplace** and is the rate every other level falls back on.
-
-See [<u>Marketplace Configuration</u>](https://spreecommerce.org/docs/user/settings/marketplace) for details on setting and updating the default.
-
-<Note>Changing the default rate only applies to vendors invited after the change — existing vendors keep their current rate. To update an existing vendor, use one of the vendor-specific methods below.</Note>
-
-## 2. Vendor-Specific Commission Rate
-
-You can set a custom commission rate for individual vendors in two ways: during the invitation flow, or from the vendor's profile after they've been invited.
-
-### When Inviting a Vendor
-
-For WooCommerce and Manual/CSV vendors, the Invite Vendor form includes a **Commission Rate** field where you can set the rate at the same time you send the invitation. This is the easiest way to onboard a vendor on a custom rate from day one.
-
-See [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce) or [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual) for the full invitation flow.
-
-<Note>Shopify vendors don't go through the email invitation flow, so commission rates for Shopify vendors are set from the vendor profile after they've signed up. See the next section.</Note>
-
-### From the Vendor Profile
-
-For existing vendors (and for Shopify vendors), you can update the commission rate at any time from their vendor profile.
-
-Navigate to **Vendors** in the admin dashboard and click on the vendor you'd like to update.
-
-![The Vendors tab showing the list of vendors](/docs/images/user/vendors/commission-rates/1-vendors-tab.png)
-
-Find the **Commission Rate** field on the vendor profile page and update it to the new percentage.
-
-![The vendor profile page with the Commission Rate field highlighted](/docs/images/user/vendors/commission-rates/2-vendor-commission-rate.png)
-
-Click **Update** at the bottom of the page to save your changes.
-
-## 3. Product-Specific Commission Rate
-
-For the most granular control, you can override the commission rate on individual products — useful when a vendor's catalog includes items with very different margins, or when you've struck a deal on a specific product with a vendor.
-
-Navigate to **Products** in the admin dashboard and open the product you'd like to update.
-
-![The Products tab showing the list of products](/docs/images/user/vendors/commission-rates/3-products-tab.png)
-
-Scroll down to the **Platform Fee** section of the product editor and update the commission rate.
-
-![The Platform Fee section of the product editor with the commission rate field](/docs/images/user/vendors/commission-rates/4-platform-fee.png)
-
-Click **Update** at the bottom of the page to save your changes.
-
-<Note>A product-specific commission rate overrides both the vendor-specific rate and the marketplace default for that product.</Note>
-
-## Which Rate Applies?
-
-When a sale is processed, Spree applies the most specific commission rate available, in the following order:
-
-1. **Product-specific rate** — if set on the product, this wins.
-2. **Vendor-specific rate** — if no product rate is set, the vendor's rate is used.
-3. **Marketplace default rate** — if neither of the above is set, the default applies.
-
-This means you can keep your overrides minimal — only set them where you genuinely need to deviate from the rate above.
diff --git a/docs/user/vendors/multi-vendor-checkout.mdx b/docs/user/vendors/multi-vendor-checkout.mdx
deleted file mode 100644
index 45cd7ea3b2..0000000000
--- a/docs/user/vendors/multi-vendor-checkout.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: "Multi-Vendor Checkout"
-description: "Learn how multi-vendor checkout works in Spree Commerce — customers shop across multiple vendors in a single cart and complete one unified checkout."
----
-
-<Warning>Multi-vendor capabilities are only available in Spree Enterprise Edition.</Warning>
-
-One of the biggest UX challenges in running a multi-vendor marketplace is the cart and checkout flow. Many marketplaces force customers to check out separately for each vendor — adding friction, hurting conversion rates, and frustrating shoppers who just want to buy what's in their cart and move on. Spree Commerce solves this with native multi-vendor checkout: customers can fill a single cart with products from any number of vendors, pick the shipping method they want for each vendor's package, pay once, and receive separate tracking updates as each vendor fulfills their part of the order.
-
-Best of all, there's nothing to configure. Multi-vendor checkout is supported out of the box with the Spree Next.js Storefront starter — as long as your marketplace is running on the multi-vendor module and the Next.js storefront, customers will get the full multi-vendor checkout experience automatically.
-
-## How It Works
-
-### Adding Items from Multiple Vendors
-
-Customers shop across all vendor catalogs as one experience. Products from different vendors are added to a single shared cart — to the customer, it feels like shopping any normal online store.
-
-![A cart containing items sold by multiple vendors](/docs/images/user/vendors/multi-vendor-checkout/1-multi-vendor-cart.png)
-
-### Selecting Shipping Methods at Checkout
-
-At checkout, customers are shown the shipping methods available for each vendor's package separately, grouped by vendor. They select one shipping method per vendor and continue without needing to leave the checkout flow.
-
-![The checkout shipping step showing per-vendor shipping method selectors](/docs/images/user/vendors/multi-vendor-checkout/2-shipping-methods.png)
-
-This is where Spree's multi-vendor checkout really shines: shoppers retain full control over how each shipment is fulfilled (express, standard, pickup, etc.) without juggling multiple separate checkouts.
-
-### Completing Payment
-
-The customer pays once for the full order, with all vendor totals consolidated into a single transaction. Behind the scenes, Spree records the order as a single customer purchase but prepares it to be split into separate suborders for downstream processing.
-
-## What Happens After Checkout
-
-Once the order is placed, Spree automatically splits it into suborders — one per vendor involved in the order. Each suborder is then routed to where the vendor will actually fulfill it:
-
-- **Manual/CSV vendors** see their suborder in their Spree vendor dashboard.
-- **Shopify vendors** see their suborder in their Shopify admin (in addition to their Spree vendor dashboard), thanks to the marketplace's Shopify sales channel app.
-- **WooCommerce vendors** see their suborder in their WooCommerce admin (in addition to their Spree vendor dashboard), via the WooCommerce integration.
-
-This means each vendor handles the part of the order that belongs to them in the environment they're most comfortable with — without ever needing to see or coordinate with other vendors involved in the same customer purchase.
-
-## Fulfillment and Tracking
-
-Each vendor ships their portion of the order independently — using their own carriers, packaging, and timelines. As each vendor marks their package as fulfilled in their dashboard, the customer receives a separate tracking email for that specific shipment.
-
-A customer who ordered from three vendors will receive three independent tracking notifications as each package ships, with no risk of confusion between them. From the marketplace's perspective, all of this happens automatically — no manual coordination is required between vendors, the marketplace owner, or the customer.
-
-## Next Steps
-
-For more on how vendors fulfill orders from their own dashboards, see the relevant onboarding guide:
-
-- [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify)
-- [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce)
-- [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual)
-
-For marketplace-wide configuration that affects checkout (including commission rates and payout schedules), see [<u>Marketplace Configuration</u>](https://spreecommerce.org/docs/user/settings/marketplace).
diff --git a/docs/user/vendors/vendor-management.mdx b/docs/user/vendors/vendor-management.mdx
deleted file mode 100644
index f86b613622..0000000000
--- a/docs/user/vendors/vendor-management.mdx
+++ /dev/null
@@ -1,147 +0,0 @@
----
-title: "Vendor Management"
-description: "Learn how to view, manage, and configure vendors from the admin dashboard in Spree Commerce."
----
-
-<Warning>Multi-vendor capabilities are only available in Spree Enterprise Edition.</Warning>
-
-Running a marketplace means juggling relationships with potentially dozens or hundreds of vendors — each at a different stage of onboarding, with their own product catalogs, revenue trajectories, and operational needs. The Vendors tab is mission control for all of it.
-
-From a single page, you can see the status of every vendor, dig into any individual vendor's full profile to manage their branding, commission rate, payout schedule, and storefront policies, and review their products, orders, and team in detail. Whether you're approving a new vendor that just finished onboarding, troubleshooting one that's stuck, or pulling lifetime revenue figures for a top performer, this is where it all happens.
-
-To get started, navigate to **Vendors** in the admin dashboard.
-
-## Vendor List Overview
-
-The main table displays every vendor on your marketplace alongside key metrics and status indicators.
-
-![The Vendors tab showing the full list of vendors with status, integration, and revenue columns](/docs/images/user/vendors/vendor-management/1-vendor-list.png)
-
-The default columns are:
-
-- **Name** - the vendor's brand or company name.
-- **Status** - the current state of the vendor relationship:
- - **Invited** - invitation sent, not yet accepted.
- - **Onboarding** - vendor is working through onboarding tasks.
- - **Ready for Review** - vendor has completed onboarding and is awaiting your approval.
- - **Approved** - vendor is live and selling on the marketplace.
- - **Rejected** - vendor was not approved during review.
- - **Suspended** - vendor's access has been temporarily revoked.
-- **Onboarding Progress** - a count of completed onboarding tasks (e.g., 4/6).
-- **Integration** - the vendor's connection type:
- - **Shopify**
- - **WooCommerce**
- - **N/A** (Manual/CSV vendors)
-- **Products** - total number of products in the vendor's catalog.
-- **Revenue** - lifetime sales generated by the vendor.
-- **Commission** - lifetime commission your marketplace has earned from the vendor.
-- **Created At** - when the vendor was first invited.
-
-From this view you can apply filters, sort by any column, customize the visible columns, and export the data by clicking **Export** in the top right corner.
-
-## Managing a Vendor
-
-To manage a specific vendor, click their row in the table to open their full vendor profile.
-
-![A vendor profile page showing the branding panel, onboarding progress, and account information sections](/docs/images/user/vendors/vendor-management/2-vendor-profile.png)
-
-From the vendor profile you can view and configure the sections below.
-
-### Branding
-
-![The Branding panel of the vendor profile with fields for About, Logo, Square Logo, and Cover Photo](/docs/images/user/vendors/vendor-management/3-branding.png)
-
-Click **Edit** at the top of the profile to open the branding panel. You can configure:
-
-- **About** - a short description of the vendor.
-- **Logo** - the vendor's primary logo (rectangular formats supported).
-- **Square Logo** - recommended for avatars and compact display areas.
-- **Cover Photo** - a wider banner image, similar to a Facebook cover photo.
-
-These assets may be displayed on the vendor's storefront pages and within their vendor dashboard.
-
-### Onboarding Progress
-
-![The Onboarding Progress section showing a checklist of completed and outstanding tasks](/docs/images/user/vendors/vendor-management/4-onboarding-progress.png)
-
-A detailed breakdown of which onboarding tasks the vendor has and hasn't completed.
-
-This helps you:
-
-- Identify blockers that are holding a vendor up.
-- Follow up with vendors who are stuck mid-flow.
-- Approve vendors once they've met all the requirements.
-
-For a walkthrough of what vendors see during onboarding, see [<u>Shopify</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify), [<u>WooCommerce</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce), or [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual).
-
-### Account Information
-
-![The Account Information section displaying commission rate, product count, total sales, and country](/docs/images/user/vendors/vendor-management/5-account-information.png)
-
-A quick snapshot of vendor performance and financial terms:
-
-- **Commission Rate** - the rate currently applied to this vendor. Click the pencil icon to update.
-- **Number of Products** - total products in the vendor's catalog.
-- **Total Sales** - lifetime sales generated by the vendor.
-- **Country / Location** - the vendor's registered country.
-
-For more on how commission rates work across the marketplace, see [<u>Commission Rates</u>](https://spreecommerce.org/docs/user/vendors/commission-rates).
-
-### Payments & Payouts
-
-![The Payments & Payouts section showing the Stripe Account ID and payout schedule dropdown](/docs/images/user/vendors/vendor-management/6-payments-payouts.png)
-
-If the vendor is using Stripe Connect, you can manage their payout setup here:
-
-- **Stripe Account ID** - copy the vendor's Stripe Account ID for reference or support purposes.
-- **Payout Schedule** - how often the vendor receives payouts. Options:
- - **Daily**
- - **Weekly**
- - **Bi-weekly**
- - **Monthly**
- - **Use Marketplace Default Interval**
-
-<Warning>Stripe Connect is only available in Spree Enterprise Edition. If your marketplace uses a different payment provider, payout schedule controls won't be available here.</Warning>
-
-For more on configuring payout schedules across the marketplace, see [<u>Vendor Payouts</u>](https://spreecommerce.org/docs/user/vendors/vendor-payouts).
-
-### Returns & Billing Address
-
-![The Returns & Billing Address section displaying the vendor's registered addresses](/docs/images/user/vendors/vendor-management/7-returns-billing.png)
-
-These sections display the vendor's registered returns and billing addresses. Both are view-only — vendors update their own addresses from their vendor dashboard.
-
-## Vendor Subtabs
-
-Similar to customer profiles, the vendor profile includes several subtabs for deeper management of the vendor's activity.
-
-![The row of subtabs on a vendor profile, including Overview, Products, Orders, Users, Invitations, and Policies](/docs/images/user/vendors/vendor-management/8-vendor-subtabs.png)
-
-### Overview
-
-A sales-over-time graph and a list of the vendor's top-performing products — useful for a quick performance read at any point.
-
-### Products
-
-Every product associated with the vendor. From here you can apply filters, sort results, perform bulk actions, and review product-level performance.
-
-### Orders
-
-Every order placed with the vendor. You can filter orders, review payment and shipment states, and monitor fulfillment activity.
-
-### Users
-
-All vendor users associated with the account — that is, users who have accepted invitations and now have access to the vendor dashboard. Useful for tracking who on the vendor's team has access.
-
-### Invitations
-
-All invitations sent to vendor users. From this tab you can see invitation status, copy pending invite links, and monitor which users haven't yet joined.
-
-### Policies
-
-The vendor's policies, including:
-
-- **Returns Policy** (default)
-- Any other policies you require from the vendor
-
-Admins can edit these policies directly from this section.
diff --git a/docs/user/vendors/vendor-onboarding-manual.mdx b/docs/user/vendors/vendor-onboarding-manual.mdx
deleted file mode 100644
index 0dc9959f2f..0000000000
--- a/docs/user/vendors/vendor-onboarding-manual.mdx
+++ /dev/null
@@ -1,158 +0,0 @@
----
-title: "Manual/CSV Vendor Onboarding"
-description: "Learn how to invite and onboard a vendor who'll upload products manually or via CSV to your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>Multi-vendor capabilities are only available in Spree Enterprise Edition.</Warning>
-
-<Note>This guide covers vendors who'll add products manually through the vendor dashboard or import them via CSV. For other vendor types, see [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify) and [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce).</Note>
-
-Not every vendor will be running on Shopify or WooCommerce. Some don't yet have an online store at all, some use platforms without a direct Spree integration, and some simply prefer to manage their marketplace catalog independently. For all of these cases, the Manual/CSV onboarding path is the catch-all — it works with any vendor regardless of their backend setup.
-
-Onboarding a Manual/CSV vendor has two distinct parts: an **Admin Setup** that the marketplace owner completes by sending an invitation, and a **Vendor Onboarding** flow that the vendor themselves completes after receiving the invite.
-
-## Prerequisites
-
-Before you can onboard Manual/CSV vendors, you'll need:
-
-- The **`spree_multi_vendor` Enterprise gem** installed on your Spree instance.
-
----
-
-## Admin Setup
-
-This section is for the marketplace owner. Inviting a Manual/CSV vendor uses the same invitation flow as WooCommerce vendors — the vendor selects their preferred method (manual or CSV) during their own onboarding.
-
-### Send the Invitation
-
-To invite a vendor, navigate to **Vendors** in the admin dashboard.
-
-![The Vendors tab listing all vendors invited or onboarded to the marketplace](/docs/images/user/vendors/vendor-onboarding-manual/1-vendors-tab.png)
-
-Click **Invite Vendor** in the top right corner to open the invitation form.
-
-![The Invite Vendor form with fields for company name, contact email, and commission rate](/docs/images/user/vendors/vendor-onboarding-manual/2-invite-vendor.png)
-
-Fill in the following fields:
-
-- **Company Name or Brand Name** - how the vendor will be displayed in the admin dashboard.
-- **Contact Person Email** - the work email address of the person who should receive the invitation.
-- **Commission Rate** - the pre-agreed commission rate to be shared with the marketplace.
-
-<Note>The commission rate can be different for each vendor and updated later from the vendor's profile.</Note>
-
-Double-check the details and click **Send Invitation**. The newly invited vendor will appear in your list of vendors with a pending status.
-
-![The Vendors list showing the newly invited vendor with a pending invitation status](/docs/images/user/vendors/vendor-onboarding-manual/3-invitation-sent.png)
-
-The vendor will receive an email at the specified address with a link to begin onboarding.
-
-### Share the Invitation Link Manually
-
-If the vendor doesn't receive the email, or they prefer a different communication channel, you can copy the invitation link and send it directly.
-
-Click on the vendor in the list to open their vendor profile, navigate to the **Invitations** subtab, click the three-dot menu, and select **Copy invitation link**.
-
-![The Invitations subtab with the three-dot menu opened to show the Copy invitation link option](/docs/images/user/vendors/vendor-onboarding-manual/4-invitation-link.png)
-
-### Cancel an Invitation
-
-If you need to withdraw the invitation — whether the wrong contact was invited, the vendor's details need correcting, or the partnership ended before they began onboarding — navigate to the **Invitations** subtab as above, click the three-dot menu, and select **Delete**.
-
-<Warning>Cancelling an invitation is irreversible. To re-invite the vendor later, you'll need to start the invitation flow from scratch.</Warning>
-
----
-
-## Vendor Onboarding
-
-This section is for the vendor. Once you've received the invitation from the marketplace owner, follow these steps to set up your vendor account and start adding products.
-
-### 1. Accept the Invitation
-
-You'll receive an email invitation from the marketplace owner with a link to get started. Click the link to be directed to your vendor account creation page.
-
-### 2. Create Your Vendor Account
-
-Fill in the sign-up form to create your vendor account, then click **Create Account**.
-
-![The Spree vendor account sign-up form](/docs/images/user/vendors/vendor-onboarding-manual/5-account-signup.png)
-
-You'll then be redirected to your new vendor dashboard, where you'll see a **Getting Started** checklist of onboarding tasks.
-
-![The Getting Started onboarding checklist in the Spree vendor dashboard](/docs/images/user/vendors/vendor-onboarding-manual/6-getting-started-tasks.png)
-
-### 3. Set Up Your Shop
-
-Click on the **Connect or Create a Shop** task in the checklist, then click **Use CSV and/or Admin dashboard**.
-
-![The Connect or Create a Shop task expanded showing Shopify, WooCommerce, and Use CSV and/or Admin dashboard options](/docs/images/user/vendors/vendor-onboarding-manual/7-connect-shop-options.png)
-
-The task will be marked complete and you'll be ready to start adding products.
-
-### 4. Add Your Products
-
-Unlike vendors who connect Shopify or WooCommerce, you'll need to add products to your marketplace catalog yourself. You have two options:
-
-- **Add products manually, one-by-one** — best for small catalogs or when you're testing things out. See [<u>Create a Product</u>](https://spreecommerce.org/docs/user/products/creating-products) for the full walkthrough of the product editor.
-- **Upload products in bulk via CSV** — best for larger catalogs or when migrating from another platform. See [<u>Import Products</u>](https://spreecommerce.org/docs/user/manage-products/import-products) for a step-by-step guide to preparing and uploading your CSV file.
-
-You can mix and match these methods as needed — for example, bulk-importing the initial catalog and then adding new products manually as they're released.
-
-### 5. Complete Your Remaining Onboarding Tasks
-
-With your shop set up, you'll still need to complete a few more tasks before you can start selling.
-
-#### Add Billing Address
-
-Your company's billing address is needed for vendor payouts and invoices. Click on the task in your checklist, fill in the form, and click **Save**.
-
-![The Add Billing Address task expanded with the billing form fields](/docs/images/user/vendors/vendor-onboarding-manual/8-billing-address.png)
-
-#### Connect Your Stripe Account
-
-Stripe is used by the marketplace to process payments and send your payouts. To receive your earnings, you'll need to connect a Stripe account.
-
-1. Click on **Connect Stripe Account** in your onboarding checklist.
-2. Click **Connect your bank account** to be guided through Stripe's short onboarding process.
-3. Follow the Stripe prompts to set up a new account or connect an existing one.
-
-![The Connect Stripe Account task expanded in the onboarding checklist](/docs/images/user/vendors/vendor-onboarding-manual/9-connect-stripe.png)
-
-An existing Stripe account isn't required — you can create one as part of this flow. The whole process usually takes around five minutes. Once connected, you'll receive payouts whenever you ship orders.
-
-<Note>If you're not the one handling your company's financials, you can invite another team member to complete this step instead.</Note>
-
-<Warning>Some marketplaces use payment providers other than Stripe. If that's the case, you'll be prompted to connect your bank account through a different flow — your marketplace owner will let you know the specifics.</Warning>
-
-#### Add Returns Address
-
-A returns address ensures customers know where to send returns. Click on the task in your checklist, enter your company's return address, and click **Save**.
-
-![The Add Returns Address task expanded with the address form fields](/docs/images/user/vendors/vendor-onboarding-manual/10-returns-address.png)
-
-#### Set Shipping Rates
-
-Since you're not connecting an external store, you'll need to add your shipping methods and rates manually.
-
-Click on the **Set Shipping Rates** task, then click **Manage Shipping Rates** to be taken to the **Settings → Shipping** section of your vendor dashboard. Add each shipping method you'd like to offer along with its rate, then click **Confirm Shipping Rates** in the top right corner.
-
-![The Shipping Methods page in the vendor dashboard with fields for adding methods and rates](/docs/images/user/vendors/vendor-onboarding-manual/11-shipping-rates.png)
-
-<Note>You can edit existing shipping methods or add new ones at any time after onboarding is complete.</Note>
-
-#### Add Policies
-
-A clear returns policy builds customer trust, sets clear expectations, and helps prevent disputes over returns and refunds.
-
-1. Click on **Add Policies** to be redirected to **Settings → Policies**.
-2. Click on the policy you'd like to update to enter the editor.
-3. Paste your policy into the text field.
-4. Click **Save**.
-
-![The Policies tab in the Spree Commerce vendor dashboard showing an unfilled returns policy](/docs/images/user/vendors/vendor-onboarding-manual/12-returns-policy.png)
-
-## Next Steps
-
-Once onboarding is complete, your products will be sent to the marketplace owner for review. Once they're approved, they'll go live on the storefront, and you can manage your business directly from your Spree vendor dashboard.
-
-For other vendor types, see [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify) or [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce).
diff --git a/docs/user/vendors/vendor-onboarding-shopify.mdx b/docs/user/vendors/vendor-onboarding-shopify.mdx
deleted file mode 100644
index 8b08a430f0..0000000000
--- a/docs/user/vendors/vendor-onboarding-shopify.mdx
+++ /dev/null
@@ -1,213 +0,0 @@
----
-title: "Shopify Vendor Onboarding"
-description: "Learn how to invite and onboard a Shopify-based vendor to your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>Shopify vendor onboarding is only available in Spree Enterprise Edition.</Warning>
-
-<Note>This guide covers vendors who'll connect their Shopify store to your marketplace. For other vendor types, see [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce) and [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual).</Note>
-
-Shopify is one of the most common platforms your prospective vendors will already be running on, so it's worth setting up a smooth, automated path for them to join your marketplace. With the right setup in place, a Shopify vendor can connect their store in just a few clicks — products, inventory, orders, and shipping all sync between Shopify and your marketplace automatically.
-
-Onboarding a Shopify vendor has two distinct parts: a one-time **Admin Setup** that the marketplace owner completes per vendor in their Shopify Partners account and Spree admin, and a much shorter **Vendor Onboarding** flow that the vendor themselves completes after receiving the install link.
-
-## Prerequisites
-
-Before you can onboard Shopify vendors, you'll need:
-
-- A **Shopify Partners account** — this is where you'll create the custom Shopify apps used to connect each vendor's store.
-- The **`spree_multi_vendor` Enterprise gem** installed on your Spree instance.
-
-### How Spree Connects to a Vendor's Shopify Store
-
-Before you start, it's worth understanding how Spree's Shopify integration is structured — Shopify supports several different patterns for building and distributing apps, and we want to be explicit about which one applies here.
-
-Spree connects each vendor's store using a **Custom App distributed via Custom Distribution** — Shopify's recommended path for apps built for specific, known stores (such as the vendors on your marketplace). You can read more in [<u>Shopify's Custom Apps overview</u>](https://help.shopify.com/en/manual/apps/about-apps#custom-apps).
-
-Everything you need to set up is available **directly in the Shopify Partners UI**. You do not need to:
-
-- Use the Shopify CLI
-- Maintain a separate codebase for the Shopify app
-
-This setup is repeated once per Shopify vendor — each vendor gets their own dedicated Custom App so that their store can be installed and authorized independently.
-
-<Note>Spree's integration does not use the Shopify Sales Channel App pattern, despite some surface-level overlap.</Note>
-
----
-
-## Admin Setup
-
-This section is for the marketplace owner. It's a one-time setup per vendor — once complete, the vendor only needs to install the app and complete a few onboarding tasks.
-
-### 1. Create the Shopify App
-
-Each Shopify vendor requires their own dedicated app, created from your Shopify Partners account.
-
-1. Sign in to your **Shopify Partners** account and open the **Dev Dashboard**.
-2. Click **Create app**.
-3. Give the app a name that identifies which vendor it's for. We recommend writing the name in kebab-case (lowercase words separated by hyphens), e.g., `example-vendor`.
-4. You'll be redirected to the **Versions → Create version** page. Fill in the form using the values below:
-
- - **App name** - already pre-filled from the previous step.
- - **App URL** - `<app-base-url>/shopify/apps/<app-handle>` (e.g., `https://spree-marketplace.com/shopify/apps/example-vendor`).
- - The `<app-base-url>` should point to your store URL. If you have multiple stores, we recommend using the URL of the default store.
- - The `<app-handle>` can be set arbitrarily but must be unique across all your Shopify apps. We recommend using the app name from step 3 (already in kebab-case).
- - **Embed app in Shopify admin** - leave unchecked.
- - **Preferences URL** - leave empty.
- - **Webhooks API Version** - `2025-07`.
- - **Scopes** - paste the following list exactly:
- ```
- write_orders,read_inventory,read_products,read_fulfillments,read_locations,read_translations,read_locales,read_shipping
- ```
- - **Optional scopes** - leave empty.
- - **Use legacy install flow** - leave unchecked.
- - **Redirect URLs** - add both of the following:
- - `<app-base-url>/shopify/apps/<app-handle>/auth`
- - `<app-base-url>/shopify/apps/<app-handle>/auth_callback`
-
-5. Click **Release** at the bottom of the form, then confirm in the modal that appears.
-
-After completing these steps, you should see an overview of the version you just released.
-
-![The completed Create version form in the Shopify Dev Dashboard with all required fields filled in](/docs/images/user/vendors/vendor-onboarding-shopify/1-create-version-form.png)
-
-### 2. Get the App's Credentials
-
-Spree needs the app's Client ID and Secret to authenticate against Shopify.
-
-1. In the **Shopify Dev Dashboard**, select the app you just created.
-2. Open the app's **Settings** page.
-3. Copy and save both the **Client ID** and the **Secret**.
-
-![The app Settings page in the Shopify Dev Dashboard with the Client ID and Secret fields](/docs/images/user/vendors/vendor-onboarding-shopify/5-app-credentials.png)
-
-### 3. Register the App in Spree
-
-Now register the new Shopify app inside your Spree admin so the marketplace can communicate with it.
-
-1. In the Spree admin dashboard, navigate to **Settings → Shopify Apps**.
-
-![The Shopify Apps page in the Spree admin dashboard listing any existing connected apps](/docs/images/user/vendors/vendor-onboarding-shopify/6-spree-shopify-apps.png)
-
-2. Click **New Shopify App** in the top right corner.
-3. Fill in the form and click **Create**:
- - **Handle** - must match the `<app-handle>` you used in step 1 (e.g., `example-vendor`).
- - **Name** - can be anything, but we recommend matching the handle for consistency.
- - **Client ID** - paste the Client ID from step 2.
- - **Secret** - paste the Secret from step 2.
-
-![The New Shopify App form in Spree with Handle, Name, Client ID, and Secret fields](/docs/images/user/vendors/vendor-onboarding-shopify/7-new-shopify-app-form.png)
-
-### 4. Generate the Install Link
-
-With the app created and connected to Spree, the next step is to generate the install link the vendor will use to connect their store.
-
-1. From the app's **Overview** page in the **Shopify Partner dashboard**, click **Select distribution method**.
-
-![The Shopify app Overview page with the Select distribution method button highlighted](/docs/images/user/vendors/vendor-onboarding-shopify/2-select-distribution-method.png)
-
-2. Choose **Custom Distribution** and click **Select**. Confirm in the modal.
-
-![The distribution method dialog with Custom Distribution selected](/docs/images/user/vendors/vendor-onboarding-shopify/3-custom-distribution.png)
-
-3. Fill in the Distribution form:
- - **Store domain** - the vendor's Shopify store domain, formatted as either `<shopify-domain>.myshopify.com` or `admin.shopify.com/store/<shopify-domain>` (e.g., `admin.shopify.com/store/jessicas-gym`).
- - **Allow multi-store install for one Plus organization** - leave this unchecked.
-4. Click **Generate link** and confirm in the modal.
-5. Copy the **install link** and save it — you'll send this to the vendor in step 5.
-
-![The generated install link displayed in the Shopify Dev Dashboard, ready to copy](/docs/images/user/vendors/vendor-onboarding-shopify/4-install-link.png)
-
-### 5. Share the Install Link with the Vendor
-
-Send the install link you saved in step 4 to the vendor through any communication channel — email, Slack, or whatever you normally use. From here, the rest of the flow is on the vendor — see the **Vendor Onboarding** section below for what they'll experience.
-
-<Note>Vendor accounts are set up with the Shopify store owner's email address. If you're connecting multiple Shopify stores that share an owner email, each store will need a unique email set under **Shopify Store Settings → General → Store details**.</Note>
-
-<Warning>If you're testing the flow yourself, make sure you're signed out of the marketplace owner account before opening the install link — otherwise installation will fail. If that happens, simply open the install link again.</Warning>
-
----
-
-## Vendor Onboarding
-
-This section is for the vendor. Once you've received the install link from the marketplace owner, follow these steps to connect your Shopify store and complete your onboarding.
-
-### 1. Install the Shopify App
-
-1. Open the install link the marketplace owner sent you.
-2. Log in to Shopify and select the store you'll be connecting to the marketplace.
-
-![The Shopify store selection screen the vendor sees after opening the install link](/docs/images/user/vendors/vendor-onboarding-shopify/8-vendor-store-select.png)
-
-3. Accept the app installation.
-
-![The Shopify app installation acceptance screen with the Install button](/docs/images/user/vendors/vendor-onboarding-shopify/9-vendor-accept-install.png)
-
-### 2. Create Your Vendor Account
-
-After accepting the installation, you'll be redirected to a Spree onboarding screen and asked to create a vendor account.
-
-![The Spree vendor account creation screen presented after the vendor accepts the Shopify app installation](/docs/images/user/vendors/vendor-onboarding-shopify/10-vendor-account-creation.png)
-
-Fill in the form and submit. A few minutes after submitting, your Shopify products will start appearing in your Spree vendor dashboard.
-
-### 3. Complete Your Onboarding Tasks
-
-When you arrive at your vendor dashboard, you'll see a **Getting Started** checklist. Most tasks are auto-completed for Shopify vendors thanks to the integration, but a few still need your attention.
-
-![The Getting Started onboarding checklist in the Spree vendor dashboard](/docs/images/user/vendors/vendor-onboarding-shopify/11-getting-started-tasks.png)
-
-#### Auto-Completed Tasks
-
-The following tasks are marked complete automatically when you install the app — just verify the imported information is correct:
-
-- **Connect or Create a Shop** — completed by the app installation itself.
-- **Add Billing Address** — imported from your Shopify store's billing details.
-- **Add Returns Address** — imported from your Shopify store's address.
-- **Add Returns Policy** — imported from your Shopify store, provided you have a returns policy configured there.
-
-#### Confirm Shipping Rates
-
-Your Shopify shipping methods and rates are synced automatically, but you still need to confirm them to mark this task complete.
-
-Navigate to **Settings → Shipping** in your vendor dashboard and click **Confirm Shipping Rates** in the top right corner.
-
-![The Shipping Methods page in the vendor dashboard with the Confirm Shipping Rates button](/docs/images/user/vendors/vendor-onboarding-shopify/12-confirm-shipping-rates.png)
-
-<Note>You can edit existing shipping methods or add new ones at any time before or after onboarding is complete.</Note>
-
-#### Connect Your Stripe Account
-
-<Warning>Some marketplaces use payment providers other than Stripe. If that's the case, you'll be prompted to connect your bank account through a different flow — your marketplace owner will let you know the specifics.</Warning>
-
-Stripe is used by the marketplace to process payments and send your payouts. To receive your earnings, you'll need to connect a Stripe account.
-
-1. Click on **Connect Stripe Account** in your onboarding checklist.
-2. Click **Connect your bank account** to be guided through Stripe's short onboarding process.
-3. Follow the Stripe prompts to set up a new account or connect an existing one.
-
-![The Connect Stripe Account task expanded in the onboarding checklist](/docs/images/user/vendors/vendor-onboarding-shopify/13-connect-stripe.png)
-
-An existing Stripe account isn't required — you can create one as part of this flow. The whole process usually takes around five minutes. Once connected, you'll receive payouts whenever you ship orders.
-
-<Note>If you're not the one handling your company's financials, you can invite another team member to complete this step instead.</Note>
-
----
-
-## What Syncs Between Shopify and the Marketplace
-
-Once your Shopify store is connected, the following data syncs automatically:
-
-- **Active products** are imported into the marketplace catalog.
-- **Inventory levels** sync in both directions in real-time.
-- **Shipping methods and rates** sync from Shopify to the marketplace.
-- **Orders** placed on the marketplace appear in your Shopify dashboard for fulfillment, just like normal Shopify orders.
-- **Fulfillment status and shipment tracking** sync back to the marketplace and trigger customer notifications automatically.
-- **Price updates** made in Shopify sync to the marketplace.
-- **Content updates** (descriptions, images) sync to the marketplace, unless the marketplace owner has edited them.
-
-## Next Steps
-
-Once onboarding is complete, your products will be sent to the marketplace owner for review. Once they're approved, they'll go live on the storefront, and you can manage your business primarily from your Shopify dashboard.
-
-For other vendor types, see [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce) or [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual).
diff --git a/docs/user/vendors/vendor-onboarding-woocommerce.mdx b/docs/user/vendors/vendor-onboarding-woocommerce.mdx
deleted file mode 100644
index 57f6e5ace1..0000000000
--- a/docs/user/vendors/vendor-onboarding-woocommerce.mdx
+++ /dev/null
@@ -1,173 +0,0 @@
----
-title: "WooCommerce Vendor Onboarding"
-description: "Learn how to invite and onboard a WooCommerce-based vendor to your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>WooCommerce vendor onboarding is only available in Spree Enterprise Edition.</Warning>
-
-<Note>This guide covers vendors who'll connect their WooCommerce store to your marketplace. For other vendor types, see [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify) and [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual).</Note>
-
-WooCommerce is one of the most widely used ecommerce platforms in the world, so it's worth making it easy for WooCommerce-based vendors to join your marketplace. Once connected, a vendor's products, inventory, orders, and shipping flow automatically between their WooCommerce store and your marketplace — no manual reconciliation required.
-
-Onboarding a WooCommerce vendor has two distinct parts: an **Admin Setup** that the marketplace owner completes by sending an invitation, and a **Vendor Onboarding** flow that the vendor themselves completes after receiving the invite.
-
-## Prerequisites
-
-Before you can onboard WooCommerce vendors, you'll need:
-
-- The **`spree_multi_vendor` Enterprise gem** installed on your Spree instance.
-
----
-
-## Admin Setup
-
-This section is for the marketplace owner. Inviting a WooCommerce vendor uses the same invitation flow as Manual/CSV vendors — the vendor chooses WooCommerce as their connection method during their own onboarding.
-
-### Send the Invitation
-
-To invite a vendor, navigate to **Vendors** in the admin dashboard.
-
-![The Vendors tab listing all vendors invited or onboarded to the marketplace](/docs/images/user/vendors/vendor-onboarding-woocommerce/1-vendors-tab.png)
-
-Click **Invite Vendor** in the top right corner to open the invitation form.
-
-![The Invite Vendor form with fields for company name, contact email, and commission rate](/docs/images/user/vendors/vendor-onboarding-woocommerce/2-invite-vendor.png)
-
-Fill in the following fields:
-
-- **Company Name or Brand Name** - how the vendor will be displayed in the admin dashboard.
-- **Contact Person Email** - the work email address of the person who should receive the invitation.
-- **Commission Rate** - the pre-agreed commission rate to be shared with the marketplace.
-
-<Note>The commission rate can be different for each vendor and updated later from the vendor's profile.</Note>
-
-Double-check the details and click **Send Invitation**. The newly invited vendor will appear in your list of vendors with a pending status.
-
-![The Vendors list showing the newly invited vendor with a pending invitation status](/docs/images/user/vendors/vendor-onboarding-woocommerce/3-invitation-sent.png)
-
-The vendor will receive an email at the specified address with a link to begin onboarding.
-
-### Share the Invitation Link Manually
-
-If the vendor doesn't receive the email, or they prefer a different communication channel, you can copy the invitation link and send it directly.
-
-Click on the vendor in the list to open their vendor profile, navigate to the **Invitations** subtab, click the three-dot menu, and select **Copy invitation link**.
-
-![The Invitations subtab with the three-dot menu opened to show the Copy invitation link option](/docs/images/user/vendors/vendor-onboarding-woocommerce/4-invitation-link.png)
-
-### Cancel an Invitation
-
-If you need to withdraw the invitation — whether the wrong contact was invited, the vendor's details need correcting, or the partnership ended before they began onboarding — navigate to the **Invitations** subtab as above, click the three-dot menu, and select **Delete**.
-
-<Warning>Cancelling an invitation is irreversible. To re-invite the vendor later, you'll need to start the invitation flow from scratch.</Warning>
-
----
-
-## Vendor Onboarding
-
-This section is for the vendor. Once you've received the invitation from the marketplace owner, follow these steps to connect your WooCommerce store and complete your onboarding.
-
-### 1. Accept the Invitation
-
-You'll receive an email invitation from the marketplace owner with a link to get started. Click the link to be directed to your vendor account creation page.
-
-### 2. Create Your Vendor Account
-
-Fill in the sign-up form to create your vendor account, then click **Create Account**.
-
-![The Spree vendor account sign-up form](/docs/images/user/vendors/vendor-onboarding-woocommerce/5-account-signup.png)
-
-You'll then be redirected to your new vendor dashboard, where you'll see a **Getting Started** checklist of onboarding tasks.
-
-![The Getting Started onboarding checklist in the Spree vendor dashboard](/docs/images/user/vendors/vendor-onboarding-woocommerce/6-getting-started-tasks.png)
-
-### 3. Connect Your WooCommerce Store
-
-Click on the **Connect or Create a Shop** task in the checklist, then click **WooCommerce**.
-
-![The Connect or Create a Shop task expanded showing Shopify, WooCommerce, and CSV options](/docs/images/user/vendors/vendor-onboarding-woocommerce/7-connect-shop-options.png)
-
-A popup will appear asking for your WooCommerce store's URL.
-
-![The popup asking for the WooCommerce store URL](/docs/images/user/vendors/vendor-onboarding-woocommerce/8-woocommerce-url.png)
-
-Enter your store URL and click **Continue**. You'll be redirected to a page asking you to approve the marketplace's connection to your store.
-
-![The WooCommerce approval screen asking the vendor to approve marketplace access](/docs/images/user/vendors/vendor-onboarding-woocommerce/9-woocommerce-approve.png)
-
-Click **Approve**. You'll be redirected back to your vendor dashboard, and the task will be marked complete.
-
-A few minutes after connecting, your WooCommerce products will start appearing in your Spree vendor dashboard.
-
-### 4. Complete Your Remaining Onboarding Tasks
-
-With your store connected, you'll still need to complete a few more tasks before you can start selling.
-
-#### Add Billing Address
-
-Your company's billing address is needed for vendor payouts and invoices. Click on the task in your checklist, fill in the form, and click **Save**.
-
-![The Add Billing Address task expanded with the billing form fields](/docs/images/user/vendors/vendor-onboarding-woocommerce/10-billing-address.png)
-
-#### Connect Your Stripe Account
-
-Stripe is used by the marketplace to process payments and send your payouts. To receive your earnings, you'll need to connect a Stripe account.
-
-1. Click on **Connect Stripe Account** in your onboarding checklist.
-2. Click **Connect your bank account** to be guided through Stripe's short onboarding process.
-3. Follow the Stripe prompts to set up a new account or connect an existing one.
-
-![The Connect Stripe Account task expanded in the onboarding checklist](/docs/images/user/vendors/vendor-onboarding-woocommerce/11-connect-stripe.png)
-
-An existing Stripe account isn't required — you can create one as part of this flow. The whole process usually takes around five minutes. Once connected, you'll receive payouts whenever you ship orders.
-
-<Note>If you're not the one handling your company's financials, you can invite another team member to complete this step instead.</Note>
-
-<Warning>Some marketplaces use payment providers other than Stripe. If that's the case, you'll be prompted to connect your bank account through a different flow — your marketplace owner will let you know the specifics.</Warning>
-
-#### Add Returns Address
-
-A returns address ensures customers know where to send returns. Click on the task in your checklist, enter your company's return address, and click **Save**.
-
-![The Add Returns Address task expanded with the address form fields](/docs/images/user/vendors/vendor-onboarding-woocommerce/12-returns-address.png)
-
-#### Set Shipping Rates
-
-Your WooCommerce shipping methods are synced to the marketplace automatically, but rates aren't — you'll need to set them manually.
-
-Click on the **Set Shipping Rates** task, then click **Manage Shipping Rates** to be taken to the **Settings → Shipping** section of your vendor dashboard. Set the rate for each shipping method, then click **Confirm Shipping Rates** in the top right corner.
-
-![The Shipping Methods page in the vendor dashboard with synced WooCommerce methods and rate fields](/docs/images/user/vendors/vendor-onboarding-woocommerce/13-shipping-rates.png)
-
-<Note>You can edit existing shipping methods or add new ones at any time after onboarding is complete.</Note>
-
-#### Add Policies
-
-Clear policies build customer trust, sets clear expectations, and helps prevent disputes over shipping, returns and refunds.
-
-1. Click on **Add Policies** in your onboarding checklist to be redirected to **Settings → Policies**.
-2. Click on the policy you like to update.
-3. Add content to the field in the policy editor.
-4. Click **Save**.
-
-![The Policies tab in the setting menu of the Spree vendor dashboard](/docs/images/user/vendors/vendor-onboarding-woocommerce/14-returns-policy.png)
-
----
-
-## What Syncs Between WooCommerce and the Marketplace
-
-Once your WooCommerce store is connected, the following data syncs automatically:
-
-- **Active products** are imported into the marketplace catalog.
-- **Inventory levels** sync in both directions in real-time.
-- **Shipping methods** sync from WooCommerce to the marketplace — note that **rates do not sync** and must be set manually in your vendor dashboard.
-- **Orders** placed on the marketplace appear in your WooCommerce dashboard for fulfillment, just like normal WooCommerce orders.
-- **Fulfillment status and shipment tracking** sync back to the marketplace and trigger customer notifications automatically.
-- **Price updates** made in WooCommerce sync to the marketplace.
-- **Content updates** (descriptions, images) sync to the marketplace, unless the marketplace owner has edited them.
-
-## Next Steps
-
-Once onboarding is complete, your products will be sent to the marketplace owner for review. Once they're approved, they'll go live on the storefront, and you can manage your business primarily from your WooCommerce dashboard.
-
-For other vendor types, see [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify) or [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual).
diff --git a/docs/user/vendors/vendor-payouts.mdx b/docs/user/vendors/vendor-payouts.mdx
deleted file mode 100644
index ac64834bea..0000000000
--- a/docs/user/vendors/vendor-payouts.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: "Vendor Payouts"
-description: "Learn how to set and override vendor payout schedules across your multi-vendor marketplace in Spree Commerce."
----
-
-<Warning>Multi-vendor capabilities are only available in Spree Enterprise Edition.</Warning>
-
-<Warning>Vendor payout scheduling is a Stripe Connect feature. If your marketplace is configured with a different payment provider, the payout schedule controls described below won't be available in your admin or vendor dashboards.</Warning>
-
-Vendor payouts are how your vendors actually receive the money they've earned from sales on your marketplace. Spree's payout flow runs through Stripe Connect, which means once a vendor has connected their Stripe account during onboarding, they'll be paid automatically on whatever schedule you've configured — no manual transfers, no chasing invoices.
-
-Like with [<u>commission rates</u>](https://spreecommerce.org/docs/user/vendors/commission-rates), one fixed schedule rarely suits every vendor. Some may want frequent payouts to manage cash flow, others may prefer larger, less frequent transfers. Spree lets you set a marketplace-wide default and override it per vendor as needed.
-
-## 1. Default Marketplace Payout Schedule
-
-The default payout schedule applies to every vendor whose schedule is set to **Use marketplace default interval**. It's configured under **Settings → Marketplace** and serves as the fallback for everyone who hasn't opted into a custom schedule.
-
-See [<u>Marketplace Configuration</u>](https://spreecommerce.org/docs/user/settings/marketplace) for details on setting and updating the default schedule.
-
-<Note>Changing the default also updates the payout schedule for any existing vendors who are still on the marketplace default. Vendors who've chosen a specific schedule of their own won't be affected.</Note>
-
-## 2. Vendor-Specific Payout Schedule
-
-You can override the payout schedule for individual vendors directly from their vendor profile — useful when a particular vendor has cash flow needs that differ from the rest of your marketplace.
-
-Navigate to **Vendors** in the admin dashboard and click on the vendor you'd like to update.
-
-![The Vendors tab showing the list of vendors](/docs/images/user/vendors/vendor-payouts/1-vendors-tab.png)
-
-Scroll down to the **Payments & Payouts** section of the vendor profile and choose a payout schedule from the dropdown.
-
-![The Payments & Payouts section of the vendor profile with the payout schedule dropdown](/docs/images/user/vendors/vendor-payouts/2-payments-payouts.png)
-
-The available options are:
-
-- **Use marketplace default interval** - the vendor follows whatever default is configured under Settings → Marketplace.
-- **Daily** - payouts are issued every business day.
-- **Weekly** - payouts are issued once per week.
-- **Bi-weekly** - payouts are issued every two weeks.
-- **Monthly** - payouts are issued once per month.
-
-Click **Update** at the bottom of the page to save your changes.
-
-<Note>If you set a vendor to a specific schedule (anything other than **Use marketplace default interval**), future changes to the marketplace default will no longer affect them. To bring them back in line, set them back to **Use marketplace default interval**.</Note>
-
-## Which Schedule Applies?
-
-When a payout is processed, Spree applies the most specific schedule available, in the following order:
-
-1. **Vendor-specific schedule** — if set to a specific interval, this wins.
-2. **Marketplace default schedule** — used whenever a vendor is set to **Use marketplace default interval**.
-
-## Next Steps
-
-For more on how vendors connect their Stripe accounts during onboarding (which is what makes automated payouts possible), see the relevant onboarding doc:
-
-- [<u>Shopify Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify)
-- [<u>WooCommerce Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce)
-- [<u>Manual/CSV Vendor Onboarding</u>](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual)
diff --git a/packages/dashboard-core/src/components/page-header.tsx b/packages/dashboard-core/src/components/page-header.tsx
index 876d1d15e7..ef5fcd1ad9 100644
--- a/packages/dashboard-core/src/components/page-header.tsx
+++ b/packages/dashboard-core/src/components/page-header.tsx
@@ -254,12 +254,12 @@ export function PageHeader({
)}
</div>
)}
- {description && (
+ {(description || docsPath) && (
<p className="text-muted-foreground text-sm">
{description}
{docsPath && (
<>
- {' '}
+ {description ? ' ' : null}
<ExternalLink href={docsUrl(docsPath)}>
{t('admin.common.learn_more')}
</ExternalLink>
diff --git a/packages/dashboard-core/src/components/section-heading.tsx b/packages/dashboard-core/src/components/section-heading.tsx
index 4a2d733c3a..9d2842c605 100644
--- a/packages/dashboard-core/src/components/section-heading.tsx
+++ b/packages/dashboard-core/src/components/section-heading.tsx
@@ -48,12 +48,12 @@ export function SectionHeading({
) : (
<CardTitle className="min-w-0 truncate text-lg">{title}</CardTitle>
)}
- {description && (
+ {(description || docsPath) && (
<p className="text-muted-foreground text-sm">
{description}
{docsPath && (
<>
- {' '}
+ {description ? ' ' : null}
<ExternalLink href={docsUrl(docsPath)} className="text-sm">
{t('admin.common.learn_more')}
</ExternalLink>
diff --git a/packages/dashboard-core/src/locales/ar.json b/packages/dashboard-core/src/locales/ar.json
index 566405bad4..efd65c5dd2 100644
--- a/packages/dashboard-core/src/locales/ar.json
+++ b/packages/dashboard-core/src/locales/ar.json
@@ -1062,7 +1062,8 @@
},
"validation": {
"non_negative": "يجب أن يكون صفرًا أو أكثر"
- }
+ },
+ "description": "الصناديق والكراتين والمنصات التي تُشحن فيها بضائعك، مع الأبعاد والأوزان التي يعتمد عليها الناقلون في التسعير."
},
"pages": {
"settings": {
@@ -1403,7 +1404,8 @@
"unknown_product": "منتج غير معروف",
"variant_count_one": "{{count}} متغير",
"variant_count_other": "{{count}} متغيرات"
- }
+ },
+ "description": "المستودعات والمتاجر التي تحتفظ فيها بالمخزون وتنفذ الطلبات منها."
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/locales/de.json b/packages/dashboard-core/src/locales/de.json
index 2c53c581ae..35aa093644 100644
--- a/packages/dashboard-core/src/locales/de.json
+++ b/packages/dashboard-core/src/locales/de.json
@@ -1062,7 +1062,8 @@
},
"validation": {
"non_negative": "muss null oder größer sein"
- }
+ },
+ "description": "Die Kartons, Umkartons und Paletten, in denen Ihre Ware versendet wird, mit den Maßen und Gewichten, auf denen Frachtangebote beruhen."
},
"pages": {
"settings": {
@@ -1403,7 +1404,8 @@
"unknown_product": "Unbekanntes Produkt",
"variant_count_one": "{{count}} Variante",
"variant_count_other": "{{count}} Varianten"
- }
+ },
+ "description": "Die Lager und Läden, in denen Sie Bestand halten und aus denen Sie Bestellungen erfüllen."
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/locales/en.json b/packages/dashboard-core/src/locales/en.json
index 9d84ac13d4..d7898d4b5b 100644
--- a/packages/dashboard-core/src/locales/en.json
+++ b/packages/dashboard-core/src/locales/en.json
@@ -1064,7 +1064,8 @@
},
"validation": {
"non_negative": "must be zero or more"
- }
+ },
+ "description": "The boxes, cartons and pallets your goods ship in, with the sizes and weights carriers quote on."
},
"pages": {
"settings": {
@@ -1405,7 +1406,8 @@
"unknown_product": "Unknown product",
"variant_count_one": "{{count}} variant",
"variant_count_other": "{{count}} variants"
- }
+ },
+ "description": "The warehouses and shops you hold stock in and fulfil orders from."
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/locales/fr.json b/packages/dashboard-core/src/locales/fr.json
index 981bb81e33..126b98f936 100644
--- a/packages/dashboard-core/src/locales/fr.json
+++ b/packages/dashboard-core/src/locales/fr.json
@@ -1062,7 +1062,8 @@
},
"validation": {
"non_negative": "doit être supérieur ou égal à zéro"
- }
+ },
+ "description": "Les boîtes, cartons et palettes dans lesquels vos marchandises sont expédiées, avec les dimensions et poids sur lesquels les transporteurs établissent leurs tarifs."
},
"pages": {
"settings": {
@@ -1403,7 +1404,8 @@
"unknown_product": "Produit inconnu",
"variant_count_one": "{{count}} variante",
"variant_count_other": "{{count}} variantes"
- }
+ },
+ "description": "Les entrepôts et boutiques où vous détenez du stock et depuis lesquels vous expédiez les commandes."
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/locales/pl.json b/packages/dashboard-core/src/locales/pl.json
index 7c280947ba..85909842aa 100644
--- a/packages/dashboard-core/src/locales/pl.json
+++ b/packages/dashboard-core/src/locales/pl.json
@@ -1063,7 +1063,8 @@
},
"validation": {
"non_negative": "musi wynosić zero lub więcej"
- }
+ },
+ "description": "Pudełka, kartony i palety, w których wysyłasz towary, z wymiarami i wagami, na podstawie których przewoźnicy wyceniają przesyłki."
},
"pages": {
"settings": {
@@ -1420,7 +1421,8 @@
"unknown_product": "Nieznany produkt",
"variant_count_one": "{{count}} wariant",
"variant_count_other": "{{count}} wariantów"
- }
+ },
+ "description": "Magazyny i sklepy, w których trzymasz towar i z których realizujesz zamówienia."
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/locales/zh-CN.json b/packages/dashboard-core/src/locales/zh-CN.json
index ddc56313cf..3323e69b59 100644
--- a/packages/dashboard-core/src/locales/zh-CN.json
+++ b/packages/dashboard-core/src/locales/zh-CN.json
@@ -1062,7 +1062,8 @@
},
"validation": {
"non_negative": "必须大于或等于零"
- }
+ },
+ "description": "您的货物用于发运的箱子、纸箱和托盘,以及承运商报价所依据的尺寸和重量。"
},
"pages": {
"settings": {
@@ -1403,7 +1404,8 @@
"unknown_product": "未知产品",
"variant_count_one": "{{count}} 个变体",
"variant_count_other": "{{count}} 个变体"
- }
+ },
+ "description": "您存放库存并从中履行订单的仓库和门店。"
},
"validation": {
"codes": {
diff --git a/packages/dashboard-core/src/tables/package-types.tsx b/packages/dashboard-core/src/tables/package-types.tsx
index eddeb4f7b6..e0b3426200 100644
--- a/packages/dashboard-core/src/tables/package-types.tsx
+++ b/packages/dashboard-core/src/tables/package-types.tsx
@@ -5,6 +5,8 @@ import type { PanelPackageType } from '../api-client'
import { defineTable } from '../lib/table-registry'
defineTable<PanelPackageType>('package-types', {
+ docsPath: 'settings/package-types',
+ description: i18n.t('admin.package_types.description'),
title: i18n.t('admin.package_types.table_title'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.package_types.search_placeholder'),
diff --git a/packages/dashboard-core/src/tables/stock-locations.tsx b/packages/dashboard-core/src/tables/stock-locations.tsx
index 6334e8a6a1..c2911bf7fb 100644
--- a/packages/dashboard-core/src/tables/stock-locations.tsx
+++ b/packages/dashboard-core/src/tables/stock-locations.tsx
@@ -5,6 +5,8 @@ import type { PanelStockLocation } from '../api-client'
import { defineTable } from '../lib/table-registry'
defineTable<PanelStockLocation>('stock-locations', {
+ docsPath: 'settings/locations',
+ description: i18n.t('admin.stock_locations.description'),
title: i18n.t('admin.settings_nav.items.stock_locations'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.stock_locations.search_placeholder'),
diff --git a/packages/dashboard-starter/src/routeTree.gen.ts b/packages/dashboard-starter/src/routeTree.gen.ts
index 6b25338546..75dc09cb0c 100644
--- a/packages/dashboard-starter/src/routeTree.gen.ts
+++ b/packages/dashboard-starter/src/routeTree.gen.ts
@@ -60,6 +60,7 @@ import { Route as SettingsChannelsRouteImport } from './../../dashboard/src/rout
import { Route as SettingsApiKeysRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/api-keys'
import { Route as SettingsAllowedOriginsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/allowed-origins'
import { Route as SellersTransfersRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/sellers/transfers'
+import { Route as SellersCommissionRatesRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/sellers/commission-rates'
import { Route as SellersSellerIdRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/sellers/$sellerId'
import { Route as ReportsNewRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/reports/new'
import { Route as ReportsReportIdRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/reports/$reportId'
@@ -364,6 +365,11 @@ const SellersTransfersRoute = SellersTransfersRouteImport.update({
path: '/sellers/transfers',
getParentRoute: () => authenticatedStoreIdRoute,
} as any)
+const SellersCommissionRatesRoute = SellersCommissionRatesRouteImport.update({
+ id: '/sellers/commission-rates',
+ path: '/sellers/commission-rates',
+ getParentRoute: () => authenticatedStoreIdRoute,
+} as any)
const SellersSellerIdRoute = SellersSellerIdRouteImport.update({
id: '/sellers/$sellerId',
path: '/sellers/$sellerId',
@@ -644,6 +650,7 @@ export interface FileRoutesByFullPath {
'/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/$storeId/reports/new': typeof ReportsNewRoute
'/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -740,6 +747,7 @@ export interface FileRoutesByTo {
'/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/$storeId/reports/new': typeof ReportsNewRoute
'/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -840,6 +848,7 @@ export interface FileRoutesById {
'/_authenticated/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/_authenticated/$storeId/reports/new': typeof ReportsNewRoute
'/_authenticated/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/_authenticated/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/_authenticated/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/_authenticated/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/_authenticated/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -940,6 +949,7 @@ export interface FileRouteTypes {
| '/$storeId/reports/$reportId'
| '/$storeId/reports/new'
| '/$storeId/sellers/$sellerId'
+ | '/$storeId/sellers/commission-rates'
| '/$storeId/sellers/transfers'
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
@@ -1036,6 +1046,7 @@ export interface FileRouteTypes {
| '/$storeId/reports/$reportId'
| '/$storeId/reports/new'
| '/$storeId/sellers/$sellerId'
+ | '/$storeId/sellers/commission-rates'
| '/$storeId/sellers/transfers'
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
@@ -1135,6 +1146,7 @@ export interface FileRouteTypes {
| '/_authenticated/$storeId/reports/$reportId'
| '/_authenticated/$storeId/reports/new'
| '/_authenticated/$storeId/sellers/$sellerId'
+ | '/_authenticated/$storeId/sellers/commission-rates'
| '/_authenticated/$storeId/sellers/transfers'
| '/_authenticated/$storeId/settings/allowed-origins'
| '/_authenticated/$storeId/settings/api-keys'
@@ -1566,6 +1578,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SellersTransfersRouteImport
parentRoute: typeof authenticatedStoreIdRoute
}
+ '/_authenticated/$storeId/sellers/commission-rates': {
+ id: '/_authenticated/$storeId/sellers/commission-rates'
+ path: '/sellers/commission-rates'
+ fullPath: '/$storeId/sellers/commission-rates'
+ preLoaderRoute: typeof SellersCommissionRatesRouteImport
+ parentRoute: typeof authenticatedStoreIdRoute
+ }
'/_authenticated/$storeId/sellers/$sellerId': {
id: '/_authenticated/$storeId/sellers/$sellerId'
path: '/sellers/$sellerId'
@@ -1992,6 +2011,7 @@ interface authenticatedStoreIdRouteChildren {
ReportsReportIdRoute: typeof ReportsReportIdRoute
ReportsNewRoute: typeof ReportsNewRoute
SellersSellerIdRoute: typeof SellersSellerIdRoute
+ SellersCommissionRatesRoute: typeof SellersCommissionRatesRoute
SellersTransfersRoute: typeof SellersTransfersRoute
TransfersNewRoute: typeof TransfersNewRoute
BrandsDotindexRoute: typeof BrandsDotindexRoute
@@ -2055,6 +2075,7 @@ const authenticatedStoreIdRouteChildren: authenticatedStoreIdRouteChildren = {
ReportsReportIdRoute: ReportsReportIdRoute,
ReportsNewRoute: ReportsNewRoute,
SellersSellerIdRoute: SellersSellerIdRoute,
+ SellersCommissionRatesRoute: SellersCommissionRatesRoute,
SellersTransfersRoute: SellersTransfersRoute,
TransfersNewRoute: TransfersNewRoute,
BrandsDotindexRoute: BrandsDotindexRoute,
diff --git a/packages/dashboard-ui/src/ui/badge.tsx b/packages/dashboard-ui/src/ui/badge.tsx
index 6259e9696a..30bb752054 100644
--- a/packages/dashboard-ui/src/ui/badge.tsx
+++ b/packages/dashboard-ui/src/ui/badge.tsx
@@ -122,6 +122,13 @@ const statusToneMap: Record<string, StatusTone> = {
archived: 'neutral',
returned: 'success',
backorder: 'warning',
+ // Order payment status: amber while money is still owed either way, blue
+ // for a hold or a part refund, red once the authorisation is gone.
+ none: 'neutral',
+ partially_paid: 'warning',
+ partially_refunded: 'info',
+ overcharged: 'warning',
+ voided: 'destructive',
balance_due: 'warning',
credit_owed: 'warning',
canceled: 'destructive',
diff --git a/packages/dashboard/src/components/spree/sellers/seller-onboarding-card.tsx b/packages/dashboard/src/components/spree/sellers/seller-onboarding-card.tsx
index bcaf28f60e..1b3e5f5154 100644
--- a/packages/dashboard/src/components/spree/sellers/seller-onboarding-card.tsx
+++ b/packages/dashboard/src/components/spree/sellers/seller-onboarding-card.tsx
@@ -31,6 +31,7 @@ import {
FileTextIcon,
XCircleIcon,
} from '@spree/dashboard-ui/icons'
+import { Link } from '@tanstack/react-router'
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import {
@@ -97,6 +98,13 @@ export function SellerOnboardingCard({ seller, canEdit }: { seller: Seller; canE
<p className="text-muted-foreground text-sm">{t('admin.common.loading')}</p>
)}
</div>
+ {canEdit && (
+ <div className="border-t px-4 pb-4 pt-3 text-sm">
+ <Link to={'/$storeId/settings/seller-requirements' as string}>
+ {t('admin.sellers.onboarding.manage_requirements')}
+ </Link>
+ </div>
+ )}
</CollapsibleContent>
</Collapsible>
</Card>
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index 66768d5a10..bc7b5410d0 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -2609,7 +2609,8 @@
"inventory": "المخزون",
"suppliers": "الموردون",
"loyalty": "الولاء",
- "store_credits": "أرصدة المتجر"
+ "store_credits": "أرصدة المتجر",
+ "commission_rates": "نسب العمولة"
},
"option_types": {
"columns": {
@@ -3033,11 +3034,18 @@
"use_default_addresses": "استخدم عناوين الفواتير والشحن الافتراضية لـ العميل"
},
"payment_statuses": {
+ "none": "غير مدفوع",
+ "authorized": "مُصرَّح به",
+ "partially_paid": "مدفوع جزئيًا",
+ "paid": "مدفوع",
+ "partially_refunded": "مسترد جزئيًا",
+ "refunded": "مسترد",
+ "overcharged": "مدفوع بالزيادة",
+ "voided": "ملغى",
"balance_due": "الرصيد المستحق",
"credit_owed": "الائتمان المستحق",
"failed": "فشل",
- "paid": "مدفوع",
- "void": "Void"
+ "void": "ملغى"
},
"statuses": {
"canceled": "تم الإلغاء",
@@ -4891,6 +4899,7 @@
},
"all_done": "اكتمل كل شيء 🎉",
"download": "تنزيل الملف",
+ "manage_requirements": "إدارة المتطلبات",
"policy_empty": "لا يوجد محتوى لهذه السياسة بعد.",
"policy_updated": "آخر تحديث في {{date}}",
"progress": "اكتمل {{done}} من {{total}}",
@@ -5381,7 +5390,31 @@
"stock_transfers": "المخزون المنقول بين مواقعك، وما وصل منه.",
"purchase_orders": "المخزون الذي طلبته من الموردين، وما وصل منه",
"suppliers": "دفتر عناوين الموردين",
- "stock_levels": "ما لديك في كل موقع: المتوفر، والمخصص للطلبات، والمحجوز من عمليات الدفع، والمتاح للبيع، والوارد."
+ "stock_levels": "ما لديك في كل موقع: المتوفر، والمخصص للطلبات، والمحجوز من عمليات الدفع، والمتاح للبيع، والوارد.",
+ "allowed_origins": "عناوين الويب المسموح لها باستدعاء واجهة برمجة تطبيقات متجرك من المتصفح.",
+ "channels": "أين تبيع — كل واجهة متجر أو تطبيق أو بوابة، بكتالوجها وإعداداتها الافتراضية الخاصة.",
+ "commission_rates": "ما يتقاضاه السوق على كل عملية بيع، ويُطبَّق بترتيب القائمة.",
+ "custom_field_definitions": "حقول إضافية تُلحقها بالمنتجات والطلبات والعملاء والسجلات الأخرى.",
+ "customers": "كل من اشترى من متجرك أو سجّل فيه.",
+ "gift_cards": "بطاقات مدفوعة مسبقًا يستخدمها العملاء عند الدفع.",
+ "imports": "ملفات CSV التي رفعتها ونتيجة معالجة كل منها.",
+ "markets": "المناطق التي تبيع فيها، لكل منها عملتها وضرائبها وإعدادات التوصيل الخاصة بها.",
+ "orders": "كل طلب تم تقديمه في متجرك وحالته الحالية.",
+ "draft_orders": "طلبات يُعدّها فريقك نيابةً عن عميل ولم تُقدَّم بعد.",
+ "payment_methods": "كيف يمكن للعملاء الدفع، ومزودو الخدمة وراء كل خيار.",
+ "policies": "شروطك وسياسات الخصوصية والإرجاع والشحن، المنشورة في واجهة المتجر.",
+ "products": "كل ما تبيعه، مع متغيراته وأسعاره ومخزونه.",
+ "promotions": "الخصومات والعروض، والقواعد التي تحدد متى تنطبق.",
+ "seller_requirements": "قائمة التحقق التي يكملها البائعون قبل أن تتم الموافقة عليهم.",
+ "sellers": "البائعون الخارجيون الذين يتاجرون في سوقك، وحالة كل منهم.",
+ "store_credits": "أرصدة يمكن للعملاء إنفاقها عند الدفع، وكيف تم إصدار كل منها.",
+ "tax_categories": "تجميعات تحدد معدل الضريبة الذي ينطبق على المنتج.",
+ "tax_rates": "الضريبة المفروضة حسب الفئة والمنطقة.",
+ "webhook_deliveries": "كل حدث أُرسل إلى نقطة النهاية هذه، وما إذا تم استلامه.",
+ "webhook_endpoints": "أين يتم إخطار أنظمتك الأخرى عندما يحدث شيء في المتجر.",
+ "returns": "البضائع العائدة، من الطلب حتى استرداد المبلغ.",
+ "exchanges": "مشتريات تم استبدالها بمقاس أو لون أو منتج مختلف.",
+ "claims": "عمليات تسليم تعثّرت — عناصر تالفة أو مفقودة أو خاطئة — وكيف تم حل كل منها."
},
"tax_categories": {
"add_cta": "إضافة فئة الضريبة",
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 8ca6d77ae5..869d296d60 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -2591,7 +2591,8 @@
"inventory": "Lagerbestand",
"suppliers": "Lieferanten",
"loyalty": "Treue",
- "store_credits": "Guthaben"
+ "store_credits": "Guthaben",
+ "commission_rates": "Provisionssätze"
},
"option_types": {
"columns": {
@@ -3016,10 +3017,17 @@
"use_default_addresses": "Standard-Rechnungs- und Lieferadresse des Kunden verwenden"
},
"payment_statuses": {
+ "none": "Unbezahlt",
+ "authorized": "Autorisiert",
+ "partially_paid": "Teilweise bezahlt",
+ "paid": "Bezahlt",
+ "partially_refunded": "Teilweise erstattet",
+ "refunded": "Erstattet",
+ "overcharged": "Überzahlt",
+ "voided": "Storniert",
"balance_due": "Offener Betrag",
"credit_owed": "Guthaben",
"failed": "Fehlgeschlagen",
- "paid": "Bezahlt",
"void": "Storniert"
},
"statuses": {
@@ -4861,6 +4869,7 @@
},
"all_done": "Alles erledigt 🎉",
"download": "Datei herunterladen",
+ "manage_requirements": "Anforderungen verwalten",
"policy_empty": "Diese Richtlinie hat noch keinen Inhalt.",
"policy_updated": "Zuletzt aktualisiert am {{date}}",
"progress": "{{done}} von {{total}} erledigt",
@@ -5347,7 +5356,31 @@
"stock_transfers": "Bestand, der zwischen Ihren Lagern bewegt wird, und was angekommen ist.",
"purchase_orders": "Ware, die Sie bei Lieferanten bestellt haben, und was eingetroffen ist",
"suppliers": "Ihr Lieferanten-Adressbuch",
- "stock_levels": "Was Sie an jedem Lagerort haben: vorrätig, Bestellungen zugewiesen, durch Kassen gehalten, verkäuflich und unterwegs."
+ "stock_levels": "Was Sie an jedem Lagerort haben: vorrätig, Bestellungen zugewiesen, durch Kassen gehalten, verkäuflich und unterwegs.",
+ "allowed_origins": "Die Webadressen, die die API Ihres Shops aus dem Browser aufrufen dürfen.",
+ "channels": "Wo Sie verkaufen — jeder Storefront, jede App und jedes Portal mit eigenem Katalog und eigenen Vorgaben.",
+ "commission_rates": "Was der Marktplatz bei jedem Verkauf berechnet, in Listenreihenfolge angewendet.",
+ "custom_field_definitions": "Zusätzliche Felder, die Sie an Produkte, Bestellungen, Kunden und andere Datensätze anhängen.",
+ "customers": "Alle, die in Ihrem Shop gekauft oder sich registriert haben.",
+ "gift_cards": "Vorausbezahlte Karten, die Kunden an der Kasse einlösen.",
+ "imports": "Hochgeladene CSV-Dateien und wie jede verarbeitet wurde.",
+ "markets": "Die Regionen, in die Sie verkaufen, jeweils mit eigener Währung, Steuer und Lieferung.",
+ "orders": "Jede Bestellung in Ihrem Shop und ihr aktueller Stand.",
+ "draft_orders": "Bestellungen, die Ihr Team im Namen eines Kunden anlegt und die noch nicht aufgegeben sind.",
+ "payment_methods": "Wie Kunden bezahlen können und welche Anbieter dahinterstehen.",
+ "policies": "Ihre AGB sowie Datenschutz-, Rückgabe- und Versandrichtlinien, veröffentlicht im Storefront.",
+ "products": "Alles, was Sie verkaufen, mit Varianten, Preisen und Bestand.",
+ "promotions": "Rabatte und Angebote und die Regeln, die entscheiden, wann sie gelten.",
+ "seller_requirements": "Die Checkliste, die Verkäufer abschließen, bevor sie freigegeben werden können.",
+ "sellers": "Die Drittanbieter auf Ihrem Marktplatz und der Stand jedes einzelnen.",
+ "store_credits": "Guthaben, das Kunden an der Kasse ausgeben können, und wie es ausgestellt wurde.",
+ "tax_categories": "Gruppen, die entscheiden, welcher Steuersatz für ein Produkt gilt.",
+ "tax_rates": "Die je Kategorie und Region berechnete Steuer.",
+ "webhook_deliveries": "Jedes an diesen Endpunkt gesendete Ereignis und ob es empfangen wurde.",
+ "webhook_endpoints": "Wohin Ihre anderen Systeme benachrichtigt werden, wenn im Shop etwas passiert.",
+ "returns": "Zurückkommende Ware, von der Anfrage bis zur Erstattung.",
+ "exchanges": "Käufe, die gegen eine andere Größe, Farbe oder ein anderes Produkt getauscht werden.",
+ "claims": "Fehlgeschlagene Lieferungen — beschädigte, fehlende oder falsche Artikel — und wie sie gelöst wurden."
},
"tax_categories": {
"add_cta": "Steuerkategorie hinzufügen",
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index e5c203a140..5c6dd34e25 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -2591,7 +2591,8 @@
"inventory": "Inventory",
"suppliers": "Suppliers",
"loyalty": "Loyalty",
- "store_credits": "Store Credits"
+ "store_credits": "Store Credits",
+ "commission_rates": "Commission rates"
},
"option_types": {
"columns": {
@@ -3016,10 +3017,17 @@
"use_default_addresses": "Use customer's default billing & shipping addresses"
},
"payment_statuses": {
+ "none": "Unpaid",
+ "authorized": "Authorized",
+ "partially_paid": "Partially paid",
+ "paid": "Paid",
+ "partially_refunded": "Partially refunded",
+ "refunded": "Refunded",
+ "overcharged": "Overcharged",
+ "voided": "Voided",
"balance_due": "Balance due",
"credit_owed": "Credit owed",
"failed": "Failed",
- "paid": "Paid",
"void": "Void"
},
"statuses": {
@@ -4861,6 +4869,7 @@
},
"all_done": "All done 🎉",
"download": "Download file",
+ "manage_requirements": "Manage requirements",
"policy_empty": "This policy has no content yet.",
"policy_updated": "Last updated {{date}}",
"progress": "{{done}} of {{total}} done",
@@ -5347,7 +5356,31 @@
"stock_transfers": "Stock moving between your locations, and what has arrived.",
"purchase_orders": "Stock you have ordered from suppliers, and what has arrived",
"suppliers": "Your supplier address book",
- "stock_levels": "What you have at each location: on hand, allocated to orders, held by checkouts, available to sell, and on its way."
+ "stock_levels": "What you have at each location: on hand, allocated to orders, held by checkouts, available to sell, and on its way.",
+ "allowed_origins": "The web addresses allowed to call your store's API from a browser.",
+ "channels": "Where you sell — each storefront, app or portal, with its own catalog and defaults.",
+ "commission_rates": "What the marketplace charges on each sale, applied in list order.",
+ "custom_field_definitions": "Extra fields you attach to products, orders, customers and other records.",
+ "customers": "Everyone who has shopped with or registered at your store.",
+ "gift_cards": "Prepaid cards customers redeem at checkout.",
+ "imports": "CSV files you have uploaded, and how each one went.",
+ "markets": "The regions you sell to, each with its own currency, tax and delivery setup.",
+ "orders": "Every order placed with your store, and where each one stands.",
+ "draft_orders": "Orders your team is building on a customer's behalf, not yet placed.",
+ "payment_methods": "How customers can pay, and the providers behind each option.",
+ "policies": "Your terms, privacy, returns and shipping policies, published on the storefront.",
+ "products": "Everything you sell, with its variants, prices and stock.",
+ "promotions": "Discounts and offers, and the rules that decide when they apply.",
+ "seller_requirements": "The checklist sellers complete before they can be approved.",
+ "sellers": "The third-party sellers trading on your marketplace, and where each one stands.",
+ "store_credits": "Balances customers can spend at checkout, and how each was issued.",
+ "tax_categories": "Groupings that decide which tax rate a product gets.",
+ "tax_rates": "The tax charged per category and region.",
+ "webhook_deliveries": "Each event sent to this endpoint, and whether it was received.",
+ "webhook_endpoints": "Where your other systems are notified when something happens in the store.",
+ "returns": "Goods coming back, from request to refund.",
+ "exchanges": "Purchases swapped for a different size, colour or product.",
+ "claims": "Deliveries that went wrong — damaged, missing or wrong items — and how each was resolved."
},
"tax_categories": {
"add_cta": "Add tax category",
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index 6e47363bb7..abea386e7b 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -2591,7 +2591,8 @@
"inventory": "Inventaire",
"suppliers": "Fournisseurs",
"loyalty": "Fidélité",
- "store_credits": "Avoirs"
+ "store_credits": "Avoirs",
+ "commission_rates": "Taux de commission"
},
"option_types": {
"columns": {
@@ -3016,10 +3017,17 @@
"use_default_addresses": "Utiliser les adresses de facturation et de livraison par défaut du client"
},
"payment_statuses": {
+ "none": "Non payée",
+ "authorized": "Autorisée",
+ "partially_paid": "Partiellement payée",
+ "paid": "Payée",
+ "partially_refunded": "Partiellement remboursée",
+ "refunded": "Remboursée",
+ "overcharged": "Trop-perçu",
+ "voided": "Annulée",
"balance_due": "Solde dû",
"credit_owed": "Crédit dû",
"failed": "Échouée",
- "paid": "Payée",
"void": "Annulée"
},
"statuses": {
@@ -4861,6 +4869,7 @@
},
"all_done": "Tout est fait 🎉",
"download": "Télécharger le fichier",
+ "manage_requirements": "Gérer les exigences",
"policy_empty": "Cette politique n'a pas encore de contenu.",
"policy_updated": "Dernière mise à jour le {{date}}",
"progress": "{{done}} sur {{total}} terminé",
@@ -5347,7 +5356,31 @@
"stock_transfers": "Le stock qui circule entre vos entrepôts, et ce qui est arrivé.",
"purchase_orders": "Le stock commandé à vos fournisseurs, et ce qui est arrivé",
"suppliers": "Votre carnet d'adresses fournisseurs",
- "stock_levels": "Ce que vous avez à chaque emplacement : en stock, alloué à des commandes, retenu par des paiements en cours, disponible à la vente et en route."
+ "stock_levels": "Ce que vous avez à chaque emplacement : en stock, alloué à des commandes, retenu par des paiements en cours, disponible à la vente et en route.",
+ "allowed_origins": "Les adresses web autorisées à appeler l'API de votre boutique depuis un navigateur.",
+ "channels": "Où vous vendez — chaque vitrine, application ou portail, avec son propre catalogue et ses valeurs par défaut.",
+ "commission_rates": "Ce que la place de marché prélève sur chaque vente, appliqué dans l'ordre de la liste.",
+ "custom_field_definitions": "Champs supplémentaires que vous attachez aux produits, commandes, clients et autres enregistrements.",
+ "customers": "Toutes les personnes ayant acheté ou créé un compte sur votre boutique.",
+ "gift_cards": "Cartes prépayées que les clients utilisent au paiement.",
+ "imports": "Les fichiers CSV que vous avez importés, et le résultat de chacun.",
+ "markets": "Les régions où vous vendez, chacune avec sa devise, ses taxes et sa livraison.",
+ "orders": "Chaque commande passée sur votre boutique, et où elle en est.",
+ "draft_orders": "Commandes que votre équipe prépare au nom d'un client, pas encore passées.",
+ "payment_methods": "Comment les clients peuvent payer, et les prestataires derrière chaque option.",
+ "policies": "Vos conditions générales et politiques de confidentialité, de retour et de livraison, publiées sur la vitrine.",
+ "products": "Tout ce que vous vendez, avec ses variantes, ses prix et son stock.",
+ "promotions": "Remises et offres, et les règles qui décident quand elles s'appliquent.",
+ "seller_requirements": "La liste de contrôle que les vendeurs complètent avant de pouvoir être approuvés.",
+ "sellers": "Les vendeurs tiers actifs sur votre place de marché, et où en est chacun.",
+ "store_credits": "Avoirs que les clients peuvent dépenser au paiement, et comment chacun a été émis.",
+ "tax_categories": "Regroupements qui décident du taux de taxe appliqué à un produit.",
+ "tax_rates": "La taxe facturée par catégorie et par région.",
+ "webhook_deliveries": "Chaque événement envoyé à ce point de terminaison, et s'il a été reçu.",
+ "webhook_endpoints": "Où vos autres systèmes sont notifiés quand quelque chose se produit dans la boutique.",
+ "returns": "Marchandises qui reviennent, de la demande au remboursement.",
+ "exchanges": "Achats échangés contre une autre taille, une autre couleur ou un autre produit.",
+ "claims": "Livraisons qui ont mal tourné — articles endommagés, manquants ou erronés — et comment chacune a été résolue."
},
"tax_categories": {
"add_cta": "Ajouter une catégorie de taxe",
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index fd95bf9ff5..d10c798930 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -2613,7 +2613,8 @@
"inventory": "Magazyn",
"suppliers": "Dostawcy",
"loyalty": "Lojalność",
- "store_credits": "Środki w sklepie"
+ "store_credits": "Środki w sklepie",
+ "commission_rates": "Stawki prowizji"
},
"option_types": {
"columns": {
@@ -3048,10 +3049,17 @@
"use_default_addresses": "Użyj domyślnych adresów rozliczeniowego i wysyłki klienta"
},
"payment_statuses": {
+ "none": "Nieopłacone",
+ "authorized": "Autoryzowane",
+ "partially_paid": "Częściowo opłacone",
+ "paid": "Opłacone",
+ "partially_refunded": "Częściowo zwrócone",
+ "refunded": "Zwrócone",
+ "overcharged": "Nadpłata",
+ "voided": "Unieważnione",
"balance_due": "Należność",
"credit_owed": "Nadpłata",
"failed": "Nieudana",
- "paid": "Opłacone",
"void": "Unieważnione"
},
"statuses": {
@@ -4923,6 +4931,7 @@
},
"all_done": "Wszystko gotowe 🎉",
"download": "Pobierz plik",
+ "manage_requirements": "Zarządzaj wymaganiami",
"policy_empty": "Ta polityka nie ma jeszcze treści.",
"policy_updated": "Ostatnia aktualizacja: {{date}}",
"progress": "Ukończono {{done}} z {{total}}",
@@ -5411,7 +5420,31 @@
"stock_transfers": "Zapasy przemieszczane między lokalizacjami i to, co już dotarło.",
"purchase_orders": "Towar zamówiony u dostawców i to, co już dotarło",
"suppliers": "Twoja książka adresowa dostawców",
- "stock_levels": "Co masz w każdej lokalizacji: na stanie, przydzielone do zamówień, wstrzymane przez koszyki, dostępne do sprzedaży i w drodze."
+ "stock_levels": "Co masz w każdej lokalizacji: na stanie, przydzielone do zamówień, wstrzymane przez koszyki, dostępne do sprzedaży i w drodze.",
+ "allowed_origins": "Adresy internetowe, które mogą wywoływać API Twojego sklepu z przeglądarki.",
+ "channels": "Gdzie sprzedajesz — każdy sklep internetowy, aplikacja lub portal z własnym katalogiem i ustawieniami domyślnymi.",
+ "commission_rates": "Ile marketplace pobiera od każdej sprzedaży, stosowane w kolejności listy.",
+ "custom_field_definitions": "Dodatkowe pola dołączane do produktów, zamówień, klientów i innych rekordów.",
+ "customers": "Wszyscy, którzy kupili w Twoim sklepie lub założyli w nim konto.",
+ "gift_cards": "Przedpłacone karty, które klienci realizują przy kasie.",
+ "imports": "Przesłane pliki CSV i wynik przetwarzania każdego z nich.",
+ "markets": "Regiony, do których sprzedajesz, każdy z własną walutą, podatkami i dostawą.",
+ "orders": "Każde zamówienie złożone w Twoim sklepie i jego aktualny stan.",
+ "draft_orders": "Zamówienia, które Twój zespół tworzy w imieniu klienta, jeszcze niezłożone.",
+ "payment_methods": "Jak klienci mogą płacić i którzy dostawcy stoją za każdą opcją.",
+ "policies": "Twój regulamin oraz polityki prywatności, zwrotów i wysyłki, publikowane w sklepie.",
+ "products": "Wszystko, co sprzedajesz, wraz z wariantami, cenami i stanami magazynowymi.",
+ "promotions": "Rabaty i oferty oraz reguły decydujące o tym, kiedy obowiązują.",
+ "seller_requirements": "Lista kontrolna, którą sprzedawcy wypełniają, zanim będzie można ich zatwierdzić.",
+ "sellers": "Sprzedawcy zewnętrzni działający na Twoim marketplace i status każdego z nich.",
+ "store_credits": "Środki, które klienci mogą wydać przy kasie, oraz sposób ich wystawienia.",
+ "tax_categories": "Grupy decydujące o tym, która stawka podatku dotyczy produktu.",
+ "tax_rates": "Podatek naliczany według kategorii i regionu.",
+ "webhook_deliveries": "Każde zdarzenie wysłane do tego punktu końcowego i informacja, czy zostało odebrane.",
+ "webhook_endpoints": "Gdzie Twoje inne systemy są powiadamiane, gdy coś dzieje się w sklepie.",
+ "returns": "Towary wracające do sklepu, od zgłoszenia do zwrotu pieniędzy.",
+ "exchanges": "Zakupy wymieniane na inny rozmiar, kolor lub produkt.",
+ "claims": "Nieudane dostawy — uszkodzone, brakujące lub błędne produkty — i sposób ich rozwiązania."
},
"tax_categories": {
"add_cta": "Dodaj kategorię podatkową",
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index c2200b806e..0c3a456673 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -2584,7 +2584,8 @@
"inventory": "库存",
"suppliers": "供应商",
"loyalty": "会员权益",
- "store_credits": "店铺信用"
+ "store_credits": "店铺信用",
+ "commission_rates": "佣金费率"
},
"option_types": {
"columns": {
@@ -3008,10 +3009,17 @@
"use_default_addresses": "使用客户的默认账单和配送地址"
},
"payment_statuses": {
+ "none": "未付款",
+ "authorized": "已授权",
+ "partially_paid": "部分付款",
+ "paid": "已付款",
+ "partially_refunded": "部分退款",
+ "refunded": "已退款",
+ "overcharged": "多付款",
+ "voided": "已作废",
"balance_due": "待付款",
"credit_owed": "应退款",
"failed": "失败",
- "paid": "已付款",
"void": "已作废"
},
"statuses": {
@@ -4850,6 +4858,7 @@
},
"all_done": "全部完成 🎉",
"download": "下载文件",
+ "manage_requirements": "管理要求",
"policy_empty": "该政策尚无内容。",
"policy_updated": "最后更新于 {{date}}",
"progress": "已完成 {{done}} / {{total}}",
@@ -5335,7 +5344,31 @@
"stock_transfers": "在各地点之间调拨的库存,以及已到货的部分。",
"purchase_orders": "已向供应商订购的库存,以及已到货的部分",
"suppliers": "你的供应商通讯簿",
- "stock_levels": "各地点的库存情况:现有、已分配给订单、结账中暂扣、可售以及在途。"
+ "stock_levels": "各地点的库存情况:现有、已分配给订单、结账中暂扣、可售以及在途。",
+ "allowed_origins": "允许从浏览器调用您店铺 API 的网址。",
+ "channels": "您的销售渠道——每个店面、应用或门户,各有自己的目录和默认设置。",
+ "commission_rates": "平台在每笔销售中收取的费用,按列表顺序应用。",
+ "custom_field_definitions": "附加到商品、订单、客户及其他记录上的额外字段。",
+ "customers": "在您店铺购物或注册过的所有人。",
+ "gift_cards": "客户在结账时使用的预付卡。",
+ "imports": "您上传的 CSV 文件,以及每个文件的处理结果。",
+ "markets": "您销售的地区,各有自己的货币、税务和配送设置。",
+ "orders": "店铺收到的每一笔订单及其当前状态。",
+ "draft_orders": "团队代客户创建、尚未提交的订单。",
+ "payment_methods": "客户可用的支付方式,以及每个选项背后的服务商。",
+ "policies": "发布在店面上的条款、隐私、退货和配送政策。",
+ "products": "您销售的所有商品,包括其变体、价格和库存。",
+ "promotions": "折扣与优惠,以及决定何时生效的规则。",
+ "seller_requirements": "卖家在获批前需完成的核对清单。",
+ "sellers": "在您平台上经营的第三方卖家及各自的状态。",
+ "store_credits": "客户可在结账时使用的余额,以及每笔余额的发放方式。",
+ "tax_categories": "决定商品适用哪种税率的分组。",
+ "tax_rates": "按类别和地区收取的税费。",
+ "webhook_deliveries": "发送到此端点的每个事件,以及是否已被接收。",
+ "webhook_endpoints": "店铺发生事件时通知您其他系统的地址。",
+ "returns": "退回的商品,从申请到退款。",
+ "exchanges": "换成其他尺码、颜色或商品的购买。",
+ "claims": "出问题的配送——损坏、缺失或错发的商品——以及各自的处理结果。"
},
"tax_categories": {
"add_cta": "添加税务类别",
diff --git a/packages/dashboard/src/nav/default.ts b/packages/dashboard/src/nav/default.ts
index d6b523eb03..93d2b88ea2 100644
--- a/packages/dashboard/src/nav/default.ts
+++ b/packages/dashboard/src/nav/default.ts
@@ -221,6 +221,16 @@ nav.add({
subject: Subject.Seller,
position: 450,
children: [
+ // What the marketplace charges on each sale. A rules engine merchants tune
+ // the way they tune promotions and price lists, and the input to the
+ // ledger below — so it lives here rather than in Settings.
+ {
+ key: 'sellers.commission-rates',
+ labelKey: 'admin.nav.commission_rates',
+ path: '/sellers/commission-rates',
+ subject: Subject.CommissionRate,
+ position: 50,
+ },
// The fund ledger. Under Sellers because that is what it is about, the
// way returns sit under Orders — and gated on the ledger subjects, so a
// staff member who manages sellers without seeing the money gets neither.
diff --git a/packages/dashboard/src/nav/settings.ts b/packages/dashboard/src/nav/settings.ts
index 0c59517725..fe32b95769 100644
--- a/packages/dashboard/src/nav/settings.ts
+++ b/packages/dashboard/src/nav/settings.ts
@@ -5,7 +5,6 @@ import {
CreditCardIcon,
GlobeIcon,
GlobeLockIcon,
- HandCoinsIcon,
KeyRoundIcon,
MailIcon,
PackageIcon,
@@ -261,18 +260,6 @@ settingsNav.add({
subject: Subject.SellerPayout,
})
-settingsNav.add({
- key: 'settings.commission-rates',
- labelKey: 'admin.settings_nav.items.commission_rates',
- descriptionKey: 'admin.settings_nav.descriptions.commission_rates',
- keywords: ['marketplace', 'sellers', 'payouts', 'fees'],
- path: '/commission-rates',
- icon: HandCoinsIcon,
- group: 'marketplace',
- position: 200,
- subject: Subject.CommissionRate,
-})
-
settingsNav.add({
key: 'settings.seller-requirements',
labelKey: 'admin.settings_nav.items.seller_requirements',
diff --git a/packages/dashboard/src/routeTree.gen.ts b/packages/dashboard/src/routeTree.gen.ts
index 544799dc0f..7a2f43f068 100644
--- a/packages/dashboard/src/routeTree.gen.ts
+++ b/packages/dashboard/src/routeTree.gen.ts
@@ -59,6 +59,7 @@ import { Route as SettingsChannelsRouteImport } from './routes/_authenticated/$s
import { Route as SettingsApiKeysRouteImport } from './routes/_authenticated/$storeId/settings/api-keys'
import { Route as SettingsAllowedOriginsRouteImport } from './routes/_authenticated/$storeId/settings/allowed-origins'
import { Route as SellersTransfersRouteImport } from './routes/_authenticated/$storeId/sellers/transfers'
+import { Route as SellersCommissionRatesRouteImport } from './routes/_authenticated/$storeId/sellers/commission-rates'
import { Route as SellersSellerIdRouteImport } from './routes/_authenticated/$storeId/sellers/$sellerId'
import { Route as ReportsNewRouteImport } from './routes/_authenticated/$storeId/reports/new'
import { Route as ReportsReportIdRouteImport } from './routes/_authenticated/$storeId/reports/$reportId'
@@ -357,6 +358,11 @@ const SellersTransfersRoute = SellersTransfersRouteImport.update({
path: '/sellers/transfers',
getParentRoute: () => authenticatedStoreIdRoute,
} as any)
+const SellersCommissionRatesRoute = SellersCommissionRatesRouteImport.update({
+ id: '/sellers/commission-rates',
+ path: '/sellers/commission-rates',
+ getParentRoute: () => authenticatedStoreIdRoute,
+} as any)
const SellersSellerIdRoute = SellersSellerIdRouteImport.update({
id: '/sellers/$sellerId',
path: '/sellers/$sellerId',
@@ -631,6 +637,7 @@ export interface FileRoutesByFullPath {
'/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/$storeId/reports/new': typeof ReportsNewRoute
'/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -725,6 +732,7 @@ export interface FileRoutesByTo {
'/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/$storeId/reports/new': typeof ReportsNewRoute
'/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -823,6 +831,7 @@ export interface FileRoutesById {
'/_authenticated/$storeId/reports/$reportId': typeof ReportsReportIdRoute
'/_authenticated/$storeId/reports/new': typeof ReportsNewRoute
'/_authenticated/$storeId/sellers/$sellerId': typeof SellersSellerIdRoute
+ '/_authenticated/$storeId/sellers/commission-rates': typeof SellersCommissionRatesRoute
'/_authenticated/$storeId/sellers/transfers': typeof SellersTransfersRoute
'/_authenticated/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/_authenticated/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
@@ -921,6 +930,7 @@ export interface FileRouteTypes {
| '/$storeId/reports/$reportId'
| '/$storeId/reports/new'
| '/$storeId/sellers/$sellerId'
+ | '/$storeId/sellers/commission-rates'
| '/$storeId/sellers/transfers'
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
@@ -1015,6 +1025,7 @@ export interface FileRouteTypes {
| '/$storeId/reports/$reportId'
| '/$storeId/reports/new'
| '/$storeId/sellers/$sellerId'
+ | '/$storeId/sellers/commission-rates'
| '/$storeId/sellers/transfers'
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
@@ -1112,6 +1123,7 @@ export interface FileRouteTypes {
| '/_authenticated/$storeId/reports/$reportId'
| '/_authenticated/$storeId/reports/new'
| '/_authenticated/$storeId/sellers/$sellerId'
+ | '/_authenticated/$storeId/sellers/commission-rates'
| '/_authenticated/$storeId/sellers/transfers'
| '/_authenticated/$storeId/settings/allowed-origins'
| '/_authenticated/$storeId/settings/api-keys'
@@ -1535,6 +1547,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SellersTransfersRouteImport
parentRoute: typeof authenticatedStoreIdRoute
}
+ '/_authenticated/$storeId/sellers/commission-rates': {
+ id: '/_authenticated/$storeId/sellers/commission-rates'
+ path: '/sellers/commission-rates'
+ fullPath: '/$storeId/sellers/commission-rates'
+ preLoaderRoute: typeof SellersCommissionRatesRouteImport
+ parentRoute: typeof authenticatedStoreIdRoute
+ }
'/_authenticated/$storeId/sellers/$sellerId': {
id: '/_authenticated/$storeId/sellers/$sellerId'
path: '/sellers/$sellerId'
@@ -1953,6 +1972,7 @@ interface authenticatedStoreIdRouteChildren {
ReportsReportIdRoute: typeof ReportsReportIdRoute
ReportsNewRoute: typeof ReportsNewRoute
SellersSellerIdRoute: typeof SellersSellerIdRoute
+ SellersCommissionRatesRoute: typeof SellersCommissionRatesRoute
SellersTransfersRoute: typeof SellersTransfersRoute
TransfersNewRoute: typeof TransfersNewRoute
CompaniesIndexRoute: typeof CompaniesIndexRoute
@@ -2014,6 +2034,7 @@ const authenticatedStoreIdRouteChildren: authenticatedStoreIdRouteChildren = {
ReportsReportIdRoute: ReportsReportIdRoute,
ReportsNewRoute: ReportsNewRoute,
SellersSellerIdRoute: SellersSellerIdRoute,
+ SellersCommissionRatesRoute: SellersCommissionRatesRoute,
SellersTransfersRoute: SellersTransfersRoute,
TransfersNewRoute: TransfersNewRoute,
CompaniesIndexRoute: CompaniesIndexRoute,
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/drafts.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/drafts.tsx
index 1805c96a2a..85533be53e 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/drafts.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/drafts.tsx
@@ -17,6 +17,8 @@ function DraftOrdersPage() {
return (
<ResourceTable
+ docsPath="orders/creating-orders"
+ description={t('admin.table_descriptions.draft_orders')}
tableKey="orders"
queryKey="draft-orders"
queryFn={(params) => adminClient.orders.list(params)}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/categories/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/categories/index.tsx
index 60d66f284c..52f82e0731 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/categories/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/categories/index.tsx
@@ -78,7 +78,7 @@ function CategoriesPage() {
sticky={false}
title={t('admin.categories.title')}
description={t('admin.table_descriptions.categories')}
- docsPath="manage-products/product-taxonomies"
+ docsPath="products/categories"
actions={
<Can I="create" a={Subject.Category}>
<Button
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/sellers/commission-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/commission-rates.tsx
new file mode 100644
index 0000000000..3899cfaa70
--- /dev/null
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/commission-rates.tsx
@@ -0,0 +1,865 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type {
+ CommissionRate,
+ CommissionRateCreateParams,
+ CommissionRuleType,
+} from '@spree/admin-sdk'
+import {
+ adminClient,
+ Can,
+ mapSpreeErrorsToForm,
+ PreferencesForm,
+ ResourceMultiAutocomplete,
+ ResourceTable,
+ resourceSearchSchema,
+ Subject,
+ typeDescription,
+ typeLabel,
+ usePermissions,
+ useStore,
+} from '@spree/dashboard-core'
+import {
+ Alert,
+ AlertDescription,
+ Button,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+ Field,
+ FieldError,
+ FieldGroup,
+ FieldLabel,
+ Input,
+ InputGroup,
+ InputGroupAddon,
+ InputGroupInput,
+ InputGroupText,
+ RowActions,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetFooter,
+ SheetHeader,
+ SheetTitle,
+ Switch,
+ useConfirm,
+ useRowClickBridge,
+} from '@spree/dashboard-ui'
+import { PlusIcon, Trash2Icon, TriangleAlertIcon } from '@spree/dashboard-ui/icons'
+import { useQueryClient } from '@tanstack/react-query'
+import { createFileRoute, useNavigate } from '@tanstack/react-router'
+import { useEffect } from 'react'
+import { Controller, type UseFormReturn, useFieldArray, useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { z } from 'zod/v4'
+import { commissionRuleSubjectPicker } from '../../../../components/spree/commission-rule-subjects'
+import {
+ useCommissionRate,
+ useCommissionRuleTypes,
+ useCreateCommissionRate,
+ useDeleteCommissionRate,
+ useUpdateCommissionRate,
+} from '../../../../hooks/use-commission-rates'
+import { slugify } from '../../../../lib/slugify'
+import {
+ COMMISSION_RATE_DEFAULTS,
+ COMMISSION_RATE_KINDS,
+ type CommissionRateFormValues,
+ commissionRateFormSchema,
+ commissionRateToFormValues,
+ commissionRateValuesToParams,
+} from '../../../../schemas/commission-rate'
+import '../../../../tables/commission-rates'
+
+const commissionRatesSearchSchema = resourceSearchSchema.extend({
+ edit: z.string().optional(),
+ new: z.coerce.boolean().optional(),
+})
+
+export const Route = createFileRoute('/_authenticated/$storeId/sellers/commission-rates')({
+ validateSearch: commissionRatesSearchSchema,
+ component: CommissionRatesPage,
+})
+
+function CommissionRatesPage() {
+ const { t } = useTranslation()
+ const search = Route.useSearch() as z.infer<typeof commissionRatesSearchSchema>
+ const navigate = useNavigate()
+ const confirm = useConfirm()
+ const deleteMutation = useDeleteCommissionRate()
+ const { permissions } = usePermissions()
+ const queryClient = useQueryClient()
+
+ const canUpdate = permissions.can('update', Subject.CommissionRate)
+ // A deep link to ?edit= would otherwise open the sheet for someone who may
+ // only read. The server refuses the write either way; this stops the form
+ // being offered at all.
+ const editId = canUpdate ? search.edit : undefined
+ const isCreating = !!search.new
+
+ const closeSheet = () =>
+ navigate({
+ search: (prev: Record<string, unknown>) => {
+ const { edit: _e, new: _n, ...rest } = prev
+ return rest as never
+ },
+ })
+
+ const openCreate = () =>
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, new: true }) as never })
+
+ const openEdit = (id: string) =>
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, edit: id }) as never })
+
+ useRowClickBridge('data-commission-rate-id', canUpdate ? openEdit : () => {})
+
+ async function handleDelete(rate: CommissionRate) {
+ const ok = await confirm({
+ title: t('admin.commission_rates.delete_confirm.title'),
+ message: t('admin.commission_rates.delete_confirm.message', { name: rate.name ?? '' }),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ if (!ok) return
+ await deleteMutation.mutateAsync(rate.id).catch(() => undefined)
+ }
+
+ return (
+ <>
+ <ResourceTable<CommissionRate>
+ tableKey="commission-rates"
+ queryKey="commission-rates"
+ queryFn={(params) => adminClient.commissionRates.list(params)}
+ searchParams={search}
+ reorder={
+ canUpdate
+ ? {
+ onReorder: async (id, position) => {
+ await adminClient.commissionRates.update(id, { position })
+ queryClient.invalidateQueries({ queryKey: ['commission-rates'] })
+ },
+ }
+ : undefined
+ }
+ rowActions={(rate) => (
+ <RowActions
+ actions={[
+ { key: 'edit', visible: canUpdate, onSelect: () => openEdit(rate.id) },
+ {
+ key: 'delete',
+ destructive: true,
+ visible: permissions.can('destroy', Subject.CommissionRate),
+ disabled: deleteMutation.isPending,
+ onSelect: () => handleDelete(rate),
+ },
+ ]}
+ />
+ )}
+ actions={
+ <Can I="create" a={Subject.CommissionRate}>
+ <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>
+ <PlusIcon className="size-4" />
+ {t('admin.commission_rates.add_cta')}
+ </Button>
+ </Can>
+ }
+ />
+
+ {isCreating && <CreateCommissionRateSheet open onOpenChange={(o) => !o && closeSheet()} />}
+ {editId && (
+ <EditCommissionRateSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />
+ )}
+ </>
+ )
+}
+
+function CreateCommissionRateSheet({
+ open,
+ onOpenChange,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const createMutation = useCreateCommissionRate()
+ const form = useForm<CommissionRateFormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(commissionRateFormSchema) as any,
+ defaultValues: COMMISSION_RATE_DEFAULTS,
+ })
+
+ async function onSubmit(values: CommissionRateFormValues) {
+ try {
+ await createMutation.mutateAsync(
+ commissionRateValuesToParams(values) as CommissionRateCreateParams,
+ )
+ form.reset(COMMISSION_RATE_DEFAULTS)
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Sheet
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) form.reset(COMMISSION_RATE_DEFAULTS)
+ onOpenChange(next)
+ }}
+ >
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>{t('admin.pages.settings.commission_rates.add_sheet_title')}</SheetTitle>
+ <SheetDescription>
+ {t('admin.commission_rates.create_description')}{' '}
+ {t('admin.commission_rates.order_hint')}
+ </SheetDescription>
+ </SheetHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <CommissionRateFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button type="submit" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting
+ ? t('admin.actions.creating')
+ : t('admin.commission_rates.create_label')}
+ </Button>
+ </SheetFooter>
+ </form>
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function EditCommissionRateSheet({
+ id,
+ open,
+ onOpenChange,
+}: {
+ id: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { data: rate, isLoading } = useCommissionRate(id)
+ const updateMutation = useUpdateCommissionRate(id)
+
+ const form = useForm<CommissionRateFormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(commissionRateFormSchema) as any,
+ defaultValues: COMMISSION_RATE_DEFAULTS,
+ })
+
+ useEffect(() => {
+ if (rate) form.reset(commissionRateToFormValues(rate))
+ }, [rate, form])
+
+ async function onSubmit(values: CommissionRateFormValues) {
+ try {
+ await updateMutation.mutateAsync(commissionRateValuesToParams(values))
+ form.reset(values)
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Sheet open={open} onOpenChange={onOpenChange}>
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>
+ {rate?.name ?? t('admin.pages.settings.commission_rates.edit_sheet_title')}
+ </SheetTitle>
+ <SheetDescription>{t('admin.commission_rates.edit_description')}</SheetDescription>
+ </SheetHeader>
+ {isLoading ? (
+ <div className="p-4 text-sm text-muted-foreground">{t('admin.common.loading')}</div>
+ ) : (
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <CommissionRateFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button
+ type="submit"
+ disabled={form.formState.isSubmitting || !form.formState.isDirty}
+ >
+ {form.formState.isSubmitting ? t('admin.actions.saving') : t('admin.actions.save')}
+ </Button>
+ </SheetFooter>
+ </form>
+ )}
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function CommissionRateFormFields({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { errors } = form.formState
+ const kind = form.watch('kind')
+ const name = form.watch('name')
+ // "Base Commission" becomes "base-commission" while the operator types, and
+ // stops the moment they write a code of their own — matching how a channel's
+ // code is derived.
+ useEffect(() => {
+ if (form.getFieldState('code').isDirty) return
+
+ form.setValue('code', slugify(name ?? ''))
+ }, [name, form])
+
+ const kindOptions = COMMISSION_RATE_KINDS.map((value) => ({
+ value,
+ label: t(`admin.fields.commission_rate.kind.options.${value}`),
+ }))
+
+ return (
+ <FieldGroup>
+ {errors.root?.message && (
+ <p className="text-sm text-destructive" role="alert">
+ {errors.root.message}
+ </p>
+ )}
+
+ <Field>
+ <FieldLabel htmlFor="name">{t('admin.fields.name.label')}</FieldLabel>
+ <Input
+ id="name"
+ autoFocus
+ placeholder={t('admin.fields.commission_rate.name.placeholder')}
+ aria-invalid={!!errors.name || undefined}
+ {...form.register('name')}
+ />
+ <FieldError errors={[errors.name]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="code">{t('admin.fields.commission_rate.code.label')}</FieldLabel>
+ <Input
+ id="code"
+ placeholder={t('admin.fields.commission_rate.code.placeholder')}
+ aria-invalid={!!errors.code || undefined}
+ {...form.register('code')}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.code.help')}
+ </span>
+ <FieldError errors={[errors.code]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="kind">{t('admin.fields.commission_rate.kind.label')}</FieldLabel>
+ <Controller
+ name="kind"
+ control={form.control}
+ render={({ field }) => (
+ <Select items={kindOptions} value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="kind">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {kindOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+
+ {kind === 'percentage' ? (
+ <Field>
+ <FieldLabel htmlFor="value">{t('admin.fields.commission_rate.value.label')}</FieldLabel>
+ <InputGroup>
+ <InputGroupInput
+ id="value"
+ type="number"
+ step="0.01"
+ min="0"
+ max="100"
+ aria-invalid={!!errors.value || undefined}
+ {...form.register('value')}
+ />
+ <InputGroupAddon align="inline-end">
+ <InputGroupText>%</InputGroupText>
+ </InputGroupAddon>
+ </InputGroup>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.value.help_percentage')}
+ </span>
+ <FieldError errors={[errors.value]} />
+ </Field>
+ ) : (
+ <>
+ <FlatFeeAmountsField form={form} />
+ <FlatFeeCapField form={form} />
+ </>
+ )}
+
+ <CommissionRulesField form={form} />
+
+ {kind === 'percentage' && <PercentageBoundsField form={form} />}
+
+ <Field>
+ <FieldLabel htmlFor="commission_tax_rate">
+ {t('admin.fields.commission_rate.commission_tax_rate.label')}
+ </FieldLabel>
+ <InputGroup>
+ <InputGroupInput
+ id="commission_tax_rate"
+ type="number"
+ step="0.01"
+ min="0"
+ placeholder={t('admin.fields.commission_rate.commission_tax_rate.placeholder')}
+ {...form.register('commission_tax_rate')}
+ />
+ <InputGroupAddon align="inline-end">
+ <InputGroupText>%</InputGroupText>
+ </InputGroupAddon>
+ </InputGroup>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.commission_tax_rate.help')}
+ </span>
+ <FieldError errors={[errors.commission_tax_rate]} />
+ </Field>
+
+ {/* A parcel is part of the sale a flat fee already charges for, so the
+ same amount again would bill one sale twice. A marketplace wanting a
+ flat charge on delivery states it as its own rate. */}
+ {kind === 'percentage' && (
+ <ToggleField
+ form={form}
+ name="include_shipping"
+ label={t('admin.fields.commission_rate.include_shipping.label')}
+ help={t('admin.fields.commission_rate.include_shipping.help')}
+ />
+ )}
+
+ <ToggleField
+ form={form}
+ name="tax_inclusive"
+ label={t('admin.fields.commission_rate.tax_inclusive.label')}
+ help={t('admin.fields.commission_rate.tax_inclusive.help')}
+ />
+
+ <ToggleField
+ form={form}
+ name="enabled"
+ label={t('admin.fields.enabled.label')}
+ help={t('admin.fields.commission_rate.enabled.help')}
+ />
+ </FieldGroup>
+ )
+}
+
+function ToggleField({
+ form,
+ name,
+ label,
+ help,
+}: {
+ form: UseFormReturn<CommissionRateFormValues>
+ name: 'enabled' | 'tax_inclusive' | 'include_shipping'
+ label: string
+ help: string
+}) {
+ return (
+ <Field>
+ <div className="flex items-start justify-between gap-4">
+ <div className="flex flex-col">
+ <FieldLabel htmlFor={name} className="cursor-pointer">
+ {label}
+ </FieldLabel>
+ <span className="text-xs text-muted-foreground">{help}</span>
+ </div>
+ <Controller
+ name={name}
+ control={form.control}
+ render={({ field }) => (
+ <Switch id={name} checked={!!field.value} onCheckedChange={field.onChange} />
+ )}
+ />
+ </div>
+ </Field>
+ )
+}
+
+/**
+ * What a flat fee charges, one field per currency the store sells in.
+ *
+ * No currency picker: a flat fee cannot travel the way a percentage can, and
+ * a marketplace selling in three currencies needs an amount in each rather
+ * than one figure and a conversion nobody asked for. A currency left empty is
+ * one this rate does not charge — that sale falls through to the next rate.
+ */
+function FlatFeeAmountsField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { currencies } = useStore()
+ const amounts = form.watch('amounts')
+ const hasAmount = Object.values(amounts ?? {}).some(
+ (amount) => String(amount ?? '').trim() !== '',
+ )
+
+ return (
+ <Field>
+ <FieldLabel>{t('admin.fields.commission_rate.amounts.label')}</FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.amounts.help')}
+ </span>
+ {hasAmount && (
+ <Alert variant="warning" className="mt-2">
+ <TriangleAlertIcon />
+ <AlertDescription>
+ {t('admin.commission_rates.flat_fee_exceeds_sale_warning')}
+ </AlertDescription>
+ </Alert>
+ )}
+ <div className="flex flex-col gap-2 pt-1">
+ {currencies.map((currency) => (
+ <div key={currency} className="flex items-center gap-2">
+ <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
+ <Controller
+ control={form.control}
+ name="amounts"
+ render={({ field }) => (
+ <Input
+ type="number"
+ step="0.01"
+ min="0"
+ aria-label={currency}
+ value={(field.value?.[currency] as string) ?? ''}
+ onChange={(event) =>
+ field.onChange({ ...field.value, [currency]: event.target.value })
+ }
+ />
+ )}
+ />
+ </div>
+ ))}
+ </div>
+ </Field>
+ )
+}
+
+/**
+ * Optional cap on a flat fee per sale line. The engine already clamps the
+ * computed fee to this ceiling — surfacing it here is what makes a minimum
+ * fee larger than a cheap item's price a deliberate choice rather than a
+ * silent overcharge.
+ */
+function FlatFeeCapField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { currencies } = useStore()
+ const amounts = form.watch('amounts')
+ const cappedCurrencies = currencies.filter(
+ (currency) => String(amounts?.[currency] ?? '').trim() !== '',
+ )
+
+ if (cappedCurrencies.length === 0) {
+ return null
+ }
+
+ return (
+ <Field>
+ <FieldLabel>{t('admin.fields.commission_rate.flat_fee_cap.label')}</FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.flat_fee_cap.help')}
+ </span>
+ <div className="flex flex-col gap-2 pt-1">
+ {cappedCurrencies.map((currency) => (
+ <div key={currency} className="flex items-center gap-2">
+ <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
+ <Controller
+ control={form.control}
+ name="bounds"
+ render={({ field }) => {
+ const bound = field.value?.[currency] ?? { min_amount: '', max_amount: '' }
+
+ return (
+ <Input
+ type="number"
+ step="0.01"
+ min="0"
+ aria-label={`${currency} ${t('admin.fields.commission_rate.max_amount.label')}`}
+ placeholder={t('admin.fields.commission_rate.max_amount.label')}
+ value={bound.max_amount}
+ onChange={(event) =>
+ field.onChange({
+ ...field.value,
+ [currency]: { ...bound, max_amount: event.target.value },
+ })
+ }
+ />
+ )
+ }}
+ />
+ </div>
+ ))}
+ </div>
+ </Field>
+ )
+}
+
+/**
+ * Optional bounds on a percentage: never charge less than this, never more
+ * than that. Amounts, so they carry a currency of their own — which is what
+ * stops "at least 5" meaning five of whatever the buyer happened to pay in.
+ */
+/**
+ * A floor and a cap per currency, on the same one-row-per-currency footing as
+ * the flat fee. Each bound holds only in its own currency — a sale in a
+ * currency left blank is charged unbounded rather than against a converted
+ * figure the merchant never agreed to.
+ */
+function PercentageBoundsField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { errors } = form.formState
+ const { currencies } = useStore()
+
+ return (
+ <Field>
+ <FieldLabel>{t('admin.fields.commission_rate.bounds.label')}</FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.bounds.help')}
+ </span>
+ <div className="flex flex-col gap-2 pt-1">
+ {currencies.map((currency) => (
+ <div key={currency} className="flex items-center gap-2">
+ <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
+ <Controller
+ control={form.control}
+ name="bounds"
+ render={({ field }) => {
+ const bound = field.value?.[currency] ?? { min_amount: '', max_amount: '' }
+ const write = (key: 'min_amount' | 'max_amount', amount: string) =>
+ field.onChange({ ...field.value, [currency]: { ...bound, [key]: amount } })
+
+ return (
+ <>
+ <Input
+ type="number"
+ step="0.01"
+ min="0"
+ aria-label={`${currency} ${t('admin.fields.commission_rate.min_amount.label')}`}
+ placeholder={t('admin.fields.commission_rate.min_amount.label')}
+ value={bound.min_amount}
+ onChange={(event) => write('min_amount', event.target.value)}
+ />
+ <span className="text-sm text-muted-foreground">–</span>
+ <Input
+ type="number"
+ step="0.01"
+ min="0"
+ aria-label={`${currency} ${t('admin.fields.commission_rate.max_amount.label')}`}
+ placeholder={t('admin.fields.commission_rate.max_amount.label')}
+ value={bound.max_amount}
+ onChange={(event) => write('max_amount', event.target.value)}
+ />
+ </>
+ )
+ }}
+ />
+ </div>
+ ))}
+ </div>
+ <FieldError errors={[errors.bounds]} />
+ </Field>
+ )
+}
+
+/**
+ * The rate's conditions.
+ *
+ * Every condition has to hold for the rate to apply, and a condition naming
+ * several records means any of them — so "cameras or audio, from that seller"
+ * is two conditions. A rate with none charges every sale, which the empty
+ * state says outright.
+ *
+ * Built from the rule kinds the marketplace reports rather than a list baked
+ * in here, so a kind added by an extension appears without a change to this
+ * file. Kinds already used drop out of the picker: a second condition of the
+ * same kind would repeat the first or contradict it.
+ */
+function CommissionRulesField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { data: ruleTypes } = useCommissionRuleTypes()
+ const rulesArray = useFieldArray<CommissionRateFormValues, 'rules', '_key'>({
+ control: form.control,
+ name: 'rules',
+ keyName: '_key',
+ })
+
+ const usedTypes = new Set(rulesArray.fields.map((rule) => rule.type))
+ const availableTypes = (ruleTypes?.data ?? []).filter((type) => !usedTypes.has(type.type))
+
+ return (
+ <Field>
+ <div className="flex items-center justify-between">
+ <FieldLabel>{t('admin.fields.commission_rate.rules.label')}</FieldLabel>
+ {availableTypes.length > 0 && (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button type="button" variant="outline" size="sm">
+ <PlusIcon className="size-4" />
+ {t('admin.commission_rates.conditions.add')}
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end">
+ {availableTypes.map((type) => (
+ <DropdownMenuItem
+ key={type.type}
+ onClick={() =>
+ rulesArray.append({ type: type.type, preferences: {}, product_ids: [] })
+ }
+ >
+ {typeLabel('commission_rule', type.type, type.name)}
+ </DropdownMenuItem>
+ ))}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ )}
+ </div>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.rules.help')}
+ </span>
+
+ <div className="flex flex-col gap-3 pt-1">
+ {rulesArray.fields.length === 0 && (
+ <span className="text-xs text-muted-foreground">
+ {t('admin.commission_rates.applies_to_everything')}
+ </span>
+ )}
+
+ {rulesArray.fields.map((field, index) => (
+ <CommissionRuleRow
+ key={field._key}
+ form={form}
+ index={index}
+ ruleType={(ruleTypes?.data ?? []).find((candidate) => candidate.type === field.type)}
+ fallbackLabel={field.type}
+ onRemove={() => rulesArray.remove(index)}
+ />
+ ))}
+ </div>
+ </Field>
+ )
+}
+
+/**
+ * One condition. What it renders is decided by what the server said about the
+ * kind: a condition naming records gets that resource's picker, and anything
+ * else renders its own preference schema — so a value band needs no code here.
+ */
+function CommissionRuleRow({
+ form,
+ index,
+ ruleType,
+ fallbackLabel,
+ onRemove,
+}: {
+ form: UseFormReturn<CommissionRateFormValues>
+ index: number
+ ruleType?: CommissionRuleType
+ fallbackLabel: string
+ onRemove: () => void
+}) {
+ const { t } = useTranslation()
+ const schema = ruleType?.preference_schema ?? []
+ // Catalog-scale references arrive as their own field; everything else names
+ // records through an id list in preferences. Either way the picker comes
+ // from the registry, keyed by rule kind.
+ const picker = ruleType ? commissionRuleSubjectPicker(ruleType.type) : undefined
+ const associationField = ruleType?.association_fields?.[0]
+ const preferenceIdKey = schema.find((preference) => preference.key.endsWith('_ids'))?.key
+
+ return (
+ <div className="flex flex-col gap-2 rounded-md border p-3">
+ <div className="flex items-center justify-between">
+ <div className="flex flex-col">
+ <span className="text-sm">
+ {ruleType ? typeLabel('commission_rule', ruleType.type, ruleType.name) : fallbackLabel}
+ </span>
+ {ruleType && typeDescription('commission_rule', ruleType.type, ruleType.description) && (
+ <span className="text-xs text-muted-foreground">
+ {typeDescription('commission_rule', ruleType.type, ruleType.description)}
+ </span>
+ )}
+ </div>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ onClick={onRemove}
+ aria-label={t('admin.actions.delete')}
+ >
+ <Trash2Icon className="size-4" />
+ </Button>
+ </div>
+
+ {picker && associationField ? (
+ <Controller
+ control={form.control}
+ name={`rules.${index}.product_ids`}
+ render={({ field }) => (
+ <ResourceMultiAutocomplete
+ {...picker(`commission-rule-${ruleType?.type}`)}
+ value={field.value ?? []}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ ) : picker && preferenceIdKey ? (
+ <Controller
+ control={form.control}
+ name={`rules.${index}.preferences`}
+ render={({ field }) => (
+ <ResourceMultiAutocomplete
+ {...picker(`commission-rule-${ruleType?.type}`)}
+ value={(field.value?.[preferenceIdKey] ?? []) as string[]}
+ onChange={(ids: string[]) =>
+ field.onChange({ ...field.value, [preferenceIdKey]: ids })
+ }
+ />
+ )}
+ />
+ ) : (
+ <Controller
+ control={form.control}
+ name={`rules.${index}.preferences`}
+ render={({ field }) => (
+ <PreferencesForm schema={schema} values={field.value} onChange={field.onChange} />
+ )}
+ />
+ )}
+ </div>
+ )
+}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
index 76137b7c17..7e4a02753a 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
@@ -40,8 +40,9 @@ function ApiKeysSettingsPage() {
return (
<div className="flex flex-col gap-6">
<PageHeader
+ docsPath="settings/api-keys"
title={t('admin.pages.settings.api_keys.title')}
- subtitle={t('admin.pages.settings.api_keys.subtitle')}
+ description={t('admin.pages.settings.api_keys.subtitle')}
actions={
<Button onClick={() => setCreateOpen(true)}>
<PlusIcon className="size-4" />
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx
index 35e2e4d36d..b7bbee943d 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx
@@ -1,865 +1,13 @@
-import { zodResolver } from '@hookform/resolvers/zod'
-import type {
- CommissionRate,
- CommissionRateCreateParams,
- CommissionRuleType,
-} from '@spree/admin-sdk'
-import {
- adminClient,
- Can,
- mapSpreeErrorsToForm,
- PreferencesForm,
- ResourceMultiAutocomplete,
- ResourceTable,
- resourceSearchSchema,
- Subject,
- typeDescription,
- typeLabel,
- usePermissions,
- useStore,
-} from '@spree/dashboard-core'
-import {
- Alert,
- AlertDescription,
- Button,
- DropdownMenu,
- DropdownMenuContent,
- DropdownMenuItem,
- DropdownMenuTrigger,
- Field,
- FieldError,
- FieldGroup,
- FieldLabel,
- Input,
- InputGroup,
- InputGroupAddon,
- InputGroupInput,
- InputGroupText,
- RowActions,
- Select,
- SelectContent,
- SelectItem,
- SelectTrigger,
- SelectValue,
- Sheet,
- SheetContent,
- SheetDescription,
- SheetFooter,
- SheetHeader,
- SheetTitle,
- Switch,
- useConfirm,
- useRowClickBridge,
-} from '@spree/dashboard-ui'
-import { PlusIcon, Trash2Icon, TriangleAlertIcon } from '@spree/dashboard-ui/icons'
-import { useQueryClient } from '@tanstack/react-query'
-import { createFileRoute, useNavigate } from '@tanstack/react-router'
-import { useEffect } from 'react'
-import { Controller, type UseFormReturn, useFieldArray, useForm } from 'react-hook-form'
-import { useTranslation } from 'react-i18next'
-import { z } from 'zod/v4'
-import { commissionRuleSubjectPicker } from '../../../../components/spree/commission-rule-subjects'
-import {
- useCommissionRate,
- useCommissionRuleTypes,
- useCreateCommissionRate,
- useDeleteCommissionRate,
- useUpdateCommissionRate,
-} from '../../../../hooks/use-commission-rates'
-import { slugify } from '../../../../lib/slugify'
-import {
- COMMISSION_RATE_DEFAULTS,
- COMMISSION_RATE_KINDS,
- type CommissionRateFormValues,
- commissionRateFormSchema,
- commissionRateToFormValues,
- commissionRateValuesToParams,
-} from '../../../../schemas/commission-rate'
-import '../../../../tables/commission-rates'
-
-const commissionRatesSearchSchema = resourceSearchSchema.extend({
- edit: z.string().optional(),
- new: z.coerce.boolean().optional(),
-})
+import { createFileRoute, redirect } from '@tanstack/react-router'
+// Commission rates moved out of Settings and under Sellers, beside the
+// transfers and payouts they feed. The old address keeps working.
export const Route = createFileRoute('/_authenticated/$storeId/settings/commission-rates')({
- validateSearch: commissionRatesSearchSchema,
- component: CommissionRatesPage,
-})
-
-function CommissionRatesPage() {
- const { t } = useTranslation()
- const search = Route.useSearch() as z.infer<typeof commissionRatesSearchSchema>
- const navigate = useNavigate()
- const confirm = useConfirm()
- const deleteMutation = useDeleteCommissionRate()
- const { permissions } = usePermissions()
- const queryClient = useQueryClient()
-
- const canUpdate = permissions.can('update', Subject.CommissionRate)
- // A deep link to ?edit= would otherwise open the sheet for someone who may
- // only read. The server refuses the write either way; this stops the form
- // being offered at all.
- const editId = canUpdate ? search.edit : undefined
- const isCreating = !!search.new
-
- const closeSheet = () =>
- navigate({
- search: (prev: Record<string, unknown>) => {
- const { edit: _e, new: _n, ...rest } = prev
- return rest as never
- },
- })
-
- const openCreate = () =>
- navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, new: true }) as never })
-
- const openEdit = (id: string) =>
- navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, edit: id }) as never })
-
- useRowClickBridge('data-commission-rate-id', canUpdate ? openEdit : () => {})
-
- async function handleDelete(rate: CommissionRate) {
- const ok = await confirm({
- title: t('admin.commission_rates.delete_confirm.title'),
- message: t('admin.commission_rates.delete_confirm.message', { name: rate.name ?? '' }),
- variant: 'destructive',
- confirmLabel: t('admin.actions.delete'),
+ beforeLoad: ({ params }) => {
+ throw redirect({
+ to: '/$storeId/sellers/commission-rates',
+ params: { storeId: params.storeId },
})
- if (!ok) return
- await deleteMutation.mutateAsync(rate.id).catch(() => undefined)
- }
-
- return (
- <>
- <ResourceTable<CommissionRate>
- tableKey="commission-rates"
- queryKey="commission-rates"
- queryFn={(params) => adminClient.commissionRates.list(params)}
- searchParams={search}
- reorder={
- canUpdate
- ? {
- onReorder: async (id, position) => {
- await adminClient.commissionRates.update(id, { position })
- queryClient.invalidateQueries({ queryKey: ['commission-rates'] })
- },
- }
- : undefined
- }
- rowActions={(rate) => (
- <RowActions
- actions={[
- { key: 'edit', visible: canUpdate, onSelect: () => openEdit(rate.id) },
- {
- key: 'delete',
- destructive: true,
- visible: permissions.can('destroy', Subject.CommissionRate),
- disabled: deleteMutation.isPending,
- onSelect: () => handleDelete(rate),
- },
- ]}
- />
- )}
- actions={
- <Can I="create" a={Subject.CommissionRate}>
- <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>
- <PlusIcon className="size-4" />
- {t('admin.commission_rates.add_cta')}
- </Button>
- </Can>
- }
- />
-
- {isCreating && <CreateCommissionRateSheet open onOpenChange={(o) => !o && closeSheet()} />}
- {editId && (
- <EditCommissionRateSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />
- )}
- </>
- )
-}
-
-function CreateCommissionRateSheet({
- open,
- onOpenChange,
-}: {
- open: boolean
- onOpenChange: (open: boolean) => void
-}) {
- const { t } = useTranslation()
- const createMutation = useCreateCommissionRate()
- const form = useForm<CommissionRateFormValues>({
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- resolver: zodResolver(commissionRateFormSchema) as any,
- defaultValues: COMMISSION_RATE_DEFAULTS,
- })
-
- async function onSubmit(values: CommissionRateFormValues) {
- try {
- await createMutation.mutateAsync(
- commissionRateValuesToParams(values) as CommissionRateCreateParams,
- )
- form.reset(COMMISSION_RATE_DEFAULTS)
- onOpenChange(false)
- } catch (err) {
- if (!mapSpreeErrorsToForm(err, form.setError)) throw err
- }
- }
-
- return (
- <Sheet
- open={open}
- onOpenChange={(next) => {
- if (!next) form.reset(COMMISSION_RATE_DEFAULTS)
- onOpenChange(next)
- }}
- >
- <SheetContent>
- <SheetHeader>
- <SheetTitle>{t('admin.pages.settings.commission_rates.add_sheet_title')}</SheetTitle>
- <SheetDescription>
- {t('admin.commission_rates.create_description')}{' '}
- {t('admin.commission_rates.order_hint')}
- </SheetDescription>
- </SheetHeader>
- <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
- <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
- <CommissionRateFormFields form={form} />
- </div>
- <SheetFooter>
- <Button
- type="button"
- variant="outline"
- onClick={() => onOpenChange(false)}
- disabled={form.formState.isSubmitting}
- >
- {t('admin.actions.cancel')}
- </Button>
- <Button type="submit" disabled={form.formState.isSubmitting}>
- {form.formState.isSubmitting
- ? t('admin.actions.creating')
- : t('admin.commission_rates.create_label')}
- </Button>
- </SheetFooter>
- </form>
- </SheetContent>
- </Sheet>
- )
-}
-
-function EditCommissionRateSheet({
- id,
- open,
- onOpenChange,
-}: {
- id: string
- open: boolean
- onOpenChange: (open: boolean) => void
-}) {
- const { t } = useTranslation()
- const { data: rate, isLoading } = useCommissionRate(id)
- const updateMutation = useUpdateCommissionRate(id)
-
- const form = useForm<CommissionRateFormValues>({
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- resolver: zodResolver(commissionRateFormSchema) as any,
- defaultValues: COMMISSION_RATE_DEFAULTS,
- })
-
- useEffect(() => {
- if (rate) form.reset(commissionRateToFormValues(rate))
- }, [rate, form])
-
- async function onSubmit(values: CommissionRateFormValues) {
- try {
- await updateMutation.mutateAsync(commissionRateValuesToParams(values))
- form.reset(values)
- onOpenChange(false)
- } catch (err) {
- if (!mapSpreeErrorsToForm(err, form.setError)) throw err
- }
- }
-
- return (
- <Sheet open={open} onOpenChange={onOpenChange}>
- <SheetContent>
- <SheetHeader>
- <SheetTitle>
- {rate?.name ?? t('admin.pages.settings.commission_rates.edit_sheet_title')}
- </SheetTitle>
- <SheetDescription>{t('admin.commission_rates.edit_description')}</SheetDescription>
- </SheetHeader>
- {isLoading ? (
- <div className="p-4 text-sm text-muted-foreground">{t('admin.common.loading')}</div>
- ) : (
- <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
- <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
- <CommissionRateFormFields form={form} />
- </div>
- <SheetFooter>
- <Button
- type="button"
- variant="outline"
- onClick={() => onOpenChange(false)}
- disabled={form.formState.isSubmitting}
- >
- {t('admin.actions.cancel')}
- </Button>
- <Button
- type="submit"
- disabled={form.formState.isSubmitting || !form.formState.isDirty}
- >
- {form.formState.isSubmitting ? t('admin.actions.saving') : t('admin.actions.save')}
- </Button>
- </SheetFooter>
- </form>
- )}
- </SheetContent>
- </Sheet>
- )
-}
-
-function CommissionRateFormFields({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
- const { t } = useTranslation()
- const { errors } = form.formState
- const kind = form.watch('kind')
- const name = form.watch('name')
- // "Base Commission" becomes "base-commission" while the operator types, and
- // stops the moment they write a code of their own — matching how a channel's
- // code is derived.
- useEffect(() => {
- if (form.getFieldState('code').isDirty) return
-
- form.setValue('code', slugify(name ?? ''))
- }, [name, form])
-
- const kindOptions = COMMISSION_RATE_KINDS.map((value) => ({
- value,
- label: t(`admin.fields.commission_rate.kind.options.${value}`),
- }))
-
- return (
- <FieldGroup>
- {errors.root?.message && (
- <p className="text-sm text-destructive" role="alert">
- {errors.root.message}
- </p>
- )}
-
- <Field>
- <FieldLabel htmlFor="name">{t('admin.fields.name.label')}</FieldLabel>
- <Input
- id="name"
- autoFocus
- placeholder={t('admin.fields.commission_rate.name.placeholder')}
- aria-invalid={!!errors.name || undefined}
- {...form.register('name')}
- />
- <FieldError errors={[errors.name]} />
- </Field>
-
- <Field>
- <FieldLabel htmlFor="code">{t('admin.fields.commission_rate.code.label')}</FieldLabel>
- <Input
- id="code"
- placeholder={t('admin.fields.commission_rate.code.placeholder')}
- aria-invalid={!!errors.code || undefined}
- {...form.register('code')}
- />
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.code.help')}
- </span>
- <FieldError errors={[errors.code]} />
- </Field>
-
- <Field>
- <FieldLabel htmlFor="kind">{t('admin.fields.commission_rate.kind.label')}</FieldLabel>
- <Controller
- name="kind"
- control={form.control}
- render={({ field }) => (
- <Select items={kindOptions} value={field.value} onValueChange={field.onChange}>
- <SelectTrigger id="kind">
- <SelectValue />
- </SelectTrigger>
- <SelectContent>
- {kindOptions.map((option) => (
- <SelectItem key={option.value} value={option.value}>
- {option.label}
- </SelectItem>
- ))}
- </SelectContent>
- </Select>
- )}
- />
- </Field>
-
- {kind === 'percentage' ? (
- <Field>
- <FieldLabel htmlFor="value">{t('admin.fields.commission_rate.value.label')}</FieldLabel>
- <InputGroup>
- <InputGroupInput
- id="value"
- type="number"
- step="0.01"
- min="0"
- max="100"
- aria-invalid={!!errors.value || undefined}
- {...form.register('value')}
- />
- <InputGroupAddon align="inline-end">
- <InputGroupText>%</InputGroupText>
- </InputGroupAddon>
- </InputGroup>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.value.help_percentage')}
- </span>
- <FieldError errors={[errors.value]} />
- </Field>
- ) : (
- <>
- <FlatFeeAmountsField form={form} />
- <FlatFeeCapField form={form} />
- </>
- )}
-
- <CommissionRulesField form={form} />
-
- {kind === 'percentage' && <PercentageBoundsField form={form} />}
-
- <Field>
- <FieldLabel htmlFor="commission_tax_rate">
- {t('admin.fields.commission_rate.commission_tax_rate.label')}
- </FieldLabel>
- <InputGroup>
- <InputGroupInput
- id="commission_tax_rate"
- type="number"
- step="0.01"
- min="0"
- placeholder={t('admin.fields.commission_rate.commission_tax_rate.placeholder')}
- {...form.register('commission_tax_rate')}
- />
- <InputGroupAddon align="inline-end">
- <InputGroupText>%</InputGroupText>
- </InputGroupAddon>
- </InputGroup>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.commission_tax_rate.help')}
- </span>
- <FieldError errors={[errors.commission_tax_rate]} />
- </Field>
-
- {/* A parcel is part of the sale a flat fee already charges for, so the
- same amount again would bill one sale twice. A marketplace wanting a
- flat charge on delivery states it as its own rate. */}
- {kind === 'percentage' && (
- <ToggleField
- form={form}
- name="include_shipping"
- label={t('admin.fields.commission_rate.include_shipping.label')}
- help={t('admin.fields.commission_rate.include_shipping.help')}
- />
- )}
-
- <ToggleField
- form={form}
- name="tax_inclusive"
- label={t('admin.fields.commission_rate.tax_inclusive.label')}
- help={t('admin.fields.commission_rate.tax_inclusive.help')}
- />
-
- <ToggleField
- form={form}
- name="enabled"
- label={t('admin.fields.enabled.label')}
- help={t('admin.fields.commission_rate.enabled.help')}
- />
- </FieldGroup>
- )
-}
-
-function ToggleField({
- form,
- name,
- label,
- help,
-}: {
- form: UseFormReturn<CommissionRateFormValues>
- name: 'enabled' | 'tax_inclusive' | 'include_shipping'
- label: string
- help: string
-}) {
- return (
- <Field>
- <div className="flex items-start justify-between gap-4">
- <div className="flex flex-col">
- <FieldLabel htmlFor={name} className="cursor-pointer">
- {label}
- </FieldLabel>
- <span className="text-xs text-muted-foreground">{help}</span>
- </div>
- <Controller
- name={name}
- control={form.control}
- render={({ field }) => (
- <Switch id={name} checked={!!field.value} onCheckedChange={field.onChange} />
- )}
- />
- </div>
- </Field>
- )
-}
-
-/**
- * What a flat fee charges, one field per currency the store sells in.
- *
- * No currency picker: a flat fee cannot travel the way a percentage can, and
- * a marketplace selling in three currencies needs an amount in each rather
- * than one figure and a conversion nobody asked for. A currency left empty is
- * one this rate does not charge — that sale falls through to the next rate.
- */
-function FlatFeeAmountsField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
- const { t } = useTranslation()
- const { currencies } = useStore()
- const amounts = form.watch('amounts')
- const hasAmount = Object.values(amounts ?? {}).some(
- (amount) => String(amount ?? '').trim() !== '',
- )
-
- return (
- <Field>
- <FieldLabel>{t('admin.fields.commission_rate.amounts.label')}</FieldLabel>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.amounts.help')}
- </span>
- {hasAmount && (
- <Alert variant="warning" className="mt-2">
- <TriangleAlertIcon />
- <AlertDescription>
- {t('admin.commission_rates.flat_fee_exceeds_sale_warning')}
- </AlertDescription>
- </Alert>
- )}
- <div className="flex flex-col gap-2 pt-1">
- {currencies.map((currency) => (
- <div key={currency} className="flex items-center gap-2">
- <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
- <Controller
- control={form.control}
- name="amounts"
- render={({ field }) => (
- <Input
- type="number"
- step="0.01"
- min="0"
- aria-label={currency}
- value={(field.value?.[currency] as string) ?? ''}
- onChange={(event) =>
- field.onChange({ ...field.value, [currency]: event.target.value })
- }
- />
- )}
- />
- </div>
- ))}
- </div>
- </Field>
- )
-}
-
-/**
- * Optional cap on a flat fee per sale line. The engine already clamps the
- * computed fee to this ceiling — surfacing it here is what makes a minimum
- * fee larger than a cheap item's price a deliberate choice rather than a
- * silent overcharge.
- */
-function FlatFeeCapField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
- const { t } = useTranslation()
- const { currencies } = useStore()
- const amounts = form.watch('amounts')
- const cappedCurrencies = currencies.filter(
- (currency) => String(amounts?.[currency] ?? '').trim() !== '',
- )
-
- if (cappedCurrencies.length === 0) {
- return null
- }
-
- return (
- <Field>
- <FieldLabel>{t('admin.fields.commission_rate.flat_fee_cap.label')}</FieldLabel>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.flat_fee_cap.help')}
- </span>
- <div className="flex flex-col gap-2 pt-1">
- {cappedCurrencies.map((currency) => (
- <div key={currency} className="flex items-center gap-2">
- <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
- <Controller
- control={form.control}
- name="bounds"
- render={({ field }) => {
- const bound = field.value?.[currency] ?? { min_amount: '', max_amount: '' }
-
- return (
- <Input
- type="number"
- step="0.01"
- min="0"
- aria-label={`${currency} ${t('admin.fields.commission_rate.max_amount.label')}`}
- placeholder={t('admin.fields.commission_rate.max_amount.label')}
- value={bound.max_amount}
- onChange={(event) =>
- field.onChange({
- ...field.value,
- [currency]: { ...bound, max_amount: event.target.value },
- })
- }
- />
- )
- }}
- />
- </div>
- ))}
- </div>
- </Field>
- )
-}
-
-/**
- * Optional bounds on a percentage: never charge less than this, never more
- * than that. Amounts, so they carry a currency of their own — which is what
- * stops "at least 5" meaning five of whatever the buyer happened to pay in.
- */
-/**
- * A floor and a cap per currency, on the same one-row-per-currency footing as
- * the flat fee. Each bound holds only in its own currency — a sale in a
- * currency left blank is charged unbounded rather than against a converted
- * figure the merchant never agreed to.
- */
-function PercentageBoundsField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
- const { t } = useTranslation()
- const { errors } = form.formState
- const { currencies } = useStore()
-
- return (
- <Field>
- <FieldLabel>{t('admin.fields.commission_rate.bounds.label')}</FieldLabel>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.bounds.help')}
- </span>
- <div className="flex flex-col gap-2 pt-1">
- {currencies.map((currency) => (
- <div key={currency} className="flex items-center gap-2">
- <span className="w-12 shrink-0 text-sm text-muted-foreground">{currency}</span>
- <Controller
- control={form.control}
- name="bounds"
- render={({ field }) => {
- const bound = field.value?.[currency] ?? { min_amount: '', max_amount: '' }
- const write = (key: 'min_amount' | 'max_amount', amount: string) =>
- field.onChange({ ...field.value, [currency]: { ...bound, [key]: amount } })
-
- return (
- <>
- <Input
- type="number"
- step="0.01"
- min="0"
- aria-label={`${currency} ${t('admin.fields.commission_rate.min_amount.label')}`}
- placeholder={t('admin.fields.commission_rate.min_amount.label')}
- value={bound.min_amount}
- onChange={(event) => write('min_amount', event.target.value)}
- />
- <span className="text-sm text-muted-foreground">–</span>
- <Input
- type="number"
- step="0.01"
- min="0"
- aria-label={`${currency} ${t('admin.fields.commission_rate.max_amount.label')}`}
- placeholder={t('admin.fields.commission_rate.max_amount.label')}
- value={bound.max_amount}
- onChange={(event) => write('max_amount', event.target.value)}
- />
- </>
- )
- }}
- />
- </div>
- ))}
- </div>
- <FieldError errors={[errors.bounds]} />
- </Field>
- )
-}
-
-/**
- * The rate's conditions.
- *
- * Every condition has to hold for the rate to apply, and a condition naming
- * several records means any of them — so "cameras or audio, from that seller"
- * is two conditions. A rate with none charges every sale, which the empty
- * state says outright.
- *
- * Built from the rule kinds the marketplace reports rather than a list baked
- * in here, so a kind added by an extension appears without a change to this
- * file. Kinds already used drop out of the picker: a second condition of the
- * same kind would repeat the first or contradict it.
- */
-function CommissionRulesField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
- const { t } = useTranslation()
- const { data: ruleTypes } = useCommissionRuleTypes()
- const rulesArray = useFieldArray<CommissionRateFormValues, 'rules', '_key'>({
- control: form.control,
- name: 'rules',
- keyName: '_key',
- })
-
- const usedTypes = new Set(rulesArray.fields.map((rule) => rule.type))
- const availableTypes = (ruleTypes?.data ?? []).filter((type) => !usedTypes.has(type.type))
-
- return (
- <Field>
- <div className="flex items-center justify-between">
- <FieldLabel>{t('admin.fields.commission_rate.rules.label')}</FieldLabel>
- {availableTypes.length > 0 && (
- <DropdownMenu>
- <DropdownMenuTrigger
- render={
- <Button type="button" variant="outline" size="sm">
- <PlusIcon className="size-4" />
- {t('admin.commission_rates.conditions.add')}
- </Button>
- }
- />
- <DropdownMenuContent align="end">
- {availableTypes.map((type) => (
- <DropdownMenuItem
- key={type.type}
- onClick={() =>
- rulesArray.append({ type: type.type, preferences: {}, product_ids: [] })
- }
- >
- {typeLabel('commission_rule', type.type, type.name)}
- </DropdownMenuItem>
- ))}
- </DropdownMenuContent>
- </DropdownMenu>
- )}
- </div>
- <span className="text-xs text-muted-foreground">
- {t('admin.fields.commission_rate.rules.help')}
- </span>
-
- <div className="flex flex-col gap-3 pt-1">
- {rulesArray.fields.length === 0 && (
- <span className="text-xs text-muted-foreground">
- {t('admin.commission_rates.applies_to_everything')}
- </span>
- )}
-
- {rulesArray.fields.map((field, index) => (
- <CommissionRuleRow
- key={field._key}
- form={form}
- index={index}
- ruleType={(ruleTypes?.data ?? []).find((candidate) => candidate.type === field.type)}
- fallbackLabel={field.type}
- onRemove={() => rulesArray.remove(index)}
- />
- ))}
- </div>
- </Field>
- )
-}
-
-/**
- * One condition. What it renders is decided by what the server said about the
- * kind: a condition naming records gets that resource's picker, and anything
- * else renders its own preference schema — so a value band needs no code here.
- */
-function CommissionRuleRow({
- form,
- index,
- ruleType,
- fallbackLabel,
- onRemove,
-}: {
- form: UseFormReturn<CommissionRateFormValues>
- index: number
- ruleType?: CommissionRuleType
- fallbackLabel: string
- onRemove: () => void
-}) {
- const { t } = useTranslation()
- const schema = ruleType?.preference_schema ?? []
- // Catalog-scale references arrive as their own field; everything else names
- // records through an id list in preferences. Either way the picker comes
- // from the registry, keyed by rule kind.
- const picker = ruleType ? commissionRuleSubjectPicker(ruleType.type) : undefined
- const associationField = ruleType?.association_fields?.[0]
- const preferenceIdKey = schema.find((preference) => preference.key.endsWith('_ids'))?.key
-
- return (
- <div className="flex flex-col gap-2 rounded-md border p-3">
- <div className="flex items-center justify-between">
- <div className="flex flex-col">
- <span className="text-sm">
- {ruleType ? typeLabel('commission_rule', ruleType.type, ruleType.name) : fallbackLabel}
- </span>
- {ruleType && typeDescription('commission_rule', ruleType.type, ruleType.description) && (
- <span className="text-xs text-muted-foreground">
- {typeDescription('commission_rule', ruleType.type, ruleType.description)}
- </span>
- )}
- </div>
- <Button
- type="button"
- variant="ghost"
- size="icon-sm"
- onClick={onRemove}
- aria-label={t('admin.actions.delete')}
- >
- <Trash2Icon className="size-4" />
- </Button>
- </div>
-
- {picker && associationField ? (
- <Controller
- control={form.control}
- name={`rules.${index}.product_ids`}
- render={({ field }) => (
- <ResourceMultiAutocomplete
- {...picker(`commission-rule-${ruleType?.type}`)}
- value={field.value ?? []}
- onChange={field.onChange}
- />
- )}
- />
- ) : picker && preferenceIdKey ? (
- <Controller
- control={form.control}
- name={`rules.${index}.preferences`}
- render={({ field }) => (
- <ResourceMultiAutocomplete
- {...picker(`commission-rule-${ruleType?.type}`)}
- value={(field.value?.[preferenceIdKey] ?? []) as string[]}
- onChange={(ids: string[]) =>
- field.onChange({ ...field.value, [preferenceIdKey]: ids })
- }
- />
- )}
- />
- ) : (
- <Controller
- control={form.control}
- name={`rules.${index}.preferences`}
- render={({ field }) => (
- <PreferencesForm schema={schema} values={field.value} onChange={field.onChange} />
- )}
- />
- )}
- </div>
- )
-}
+ },
+ component: () => null,
+})
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails.tsx
index 375c4da759..e55fd64f8d 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails.tsx
@@ -135,8 +135,9 @@ function EmailSettingsForm({ store }: { store: Store }) {
<ResourceLayout
header={
<PageHeader
+ docsPath="settings/emails"
title={t('admin.pages.settings.emails.title')}
- subtitle={t('admin.pages.settings.emails.subtitle')}
+ description={t('admin.pages.settings.emails.subtitle')}
actions={<FormActions form={form} />}
/>
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
index 20d8abaeac..75765a7cd6 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
@@ -72,8 +72,9 @@ function IntegrationsPage() {
return (
<div className="flex flex-col gap-6">
<PageHeader
+ docsPath="settings/integrations"
title={t('admin.integrations.title')}
- subtitle={t('admin.integrations.description')}
+ description={t('admin.integrations.description')}
/>
{!isLoading && types.length === 0 && (
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/payouts.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/payouts.tsx
index 58c925bee9..96bb4b4f60 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/payouts.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/payouts.tsx
@@ -130,8 +130,9 @@ function PayoutSettingsPage({ store }: { store: Store }) {
<ResourceLayout
header={
<PageHeader
+ docsPath="sellers/payouts"
title={t('admin.pages.settings.payouts.title')}
- subtitle={t('admin.pages.settings.payouts.subtitle')}
+ description={t('admin.pages.settings.payouts.subtitle')}
actions={<FormActions form={form} />}
/>
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/reasons.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/reasons.tsx
index 77a6debd20..7b380098d5 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/reasons.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/reasons.tsx
@@ -102,7 +102,11 @@ function ReasonsPage() {
return (
<div className="flex flex-col gap-6">
- <PageHeader title={t('admin.reasons.title')} subtitle={t('admin.reasons.description')} />
+ <PageHeader
+ title={t('admin.reasons.title')}
+ description={t('admin.reasons.description')}
+ docsPath="settings/returns-configuration"
+ />
{SECTIONS.map((section) => (
<ReasonSection key={section.kind} {...section} />
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/roles.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/roles.tsx
index abd5175841..5975f23e29 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/roles.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/roles.tsx
@@ -69,8 +69,9 @@ function RolesSettingsPage() {
return (
<div className="flex flex-col gap-6">
<PageHeader
+ docsPath="settings/users"
title={t('admin.pages.roles.title')}
- subtitle={t('admin.pages.roles.subtitle')}
+ description={t('admin.pages.roles.subtitle')}
actions={
permissions.can('create', 'Spree::Role') && (
<Button onClick={() => openCreate()}>
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/staff.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/staff.tsx
index 2feac7b015..11556310d9 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/staff.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/staff.tsx
@@ -98,8 +98,9 @@ function StaffSettingsPage() {
return (
<div className="flex flex-col gap-6">
<PageHeader
+ docsPath="settings/users"
title={t('admin.pages.staff.title')}
- subtitle={t('admin.pages.staff.subtitle')}
+ description={t('admin.pages.staff.subtitle')}
actions={
<Button onClick={() => setInviteOpen(true)}>
<PlusIcon className="size-4" />
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
index 0c6f19b361..387456d4ad 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
@@ -384,8 +384,9 @@ function StoreSettingsForm({ store }: { store: Store }) {
<ResourceLayout
header={
<PageHeader
+ docsPath="settings/store-details"
title={t('admin.pages.settings.store.title')}
- subtitle={t('admin.pages.settings.store.subtitle')}
+ description={t('admin.pages.settings.store.subtitle')}
actions={<FormActions form={form} />}
/>
}
diff --git a/packages/dashboard/src/tables/allowed-origins.tsx b/packages/dashboard/src/tables/allowed-origins.tsx
index 6e14d512fc..2215f17d54 100644
--- a/packages/dashboard/src/tables/allowed-origins.tsx
+++ b/packages/dashboard/src/tables/allowed-origins.tsx
@@ -6,6 +6,8 @@ import i18n from 'i18next'
defineTable<AllowedOrigin>('allowed-origins', {
title: i18n.t('admin.allowed_origins.table_title'),
+ docsPath: 'settings/allowed-origins',
+ description: i18n.t('admin.table_descriptions.allowed_origins'),
searchParam: 'origin_cont',
searchPlaceholder: i18n.t('admin.allowed_origins.search_placeholder'),
defaultSort: { field: 'origin', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/catalogs.tsx b/packages/dashboard/src/tables/catalogs.tsx
index 28c9a07cc1..e052602668 100644
--- a/packages/dashboard/src/tables/catalogs.tsx
+++ b/packages/dashboard/src/tables/catalogs.tsx
@@ -7,7 +7,7 @@ import i18n from 'i18next'
defineTable<Catalog>('catalogs', {
title: i18n.t('admin.nav.catalogs'),
description: i18n.t('admin.table_descriptions.catalogs'),
- docsPath: 'manage-products/catalogs',
+ docsPath: 'catalogs/catalogs',
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.catalogs.search_placeholder'),
defaultSort: { field: 'position', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/channels.tsx b/packages/dashboard/src/tables/channels.tsx
index 3d810f1226..c00671aa41 100644
--- a/packages/dashboard/src/tables/channels.tsx
+++ b/packages/dashboard/src/tables/channels.tsx
@@ -6,6 +6,8 @@ import i18n from 'i18next'
defineTable<Channel>('channels', {
title: i18n.t('admin.pages.channels.title'),
+ docsPath: 'settings/sales-channels',
+ description: i18n.t('admin.table_descriptions.channels'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.common.search_placeholder'),
defaultSort: { field: 'name', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/collections.tsx b/packages/dashboard/src/tables/collections.tsx
index bc456edc05..4e43cc237c 100644
--- a/packages/dashboard/src/tables/collections.tsx
+++ b/packages/dashboard/src/tables/collections.tsx
@@ -8,7 +8,7 @@ import { sortOrderLabelKey } from '../schemas/collection'
defineTable<Collection>('collections', {
title: i18n.t('admin.collections.title'),
description: i18n.t('admin.table_descriptions.collections'),
- docsPath: 'manage-products/product-taxonomies',
+ docsPath: 'products/collections',
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.collections.search_placeholder'),
defaultSort: { field: 'position', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/commission-rates.tsx b/packages/dashboard/src/tables/commission-rates.tsx
index 30fafd87f4..5e761bb5d3 100644
--- a/packages/dashboard/src/tables/commission-rates.tsx
+++ b/packages/dashboard/src/tables/commission-rates.tsx
@@ -7,6 +7,8 @@ import { useCommissionRuleTypes } from '../hooks/use-commission-rates'
defineTable<CommissionRate>('commission-rates', {
title: i18n.t('admin.settings_nav.items.commission_rates'),
+ docsPath: 'sellers/commission-rates',
+ description: i18n.t('admin.table_descriptions.commission_rates'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.commission_rates.search_placeholder'),
// The list IS the resolution order, walked top-down, so the table has to
diff --git a/packages/dashboard/src/tables/companies.tsx b/packages/dashboard/src/tables/companies.tsx
index 6a46e5facc..46277cf8ae 100644
--- a/packages/dashboard/src/tables/companies.tsx
+++ b/packages/dashboard/src/tables/companies.tsx
@@ -6,6 +6,7 @@ import i18n from 'i18next'
import { CompanyKindBadge } from '../components/spree/company-kind-badge'
defineTable<Company>('companies', {
+ docsPath: 'customers/companies',
title: i18n.t('admin.nav.companies'),
description: i18n.t('admin.table_descriptions.companies'),
searchParam: 'name_cont',
diff --git a/packages/dashboard/src/tables/custom-field-definitions.tsx b/packages/dashboard/src/tables/custom-field-definitions.tsx
index 49e8b769fc..3b9d509c1a 100644
--- a/packages/dashboard/src/tables/custom-field-definitions.tsx
+++ b/packages/dashboard/src/tables/custom-field-definitions.tsx
@@ -13,6 +13,8 @@ const t = (key: string) => i18n.t(key)
defineTable<CustomFieldDefinition>('custom-field-definitions', {
title: t('admin.custom_field_definitions.table_title'),
+ docsPath: 'settings/metafields',
+ description: t('admin.table_descriptions.custom_field_definitions'),
searchParam: 'search',
searchPlaceholder: t('admin.custom_field_definitions.search_placeholder'),
defaultSort: { field: 'resource_type', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/customers.tsx b/packages/dashboard/src/tables/customers.tsx
index 56a1cce749..f0710ef003 100644
--- a/packages/dashboard/src/tables/customers.tsx
+++ b/packages/dashboard/src/tables/customers.tsx
@@ -9,6 +9,8 @@ import { customerDisplayName, erasedFieldValue } from '../lib/erased-customer'
defineTable('customers', {
title: i18n.t('admin.nav.customers'),
+ docsPath: 'customers/customer-profile',
+ description: i18n.t('admin.table_descriptions.customers'),
searchParam: 'search',
searchPlaceholder: i18n.t('admin.customers.table.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
diff --git a/packages/dashboard/src/tables/gift-cards.tsx b/packages/dashboard/src/tables/gift-cards.tsx
index 952628699c..2648f3051a 100644
--- a/packages/dashboard/src/tables/gift-cards.tsx
+++ b/packages/dashboard/src/tables/gift-cards.tsx
@@ -26,6 +26,8 @@ function statusLabel(value: string): string {
defineTable<GiftCard>('gift-cards', {
title: i18n.t('admin.nav.gift_cards'),
+ docsPath: 'loyalty/gift-cards',
+ description: i18n.t('admin.table_descriptions.gift_cards'),
searchParam: 'code_cont',
searchPlaceholder: i18n.t('admin.gift_cards.table.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
diff --git a/packages/dashboard/src/tables/imports.tsx b/packages/dashboard/src/tables/imports.tsx
index 611ebbe757..3c05cbc0e6 100644
--- a/packages/dashboard/src/tables/imports.tsx
+++ b/packages/dashboard/src/tables/imports.tsx
@@ -7,6 +7,8 @@ import { importTypeLabel } from '../lib/import-types'
defineTable<Import>('imports', {
title: i18n.t('admin.pages.settings.imports.title'),
+ docsPath: 'manage-products/import-products',
+ description: i18n.t('admin.table_descriptions.imports'),
searchParam: 'number_cont',
searchPlaceholder: i18n.t('admin.pages.settings.imports.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
diff --git a/packages/dashboard/src/tables/markets.tsx b/packages/dashboard/src/tables/markets.tsx
index 6b71d82d19..37d6a2ace7 100644
--- a/packages/dashboard/src/tables/markets.tsx
+++ b/packages/dashboard/src/tables/markets.tsx
@@ -6,6 +6,8 @@ import i18n from 'i18next'
defineTable<Market>('markets', {
title: i18n.t('admin.settings_nav.items.markets'),
+ docsPath: 'settings/markets',
+ description: i18n.t('admin.table_descriptions.markets'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.markets.search_placeholder'),
defaultSort: { field: 'position', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/orders.tsx b/packages/dashboard/src/tables/orders.tsx
index 3d37182705..8df9bcc0fe 100644
--- a/packages/dashboard/src/tables/orders.tsx
+++ b/packages/dashboard/src/tables/orders.tsx
@@ -20,6 +20,8 @@ function statusLabel(namespace: string, status: string): string {
defineTable('orders', {
title: i18n.t('admin.nav.orders'),
+ docsPath: 'orders/processing-orders',
+ description: i18n.t('admin.table_descriptions.orders'),
searchParam: 'multi_search',
searchPlaceholder: i18n.t('admin.orders.table.search_placeholder'),
defaultSort: { field: 'completed_at', direction: 'desc' },
@@ -89,11 +91,17 @@ defineTable('orders', {
default: true,
filterType: 'enum',
filterOptions: [
- { value: 'balance_due', label: i18n.t('admin.orders.payment_statuses.balance_due') },
- { value: 'credit_owed', label: i18n.t('admin.orders.payment_statuses.credit_owed') },
- { value: 'failed', label: i18n.t('admin.orders.payment_statuses.failed') },
+ { value: 'none', label: i18n.t('admin.orders.payment_statuses.none') },
+ { value: 'authorized', label: i18n.t('admin.orders.payment_statuses.authorized') },
+ { value: 'partially_paid', label: i18n.t('admin.orders.payment_statuses.partially_paid') },
{ value: 'paid', label: i18n.t('admin.orders.payment_statuses.paid') },
- { value: 'void', label: i18n.t('admin.orders.payment_statuses.void') },
+ {
+ value: 'partially_refunded',
+ label: i18n.t('admin.orders.payment_statuses.partially_refunded'),
+ },
+ { value: 'refunded', label: i18n.t('admin.orders.payment_statuses.refunded') },
+ { value: 'overcharged', label: i18n.t('admin.orders.payment_statuses.overcharged') },
+ { value: 'voided', label: i18n.t('admin.orders.payment_statuses.voided') },
],
quickFilter: true,
render: (order) =>
diff --git a/packages/dashboard/src/tables/payment-methods.tsx b/packages/dashboard/src/tables/payment-methods.tsx
index 86da687ded..94eaa49313 100644
--- a/packages/dashboard/src/tables/payment-methods.tsx
+++ b/packages/dashboard/src/tables/payment-methods.tsx
@@ -5,6 +5,8 @@ import { CreditCardIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<PaymentMethod>('payment-methods', {
+ docsPath: 'settings/payments',
+ description: i18n.t('admin.table_descriptions.payment_methods'),
title: i18n.t('admin.payment_methods.title'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.payment_methods.search_placeholder'),
diff --git a/packages/dashboard/src/tables/policies.tsx b/packages/dashboard/src/tables/policies.tsx
index 3b2a32ff85..5aca728281 100644
--- a/packages/dashboard/src/tables/policies.tsx
+++ b/packages/dashboard/src/tables/policies.tsx
@@ -5,6 +5,8 @@ import { ScrollTextIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<Policy>('policies', {
+ docsPath: 'settings/policies',
+ description: i18n.t('admin.table_descriptions.policies'),
title: i18n.t('admin.settings_nav.items.policies'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.policies.search_placeholder'),
diff --git a/packages/dashboard/src/tables/post-sale.tsx b/packages/dashboard/src/tables/post-sale.tsx
index 5f0045a549..9d90430157 100644
--- a/packages/dashboard/src/tables/post-sale.tsx
+++ b/packages/dashboard/src/tables/post-sale.tsx
@@ -65,6 +65,8 @@ function createdColumn<T extends { created_at: string }>() {
defineTable<Return>('returns', {
title: i18n.t('admin.nav.returns'),
+ description: i18n.t('admin.table_descriptions.returns'),
+ docsPath: 'orders/returns',
searchParam: 'number_cont',
searchPlaceholder: i18n.t('admin.post_sale.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
@@ -94,6 +96,8 @@ defineTable<Return>('returns', {
defineTable<Exchange>('exchanges', {
title: i18n.t('admin.nav.exchanges'),
+ description: i18n.t('admin.table_descriptions.exchanges'),
+ docsPath: 'orders/exchanges',
searchParam: 'number_cont',
searchPlaceholder: i18n.t('admin.post_sale.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
@@ -123,6 +127,8 @@ defineTable<Exchange>('exchanges', {
defineTable<Claim>('claims', {
title: i18n.t('admin.nav.claims'),
+ description: i18n.t('admin.table_descriptions.claims'),
+ docsPath: 'orders/claims',
searchParam: 'number_cont',
searchPlaceholder: i18n.t('admin.post_sale.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
diff --git a/packages/dashboard/src/tables/price-lists.tsx b/packages/dashboard/src/tables/price-lists.tsx
index 46594824fe..4b9951399f 100644
--- a/packages/dashboard/src/tables/price-lists.tsx
+++ b/packages/dashboard/src/tables/price-lists.tsx
@@ -8,7 +8,7 @@ import { PriceListStatusBadge } from '../components/spree/price-list-editors/sta
defineTable<PriceList>('price-lists', {
title: i18n.t('admin.nav.price_lists'),
description: i18n.t('admin.table_descriptions.price_lists'),
- docsPath: 'manage-products/price-lists',
+ docsPath: 'pricing/price-lists',
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.common.search_placeholder'),
defaultSort: { field: 'position', direction: 'asc' },
diff --git a/packages/dashboard/src/tables/product-types.tsx b/packages/dashboard/src/tables/product-types.tsx
index 54e8fda043..7d97ea8ba7 100644
--- a/packages/dashboard/src/tables/product-types.tsx
+++ b/packages/dashboard/src/tables/product-types.tsx
@@ -5,6 +5,7 @@ import { ShapesIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<ProductType>('product-types', {
+ docsPath: 'settings/product-types',
title: i18n.t('admin.settings_nav.items.product_types'),
description: i18n.t('admin.table_descriptions.product_types'),
searchParam: 'name_cont',
diff --git a/packages/dashboard/src/tables/products.tsx b/packages/dashboard/src/tables/products.tsx
index e448e84e7f..4233ab369e 100644
--- a/packages/dashboard/src/tables/products.tsx
+++ b/packages/dashboard/src/tables/products.tsx
@@ -10,6 +10,8 @@ import { productTypeAutocompleteProps } from '../hooks/use-product-types'
import { sellerAutocompleteProps } from '../hooks/use-sellers'
defineTable('products', {
+ docsPath: 'products/creating-products',
+ description: i18n.t('admin.table_descriptions.products'),
title: i18n.t('admin.nav.products'),
searchParam: 'multi_search',
searchPlaceholder: i18n.t('admin.common.search_placeholder'),
diff --git a/packages/dashboard/src/tables/promotions.tsx b/packages/dashboard/src/tables/promotions.tsx
index d424a5e4ad..2819772161 100644
--- a/packages/dashboard/src/tables/promotions.tsx
+++ b/packages/dashboard/src/tables/promotions.tsx
@@ -5,6 +5,8 @@ import { TagIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<Promotion>('promotions', {
+ docsPath: 'promotions/create-a-promotion',
+ description: i18n.t('admin.table_descriptions.promotions'),
title: i18n.t('admin.nav.promotions'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.promotions.table.search_placeholder'),
diff --git a/packages/dashboard/src/tables/purchase-orders.tsx b/packages/dashboard/src/tables/purchase-orders.tsx
index 888c447276..37eafb2206 100644
--- a/packages/dashboard/src/tables/purchase-orders.tsx
+++ b/packages/dashboard/src/tables/purchase-orders.tsx
@@ -17,6 +17,7 @@ function statusLabel(value: string): string {
}
defineTable<PurchaseOrder>('purchase-orders', {
+ docsPath: 'inventory/purchase-orders',
title: i18n.t('admin.purchase_orders.title'),
description: i18n.t('admin.table_descriptions.purchase_orders'),
searchParam: 'number_or_reference_cont',
diff --git a/packages/dashboard/src/tables/saved-reports.tsx b/packages/dashboard/src/tables/saved-reports.tsx
index 869b96ca06..32f081c7f3 100644
--- a/packages/dashboard/src/tables/saved-reports.tsx
+++ b/packages/dashboard/src/tables/saved-reports.tsx
@@ -6,6 +6,7 @@ import { Link } from '@tanstack/react-router'
import i18n from 'i18next'
defineTable<SavedReport>('saved-reports', {
+ docsPath: 'reports/reports',
title: i18n.t('admin.reports.title'),
description: i18n.t('admin.reports.subtitle'),
searchParam: 'name_cont',
diff --git a/packages/dashboard/src/tables/seller-ledger.tsx b/packages/dashboard/src/tables/seller-ledger.tsx
index 22584bccab..020a6fce71 100644
--- a/packages/dashboard/src/tables/seller-ledger.tsx
+++ b/packages/dashboard/src/tables/seller-ledger.tsx
@@ -30,6 +30,7 @@ function statusOptions() {
}
defineTable<SellerTransfer>('seller-transfers', {
+ docsPath: 'sellers/payouts',
title: i18n.t('admin.nav.seller_transfers'),
description: i18n.t('admin.payouts.transfers_description'),
// The provider's own id for the movement. Without a searchParam the toolbar
diff --git a/packages/dashboard/src/tables/seller-requirements.tsx b/packages/dashboard/src/tables/seller-requirements.tsx
index f6e0d467ff..4707be2d1d 100644
--- a/packages/dashboard/src/tables/seller-requirements.tsx
+++ b/packages/dashboard/src/tables/seller-requirements.tsx
@@ -6,6 +6,8 @@ import i18n from 'i18next'
import { useSellerRequirementTypes } from '../hooks/use-seller-requirements'
defineTable<SellerRequirement>('seller-requirements', {
+ docsPath: 'sellers/onboarding',
+ description: i18n.t('admin.table_descriptions.seller_requirements'),
title: i18n.t('admin.seller_requirements.title'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.seller_requirements.search_placeholder'),
diff --git a/packages/dashboard/src/tables/sellers.tsx b/packages/dashboard/src/tables/sellers.tsx
index 12b076edd4..5773c7c06e 100644
--- a/packages/dashboard/src/tables/sellers.tsx
+++ b/packages/dashboard/src/tables/sellers.tsx
@@ -7,6 +7,8 @@ import i18n from 'i18next'
import { SELLER_STATUSES } from '../schemas/seller'
defineTable<Seller>('sellers', {
+ docsPath: 'sellers/managing-sellers',
+ description: i18n.t('admin.table_descriptions.sellers'),
title: i18n.t('admin.nav.sellers'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.sellers.search_placeholder'),
diff --git a/packages/dashboard/src/tables/stock-levels.tsx b/packages/dashboard/src/tables/stock-levels.tsx
index 00a1ef82b4..f8be97424d 100644
--- a/packages/dashboard/src/tables/stock-levels.tsx
+++ b/packages/dashboard/src/tables/stock-levels.tsx
@@ -27,7 +27,7 @@ function ProductLabel({ level }: { level: StockLevel }) {
defineTable<StockLevel>('stock-levels', {
title: i18n.t('admin.stock_levels.title'),
description: i18n.t('admin.table_descriptions.stock_levels'),
- docsPath: 'manage-products/stock-levels',
+ docsPath: 'inventory/stock-levels',
searchParam: 'variant_sku_or_variant_product_name_cont',
searchPlaceholder: i18n.t('admin.stock_levels.table.search_placeholder'),
// A shelf list has to hold still. Without this the table falls back to
diff --git a/packages/dashboard/src/tables/stock-transfers.tsx b/packages/dashboard/src/tables/stock-transfers.tsx
index b0e698eeae..5ea6928fd0 100644
--- a/packages/dashboard/src/tables/stock-transfers.tsx
+++ b/packages/dashboard/src/tables/stock-transfers.tsx
@@ -12,7 +12,7 @@ function statusLabel(value: string): string {
defineTable<StockTransfer>('stock-transfers', {
title: i18n.t('admin.stock_transfers.title'),
description: i18n.t('admin.table_descriptions.stock_transfers'),
- docsPath: 'manage-products/stock-transfers',
+ docsPath: 'inventory/stock-transfers',
searchParam: 'number_or_reference_cont',
searchPlaceholder: i18n.t('admin.stock_transfers.table.search_placeholder'),
defaultSort: { field: 'created_at', direction: 'desc' },
diff --git a/packages/dashboard/src/tables/store-credits.tsx b/packages/dashboard/src/tables/store-credits.tsx
index b845f31a23..91f6e15ce3 100644
--- a/packages/dashboard/src/tables/store-credits.tsx
+++ b/packages/dashboard/src/tables/store-credits.tsx
@@ -24,6 +24,8 @@ const ORIGIN_OPTIONS = [
]
defineTable<StoreCredit>('store-credits', {
+ docsPath: 'loyalty/store-credits',
+ description: i18n.t('admin.table_descriptions.store_credits'),
title: i18n.t('admin.nav.store_credits'),
searchParam: 'memo_cont',
searchPlaceholder: i18n.t('admin.store_credits.table.search_placeholder'),
diff --git a/packages/dashboard/src/tables/suppliers.tsx b/packages/dashboard/src/tables/suppliers.tsx
index a93f1d0624..15e0b9f7fe 100644
--- a/packages/dashboard/src/tables/suppliers.tsx
+++ b/packages/dashboard/src/tables/suppliers.tsx
@@ -5,6 +5,7 @@ import { Building2Icon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<Supplier>('suppliers', {
+ docsPath: 'inventory/suppliers',
title: i18n.t('admin.suppliers.title'),
description: i18n.t('admin.table_descriptions.suppliers'),
searchParam: 'name_or_contact_name_or_email_cont',
diff --git a/packages/dashboard/src/tables/tax-categories.tsx b/packages/dashboard/src/tables/tax-categories.tsx
index ca1ad96077..23a7a0da8b 100644
--- a/packages/dashboard/src/tables/tax-categories.tsx
+++ b/packages/dashboard/src/tables/tax-categories.tsx
@@ -5,6 +5,8 @@ import { PercentIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
defineTable<TaxCategory>('tax-categories', {
+ docsPath: 'settings/tax',
+ description: i18n.t('admin.table_descriptions.tax_categories'),
title: i18n.t('admin.settings_nav.items.tax_categories'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.tax_categories.search_placeholder'),
diff --git a/packages/dashboard/src/tables/tax-rates.tsx b/packages/dashboard/src/tables/tax-rates.tsx
index f666fcd924..79e89768c1 100644
--- a/packages/dashboard/src/tables/tax-rates.tsx
+++ b/packages/dashboard/src/tables/tax-rates.tsx
@@ -7,6 +7,8 @@ import { JurisdictionLabel } from '../components/spree/jurisdiction-label'
import { TaxCategoryLabel } from '../components/spree/tax-category-label'
defineTable<TaxRate>('tax-rates', {
+ docsPath: 'settings/tax',
+ description: i18n.t('admin.table_descriptions.tax_rates'),
title: i18n.t('admin.settings_nav.items.tax_rates'),
searchParam: 'name_cont',
searchPlaceholder: i18n.t('admin.tax_rates.search_placeholder'),
diff --git a/packages/dashboard/src/tables/webhook-deliveries.tsx b/packages/dashboard/src/tables/webhook-deliveries.tsx
index 32bd4ccf08..3038b9502e 100644
--- a/packages/dashboard/src/tables/webhook-deliveries.tsx
+++ b/packages/dashboard/src/tables/webhook-deliveries.tsx
@@ -14,6 +14,8 @@ const STATUS_OPTIONS = [
] as const
defineTable<WebhookDelivery>('webhook-deliveries', {
+ docsPath: 'settings/webhooks',
+ description: i18n.t('admin.table_descriptions.webhook_deliveries'),
title: i18n.t('admin.pages.settings.webhooks.deliveries_sheet_title'),
searchParam: 'event_name_cont',
searchPlaceholder: i18n.t('admin.pages.settings.webhooks.deliveries.search_placeholder'),
diff --git a/packages/dashboard/src/tables/webhook-endpoints.tsx b/packages/dashboard/src/tables/webhook-endpoints.tsx
index dfd5e84f63..6e6479ce84 100644
--- a/packages/dashboard/src/tables/webhook-endpoints.tsx
+++ b/packages/dashboard/src/tables/webhook-endpoints.tsx
@@ -13,6 +13,8 @@ import i18n from 'i18next'
import { webhookEndpointHealth, webhookHealthBadgeVariant } from '../lib/webhook-health'
defineTable<WebhookEndpoint>('webhook-endpoints', {
+ docsPath: 'settings/webhooks',
+ description: i18n.t('admin.table_descriptions.webhook_endpoints'),
title: i18n.t('admin.pages.settings.webhooks.title'),
searchParam: 'url_cont',
searchPlaceholder: i18n.t('admin.pages.settings.webhooks.search_placeholder'),