@spree/docs 0.1.181 → 0.1.182

package/dist/api-reference/seller-api/errors.md

@@ -90,7 +90,7 @@ This is deliberate. Answering `403` for another seller's product would confirm t
 | `record_not_found` | 404 | The record does not belong to the acting seller |
 | `validation_error` | 422 | Model validation failed; see `details` |
 | `processing_error` | 422 | A workflow refused — for example, submitting for review with requirements outstanding |
-| `parameter_missing` | 400 | A required parameter was absent |
+| `parameter_missing` | 422 | A required parameter was absent — accepting an invitation without a password, for example |
 | `rate_limit_exceeded` | 429 | Too many requests to an auth endpoint |
 
 ## Handling errors with the SDK

package/dist/api-reference/store.yaml

@@ -876,8 +876,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 1576979
-                  slug: product-1576979
+                  name: Product 1646979
+                  slug: product-1646979
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1051,8 +1051,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 2039085
-                  slug: product-2039085
+                  name: Product 2109085
+                  slug: product-2109085
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1083,8 +1083,8 @@ paths:
                   original_price:
                   seller_id:
                 - id: prod_gbHJdmfrXB
-                  name: Product 2048209
-                  slug: product-2048209
+                  name: Product 2118209
+                  slug: product-2118209
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1212,8 +1212,8 @@ paths:
             application/json:
               example:
                 id: prod_UkLWZg9DAJ
-                name: Product 2316885
-                slug: product-2316885
+                name: Product 2386885
+                slug: product-2386885
                 meta_title:
                 meta_description:
                 meta_keywords:
@@ -1564,8 +1564,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 131715
-                    slug: product-131715
+                    name: Product 138715
+                    slug: product-138715
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -1675,8 +1675,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1322171
-                    slug: product-1322171
+                    name: Product 1392171
+                    slug: product-1392171
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -1972,7 +1972,7 @@ paths:
                 total_quantity: 0
                 warnings:
                 - code: line_item_removed
-                  message: Product 136307 was removed because it was sold out
+                  message: Product 143307 was removed because it was sold out
                   line_item_id: li_UkLWZg9DAJ
                   variant_id: variant_UkLWZg9DAJ
                 coupon_code:
@@ -2182,8 +2182,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1373263
-                  slug: product-1373263
+                  name: Product 1443263
+                  slug: product-1443263
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2460,8 +2460,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1398992
-                  slug: product-1398992
+                  name: Product 1468992
+                  slug: product-1468992
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2492,7 +2492,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 136 Lovely Street
+                  address1: 150 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2514,7 +2514,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 135 Lovely Street
+                  address1: 149 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2668,8 +2668,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1424794
-                  slug: product-1424794
+                  name: Product 1494794
+                  slug: product-1494794
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2803,7 +2803,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 142 Lovely Street
+                  address1: 156 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2825,7 +2825,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 141 Lovely Street
+                  address1: 155 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -3001,8 +3001,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1694241
-                  slug: product-1694241
+                  name: Product 1764241
+                  slug: product-1764241
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3192,8 +3192,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1713461
-                  slug: product-1713461
+                  name: Product 1783461
+                  slug: product-1783461
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3371,8 +3371,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1738182
-                  slug: product-1738182
+                  name: Product 1808182
+                  slug: product-1808182
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3482,7 +3482,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 226 Lovely Street
+                  address1: 240 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -3660,8 +3660,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1755702
-                  slug: product-1755702
+                  name: Product 1825702
+                  slug: product-1825702
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3906,8 +3906,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1799569
-                  slug: product-1799569
+                  name: Product 1869569
+                  slug: product-1869569
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4056,10 +4056,10 @@ paths:
                 total_quantity: 2
                 warnings:
                 - code: delivery_unavailable
-                  message: Product 18263 cannot be delivered to the selected address
+                  message: Product 18963 cannot be delivered to the selected address
                   line_item_id: li_UkLWZg9DAJ
                 - code: delivery_unavailable
-                  message: Product 183298 cannot be delivered to the selected address
+                  message: Product 190298 cannot be delivered to the selected address
                   line_item_id: li_gbHJdmfrXB
                 coupon_code:
                 item_total: '29.99'
@@ -4113,8 +4113,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 18263
-                  slug: product-18263
+                  name: Product 18963
+                  slug: product-18963
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4144,8 +4144,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 183298
-                  slug: product-183298
+                  name: Product 190298
+                  slug: product-190298
                   options_text: ''
                   price: '19.99'
                   display_price: "$19.99"
