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.

Document how a seller gets a product on sale

Damian Legawiecbc2026200a2e
diff --git a/.claude/commands/schema-review.md b/.claude/commands/schema-review.md
new file mode 100644
index 0000000000..7832346da8
--- /dev/null
+++ b/.claude/commands/schema-review.md
@@ -0,0 +1,99 @@
+Review a change's database impact and publish it as a visual artifact.
+
+Target: $ARGUMENTS (a PR number, a branch, a commit range, or empty for the current branch against `main`)
+
+The output is a published Artifact the reviewer can open — an ERD showing what
+this change adds to the database, plus the lifecycle and permission surface
+around it. It exists so a reviewer can see the shape of a schema change before
+reading the diff.
+
+## 1. Establish the range
+
+- A bare number is a PR: `gh pr view <n> --json headRefName,baseRefName`.
+- A branch or range is used as given.
+- Empty means `origin/main...HEAD`.
+
+Fetch first so the base is current.
+
+## 2. Gather facts — never from memory
+
+Every figure on the page must come from a command you ran in this session. The
+whole value of the artifact is that it is trustworthy at a glance, so a number
+you assumed is worse than a number you left out.
+
+```bash
+# New tables
+git diff <range> --name-only --diff-filter=A | grep db/migrate
+
+# Changed tables — only migrations that ALTER what already exists.
+# Excludes the create_* files found above, whose add_index lines would
+# otherwise read as a change to an existing table.
+git diff <range> -- '*/db/migrate/*' ':!*create_*' \
+ | grep -E "^\+.*(add_column|add_reference|remove_column|rename_column)"
+
+# New models, workflows, services, serializers
+git diff <range> --name-only --diff-filter=A | grep -E "app/(models|workflows|services|serializers)/"
+```
+
+Then read each new migration in full for the exact columns, types, null
+constraints and indexes. Read each new model for `has_status`, `has_prefix_id`,
+`belongs_to`, and any `dependent:`.
+
+**State "no change" explicitly when that is the answer.** "No existing table
+gained a column" is one of the most useful things the page can say, and it only
+carries weight if you checked.
+
+Verify anything you are unsure of against the running app rather than guessing:
+
+```bash
+cd server && bin/rails runner 'puts Spree::Thing.column_names.inspect'
+```
+
+Watch for claims that read as true but are not: a model whose comments mention
+another entity does not reference it. Grep for the association, not the word.
+
+## 3. Decide what belongs on the page
+
+Include, in this order, and only the ones that apply:
+
+- **Counts** — new tables, columns, foreign keys, and explicitly `0` where
+ nothing changed.
+- **ERD** — the new table(s) drawn solid; the existing tables they reference
+ drawn as outlines. That contrast is what makes "what's new" readable before
+ any words are.
+- **Lifecycle** — if the new table has a `status`, one row per value: the
+ status, the workflow that writes it, and what it means. Never a state-machine
+ graph; Spree has no state machines.
+- **Vocabulary changes** — statuses added to an existing model via
+ `add_status`, which are a code change rather than a migration and so are
+ invisible in the schema.
+- **Permission catalog** — resources registered or split, and who can reach
+ them.
+- **Derived columns** — anything deliberately *not* stored (a store derived
+ through a parent, say) is worth showing as such; its absence is a design
+ decision a reviewer should see.
+
+Leave out anything you could not verify.
+
+## 4. Build and publish
+
+Load the `artifact-design` skill before writing the file, and follow it.
+
+Design notes specific to this kind of page:
+
+- It is a technical document read by engineers, not a marketing page. Utilitarian
+ treatment, real typographic hierarchy, no hero.
+- Column names, types and event names are the content — set them in a monospace
+ face, and let that carry the character.
+- Spend colour on one thing: the new table and its foreign keys. Everything
+ existing stays neutral. Semantic colour is for statuses only.
+- Use `font-variant-numeric: tabular-nums` wherever counts line up.
+- Both themes, per the skill. Wide tables get their own `overflow-x: auto`.
+
+Write the file to the scratchpad directory, then publish with `Artifact`. Title
+it for the subject — the feature the schema serves, not "Schema Changes".
+
+## 5. Report
+
+Give the user the URL, then the same facts in prose: what was added, what was
+deliberately not added, and anything you could not verify and left off.
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 5009ac55ee..85d43f235f 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -66,7 +66,7 @@ erDiagram
| `name` | Product name | Yes |
| `description` | Full product description | Yes |
| `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
-| `status` | `draft`, `active`, or `archived` | No |
+| `status` | `draft`, `active`, or `archived`. A marketplace adds `proposed` and `rejected` — see Seller submissions below | No |
| `available_on` | Date the product becomes available for sale | No |
| `discontinue_on` | Date the product is no longer available | No |
| `meta_title` | Custom SEO title | Yes |
@@ -233,6 +233,154 @@ spree api delete /products/prod_xxx
Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](/api-reference/admin-api/endpoints).
</Tip>
+## Seller submissions <Since version="6.0" />
+
+On a marketplace, a seller lists a product but does not publish one. They submit it, and the marketplace decides. This adds two statuses to the three above — both hidden from the storefront, since only `active` is visible.
+
+<Info>
+This applies to products that belong to a seller. A marketplace's own catalog is unaffected: an operator publishing their own product sets `status` directly and answers to nobody.
+</Info>
+
+### The lifecycle
+
+```mermaid
+stateDiagram-v2
+ [*] --> draft
+ draft --> proposed : seller submits
+ proposed --> active : operator approves
+ proposed --> rejected : operator sends back
+ rejected --> proposed : seller revises and resubmits
+ proposed --> draft : seller withdraws
+ proposed --> archived : seller withdraws
+ active --> draft : seller takes it down
+ active --> archived : seller withdraws it
+```
+
+Withdrawing a submission before anyone has ruled on it closes the open row as `withdrawn`, so a `pending` row always means the marketplace still owes an answer. A product that was already rejected keeps that decision at the head of its trail instead.
+
+| Status | Meaning | Storefront |
+|---|---|:---:|
+| `draft` | The seller is still working on it | Hidden |
+| `proposed` | Submitted, waiting on the marketplace | Hidden |
+| `rejected` | Sent back with a reason, awaiting changes | Hidden |
+| `active` | Approved and on sale | **Visible** |
+| `archived` | Withdrawn | Hidden |
+
+A seller can always take their own listing down — that is not a review decision. Putting one up is.
+
+### The submission record
+
+Each submission and each decision on it is a `Spree::ProductSubmission` row. The product's `status` stays the operational truth; these rows are how it got there.
+
+```mermaid
+erDiagram
+ Product ||--o{ ProductSubmission : "has many"
+ AdminUser ||--o{ ProductSubmission : "submitted"
+ AdminUser ||--o{ ProductSubmission : "reviewed"
+
+ ProductSubmission {
+ string status
+ bigint product_id
+ bigint submitted_by_id
+ bigint reviewed_by_id
+ datetime reviewed_at
+ text review_note
+ json metadata
+ }
+```
+
+| Column | Description |
+|---|---|
+| `status` | `pending`, `approved`, `rejected`, or `withdrawn` |
+| `submitted_by_id` | The seller's staff member who asked |
+| `reviewed_by_id` | The marketplace's staff member who decided |
+| `reviewed_at` | When the decision was made |
+| `review_note` | Why it was sent back — this is what the seller reads |
+
+Rows accumulate rather than overwrite, so a seller sent back three times leaves three rows. The latest row for a product is the live one; the ones before it are the trail.
+
+<Warning>
+Never store a rejection reason on the product itself. A seller can write their own product's `metadata`, so a note kept there is erased the next time they save.
+</Warning>
+
+An approval with no `reviewed_by_id` and `metadata.auto_approved` set means the store approves listings automatically — never a decision whose author was lost. Turn that on with the `auto_approve_seller_products` store preference.
+
+### Submitting, as a seller
+
+Status is not writable on the seller branch. A seller moves a product with an explicit action:
+
+<CodeGroup>
+
+```typescript Seller SDK
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://marketplace.example.com',
+ sellerId: 'sel_xxx',
+})
+
+await client.products.submit('prod_xxx') // draft or rejected → proposed
+await client.products.draft('prod_xxx') // take it back down
+await client.products.archive('prod_xxx') // withdraw it
+
+// Why it was sent back
+const product = await client.products.get('prod_xxx', 'submission')
+product.submission?.review_note
+```
+
+```bash CLI
+spree api patch /seller/products/prod_xxx/submit
+spree api patch /seller/products/prod_xxx/draft
+spree api patch /seller/products/prod_xxx/archive
+```
+
+</CodeGroup>
+
+### Deciding, as the marketplace
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.products.approve('prod_xxx')
+await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })
+
+// The review queue
+const pending = await client.products.list({ filter: { status_eq: 'proposed' } })
+
+// Who decided, and when
+const product = await client.products.get('prod_xxx', { expand: ['submission'] })
+product.submission?.reviewed_by_name
+```
+
+```bash CLI
+spree api patch /products/prod_xxx/approve
+spree api patch /products/prod_xxx/reject -d '{"reason": "Please add a photo showing scale."}'
+```
+
+</CodeGroup>
+
+<Note>
+The seller sees the note and when the decision was made, but never who made it.
+</Note>
+
+### Leaving review is a decision
+
+A product in `proposed` or `rejected` cannot have its status changed by an ordinary update — that would put it on sale with nobody's name against it. The refusal lives in the product update workflow, so every caller inherits it, and bulk status updates skip those products and report how many they left behind.
+
+### Events
+
+Each transition publishes an event you can subscribe to:
+
+| Event | Published when |
+|---|---|
+| `product.proposed` | A seller submits for review |
+| `product.approved` | The marketplace accepts it |
+| `product.rejected` | The marketplace sends it back |
+| `product.drafted` | A seller takes a listing down |
+| `product.archived` | A seller withdraws it |
+
+The submission row itself also publishes `product_submission.created` and `product_submission.updated`, carrying the status, the note and the product. See [Events](/developer/core-concepts/events).
+
## Product Filters
Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts: