Overview
A marketplace sells things it doesn’t own. Vendors list their own products, the marketplace takes a cut, and a shopper buying from three vendors at once expects one basket and one payment — not three checkouts. A seller is a vendor on your marketplace: their own products, their own staff, their own orders, and their own panel to work in.This is all open source. Sellers, product review, order splitting, commissions and the seller panel ship in the box — you don’t need a commercial licence to run a marketplace on Spree.
The seller lifecycle
A seller isn’t simply created and switched on. Bringing a vendor onto a marketplace is a process with a decision at the end of it, and the status reflects where they are in it.
Only an approved seller can sell, and even then not while they’re on holiday — sellers can pause their own listings without the marketplace suspending them.
What a seller owns
A seller is a tenant inside the marketplace: their own catalogue, their own stock, their own shipping setup and their own money trail. Delivery profiles and zones stay with the operator — a seller picks from them rather than defining them. A seller’s delivery methods are their own — internal rates and manual fulfillment, since carrier accounts stay with the operator. Their package types sit alongside the marketplace’s shared ones, so they can pack into the operator’s standard cartons or record their own.Onboarding requirements
What a vendor 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 configured, not hardcoded. Each store defines its own:
Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, a way to ship, the box they ship in, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.
A seller sees their checklist and its progress:
The checklist is enforced at exactly two moments — submitting for review, and approval. Approval refuses while a required item is outstanding, unless an operator deliberately overrides it.Afterwards it’s advisory. If a seller’s insurance certificate lapses, that’s flagged for the marketplace to act on; it does not silently stop their sales mid-trade.
Products belong to sellers
A product can name a seller. No seller means it’s the marketplace’s own stock — a marketplace that also sells directly is a normal setup. Sellers don’t publish; they submit, and the marketplace decides. That review flow, and the statuses behind it, are covered in Products.One checkout, several sellers
This is the part that makes a marketplace different from a shop, and it’s worth understanding before you build a storefront against it. A customer fills one basket, enters one address, and pays once. But each seller needs their own order — they fulfil separately, get paid separately, and must never see each other’s business. So at completion, a checkout spanning several sellers becomes an order group: one container holding one order per seller.
The single payment is apportioned across the child orders as payment splits, so each seller’s share of one charge is recorded exactly — which is what makes per-seller refunds and settlement possible later.
Two details worth knowing:
- Group totals are added up, not divided. The group’s total is the sum of its children, so it always agrees with them.
- Delivery and order-level fees are shared out by item value, so a seller whose goods made up most of the basket carries most of the delivery charge.
Commission
Commission is what the marketplace charges for the sale — configured as rates, and recorded per sale as immutable commission lines.- Rates are tried in list order, and the first whose rules match wins. A rate with no rules matches everything, so the marketplace default belongs at the bottom.
- Commission is charged on the seller’s net revenue by default, after discounts and excluding the customer’s tax.
- Commission tax follows the seller’s jurisdiction, not the shopper’s — the marketplace is selling a service to the vendor, which is a separate supply from the vendor’s sale to the customer.
Payouts
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.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. Whenorder.fulfilled fires, a Spree::SellerTransfer of kind earning is written for the seller’s sale less commission, 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 oneSpree::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”:
A seller on the
manual interval is skipped by the sweep and settled by hand instead:
201 with the payouts it created, one per currency. When one
currency settles and another is refused it still answers 201, listing what
failed under meta.failures — so check that rather than assuming success. With
nothing to settle it answers 422.
Reading the ledger
Across every seller, from the marketplace side:Admin SDK
Seller SDK
Payout providers
A provider is a stateless class registered inSpree.payout_providers and chosen per store with the payout_provider preference. Core ships one:
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 drives. A seller gets a fresh link from POST /seller/onboarding/payout_account, and GET /admin/payout_providers lists what is registered, for a picker.
A connected provider confirms settlements through POST /api/v3/webhooks/payouts/:payment_method_id — separate from the payment webhook, because providers scope seller-account events to their own subscription and signing secret. To pay sellers through rails of your own, see Seller payouts.
See Stripe Connect for marketplaces for the shipped provider.
Refund clawbacks and netting across settlements, reconciliation, KYC operations and seller tax reporting (DAC7) are Spree Enterprise.
The seller panel
Sellers get their own application — not access to the marketplace’s dashboard. It’s a separate API with its own sign-in, and every request is scoped to the seller making it, so no endpoint even takes a seller ID. That last point is the security property worth relying on: a seller cannot ask for another seller’s data, because there’s nowhere in the request to name one.Related
- Commissions — rates, rules, and what the marketplace charges
- Products — the listing review flow
- Orders — orders and their statuses
- Delivery setup — how a seller’s goods ship, and what they ship in
- Staff & Roles — how seller teams are governed
- Seller API — the full endpoint reference