@@ -4366,8 +4366,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1899165
-                  slug: product-1899165
+                  name: Product 1969165
+                  slug: product-1969165
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5180,8 +5180,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2519789
-                  slug: product-2519789
+                  name: Product 2589789
+                  slug: product-2589789
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5390,8 +5390,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 253179
-                  slug: product-253179
+                  name: Product 260179
+                  slug: product-260179
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5557,8 +5557,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 193496
-                  slug: product-193496
+                  name: Product 200496
+                  slug: product-200496
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5667,7 +5667,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 282 Lovely Street
+                  address1: 296 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5689,7 +5689,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 283 Lovely Street
+                  address1: 297 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5795,7 +5795,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 100 Lovely Street
+                  address1: 114 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5816,7 +5816,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 101 Lovely Street
+                  address1: 115 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5837,7 +5837,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 102 Lovely Street
+                  address1: 116 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -6095,7 +6095,7 @@ paths:
                 first_name: John
                 last_name: Doe
                 full_name: John Doe
-                address1: 114 Lovely Street
+                address1: 128 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: New York
@@ -6177,7 +6177,7 @@ paths:
                 first_name: John
                 last_name: Doe
                 full_name: John Doe
-                address1: 120 Lovely Street
+                address1: 134 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: Los Angeles
@@ -6667,8 +6667,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1595270
-                    slug: product-1595270
+                    name: Product 1665270
+                    slug: product-1665270
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -6777,7 +6777,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 186 Lovely Street
+                    address1: 200 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -6799,7 +6799,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 187 Lovely Street
+                    address1: 201 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -6975,8 +6975,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1615633
-                  slug: product-1615633
+                  name: Product 1685633
+                  slug: product-1685633
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -7085,7 +7085,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 192 Lovely Street
+                  address1: 206 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7107,7 +7107,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 193 Lovely Street
+                  address1: 207 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7326,7 +7326,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 198 Lovely Street
+                  address1: 212 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7347,7 +7347,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 199 Lovely Street
+                  address1: 213 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7369,7 +7369,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 199 Lovely Street
+                  address1: 213 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7391,7 +7391,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 198 Lovely Street
+                  address1: 212 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7482,7 +7482,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 200 Lovely Street
+                  address1: 214 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7503,7 +7503,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 201 Lovely Street
+                  address1: 215 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7525,7 +7525,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 201 Lovely Street
+                  address1: 215 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7547,7 +7547,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 200 Lovely Street
+                  address1: 214 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -9343,7 +9343,7 @@ paths:
                 variant:
                   id: variant_gbHJdmfrXB
                   product_id: prod_gbHJdmfrXB
-                  sku: SKU-307
+                  sku: SKU-314
                   options_text: ''
                   track_inventory: true
                   media_count: 0
@@ -10304,7 +10304,7 @@ paths:
                   first_name:
                   last_name:
                   full_name: ''
-                  address1: 159 Lovely Street
+                  address1: 173 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -10375,7 +10375,7 @@ paths:
                 first_name:
                 last_name:
                 full_name: ''
-                address1: 162 Lovely Street
+                address1: 176 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: New York
@@ -10549,8 +10549,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1585649
-                    slug: product-1585649
+                    name: Product 1655649
+                    slug: product-1655649
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -10659,7 +10659,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 170 Lovely Street
+                    address1: 184 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -10681,7 +10681,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 171 Lovely Street
+                    address1: 185 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -11262,19 +11262,6 @@ components:
       - actions
       - subjects
       - has_conditions
-    MeResponse:
-      type: object
-      description: Current admin user profile and serialized permissions
-      properties:
-        user:
-          "$ref": "#/components/schemas/AdminUser"
-        permissions:
-          type: array
-          items:
-            "$ref": "#/components/schemas/PermissionRule"
-      required:
-      - user
-      - permissions
     ImportSchemaField:
       type: object
       description: A canonical column of an import type, including per-store custom

package/dist/developer/core-concepts/products.md

@@ -64,7 +64,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 |
@@ -221,6 +221,144 @@ spree api delete /products/prod_xxx
 
 > **TIP:** 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.md).
 
+## Seller submissions 
+
+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.
+
+### 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.
+
+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:
+
+
+```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
+```
+
+
+### Deciding, as the marketplace
+
+
+```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."}'
+```
+
+
+> **NOTE:** The seller sees the note and when the decision was made, but never who made it.
+
+### 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](events.md).
+
 ## Product Filters
 
 Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.181",
+  "version": "0.1.182",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",