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.

Let sellers submit products instead of publishing them

Damian Legawieced53e4852874
diff --git a/docs/plans/6.0-seller-product-submission.md b/docs/plans/6.0-seller-product-submission.md
new file mode 100644
index 0000000000..729af82e42
--- /dev/null
+++ b/docs/plans/6.0-seller-product-submission.md
@@ -0,0 +1,212 @@
+# Seller Product Submission and Review
+
+**Status:** Design Finalized
+**Target:** Spree 6.0
+**Depends on:** `6.0-multi-vendor-marketplace.md`, `6.0-seller-onboarding-requirements.md`, `6.0-admin-rbac.md`, `6.0-product-types.md`
+**Author:** Damian Legawiec
+**Last updated:** 2026-08-26
+
+## Summary
+
+A seller can list a product but must not publish one. Today they can: the
+seller products endpoint permits `status` as a plain attribute, so a seller
+sends `status: 'active'` and their product is live in the marketplace catalog
+with nobody having looked at it. This plan closes that by giving products a
+review lifecycle — the seller submits, the operator decides — and by splitting
+the two capabilities that currently ride the `products` permission key and
+should not: managing product types, and publishing to sales channels.
+
+It also gives the seller panel the same product form the operator's dashboard
+has, rather than the four-field placeholder it ships today. The form cards move
+into `@spree/dashboard-ui` so both dashboards render one definition and cannot
+drift.
+
+## Key Decisions (do not deviate without discussion)
+
+1. **Two new statuses, `proposed` and `rejected`**, added through
+ `add_status` — additive by design, so core workflows guarding on core
+ statuses keep passing. We keep our own vocabulary: `active` is what the
+ marketplace reference calls `published`, and renaming it would churn every
+ existing consumer for no gain. `archived` is untouched.
+
+2. **The lifecycle is workflows, never a state machine.** `Products::Propose`,
+ `Products::Approve` and `Products::Reject` join the existing `Activate` /
+ `Archive` / `Draft` trio, each with a leading `validate` hook. There is no
+ transition graph — that would be a state machine by another name (see
+ `6.0-service-workflows.md`).
+
+3. **`status` stops being a writable attribute on the seller branch.** A
+ seller moves a product with an explicit member action, never by sending a
+ status in an update payload. The operator's branch keeps the plain
+ attribute: an operator publishing their own catalog needs no ceremony.
+
+4. **A seller may return an `active` product to `draft` or `archived`, but may
+ never reach `active` themselves.** Taking your own listing down is not a
+ review decision; putting it up is. This mirrors the legacy gem, which
+ granted `activate` only for products already `active`.
+
+5. **`product_types` becomes its own catalog resource, read-only for the
+ seller audience.** A seller fills in a type's custom fields; they do not
+ define types. Per `6.0-admin-rbac.md`, a new sensitive capability gets its
+ own catalog entry rather than riding an existing key.
+
+6. **`ProductPublication` moves off the `products` key onto a publishing
+ resource with no seller audience.** Which channels carry a product is
+ marketplace merchandising, not a seller's to set.
+
+7. **Custom field *values* are seller-writable; *definitions* are not.**
+ `Spree::CustomField` stays on `products`; `Spree::MetafieldDefinition`
+ is operator-only, and the seller panel renders the definitions it is given
+ without the "add a definition" affordance.
+
+8. **The product form cards live in `@spree/dashboard-ui`**, headless and
+ generic over the record type — data by props, no SDK import, no provider
+ import. `MediaCard`'s one `adminClient.media.list` call becomes an injected
+ prop. This is what makes "the same as in dashboard" true by construction
+ rather than by discipline.
+
+9. **No JSON preview on the seller panel.** It is an opt-in prop on the page
+ shell; the seller form omits it.
+
+## Design Details
+
+### Status lifecycle
+
+```
+draft ──propose──▶ proposed ──approve──▶ active
+ ▲ │
+ │ └──reject───▶ rejected
+ │ │
+ └──────────── seller revises ─────────┘
+
+active ──▶ draft | archived (seller may do this)
+active ──▶ proposed (never — approval is not re-requested)
+```
+
+- `draft` — the seller is still working. Not visible in the storefront.
+- `proposed` — submitted, awaiting the operator. Not visible in the storefront.
+- `active` — approved and on sale. Unchanged meaning.
+- `rejected` — the operator turned it down. Not visible in the storefront. The
+ seller edits and submits again, which returns it to `proposed`.
+- `archived` — withdrawn. Unchanged meaning.
+
+Only `active` is storefront-visible, which is already how `ProductScopes`
+works — the new statuses inherit that for free precisely because they are not
+`active`.
+
+**Auto-approval.** A store preference (`auto_approve_seller_products`)
+chains `Propose` straight into `Approve`, matching how
+`auto_approve_sellers` works in `6.0-seller-onboarding-requirements.md`. A
+marketplace that does not want to review every listing sets it once.
+
+**Rejection reason.** `Reject` takes a `reason:` and records it, so the seller
+sees why. Stored on the product's metadata rather than a new column — this is
+a note, not a queryable domain concept, and a `ProductRejection` model would
+be a table for one string.
+
+### Core
+
+- `Spree::Product`: `add_status :proposed, after: :draft` and
+ `add_status :rejected, after: :proposed`. `STATUSES` stays as-is; the
+ class attribute is what `has_status` validates against.
+- New scopes fall out of `has_status` automatically (`.proposed`, `.rejected`).
+- `Spree::Products::Propose`, `::Approve`, `::Reject` — workflows on the
+ `Activate` template, each publishing an event (`product.proposed`,
+ `product.approved`, `product.rejected`).
+- Registered as `Spree.product_propose_workflow` and friends in
+ `Spree::Dependencies`.
+
+### API
+
+Seller branch:
+
+- `PATCH /seller/products/:id/submit` → `Products::Propose`
+- `PATCH /seller/products/:id/draft` → `Products::Draft` (take down)
+- `PATCH /seller/products/:id/archive` → `Products::Archive`
+- `status` removed from `permitted_params`.
+- `GET /seller/product_types` — read-only, for the type picker.
+- `GET /seller/custom_field_definitions` — read-only, so the form can render
+ the fields a seller fills in.
+
+Admin branch:
+
+- `PATCH /admin/products/:id/approve` → `Products::Approve`
+- `PATCH /admin/products/:id/reject` → `Products::Reject` (takes `reason`)
+- A `proposed` filter on the products index so an operator can find the queue.
+
+### Permissions
+
+```ruby
+register_resource(:product_types, group: :catalog, write: false,
+ audiences: %i[seller],
+ subjects: -> { [Spree::ProductType] })
+
+register_resource(:publishing, group: :catalog,
+ subjects: -> { [Spree::ProductPublication] })
+```
+
+`Spree::ProductType` and `Spree::ProductPublication` leave the `products`
+subject list. Approving and rejecting are `write_products` on the admin
+branch — an operator who may edit the catalog may decide what enters it.
+
+### Dashboard packages
+
+`@spree/dashboard-ui` gains a `products/` directory holding the form cards,
+each headless: no `adminClient`, no `useStore`, no locale import. The two apps
+supply data, mutations and translated labels by prop.
+
+The seller panel composes: General, Media, Prices, Variants, Inventory, SEO,
+Categorization, Custom Fields, Metadata, Status (restricted), Translations.
+It omits Publishing (channels), Tax, and the JSON preview.
+
+`StatusCard` takes the allowed transitions as a prop rather than deriving
+them, so the seller panel offers Submit / Take down / Archive while the
+operator's offers the full set.
+
+## Migration Path
+
+1. Core statuses + the three workflows + dependency registration.
+2. Permission catalog split (`product_types`, `publishing`), with the
+ subjects moved off `products`.
+3. Seller API: member actions, `status` dropped from permitted params,
+ read-only product types and custom field definitions.
+4. Admin API: approve/reject + the review queue filter.
+5. Lift the form cards into `@spree/dashboard-ui`; repoint the operator's
+ dashboard at them (no visual change — the same components).
+6. Build the seller product form on the shared cards.
+7. Data: nothing to migrate. Existing products keep their status; no row is
+ `proposed` or `rejected` until somebody submits one.
+
+## Constraints on Current Work
+
+- **Never permit `status` as a writable attribute on the seller branch.** A
+ new seller endpoint touching products must move status through a workflow.
+- **Do not add `Spree::ProductType` or `Spree::ProductPublication` back to
+ the `products` permission subjects.** They are their own resources now.
+- **A new product-form card goes into `@spree/dashboard-ui`**, not into
+ `@spree/dashboard` — otherwise the two forms drift again, which is the
+ thing this plan exists to prevent. It must take its data by prop and import
+ no SDK.
+- **Storefront visibility keys off `active` only.** A new status must not be
+ added to the published scope without a deliberate decision.
+- No `Product#submitted?`-style helper methods beyond what `has_status`
+ generates, and no columns recording review state — the status is the state.
+
+## Open Questions
+
+- Should a `proposed` product be editable by the seller, or frozen until the
+ operator decides? Leaning editable, with an edit returning it to `draft`
+ so the operator never reviews a moving target. Not blocking: the first cut
+ leaves it editable and in place.
+- Whether the operator needs a bulk approve for a seller's first batch. Likely
+ yes, but `bulk_status_update` already exists and may cover it.
+
+## References
+
+- `docs/plans/6.0-multi-vendor-marketplace.md` — the marketplace core
+- `docs/plans/6.0-seller-onboarding-requirements.md` — the submit-for-review
+ pattern this mirrors (`Sellers::SubmitForReview` / `Approve`)
+- `docs/plans/6.0-admin-rbac.md` — why a new capability gets its own resource
+- `docs/plans/6.0-service-workflows.md` — why transitions are workflows
+- The legacy `spree_multi_vendor` gem's `PermissionSets::VendorUser`, which
+ established `cannot :activate` and `cannot :manage, ProductPublication`.
diff --git a/packages/seller-sdk/src/types/generated/ProductType.ts b/packages/seller-sdk/src/types/generated/ProductType.ts
new file mode 100644
index 0000000000..c5fd6aa991
--- /dev/null
+++ b/packages/seller-sdk/src/types/generated/ProductType.ts
@@ -0,0 +1,12 @@
+// Typelizer digest ff94661cfa2e3ea366ee05fc7f683f16
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {ProductTypeCustomFieldDefinition} from '@/types'
+
+type ProductType = {
+ id: string;
+ name: string;
+ custom_field_definitions: Array<ProductTypeCustomFieldDefinition>;
+}
+
+export default ProductType;
diff --git a/packages/seller-sdk/src/types/generated/ProductTypeCustomFieldDefinition.ts b/packages/seller-sdk/src/types/generated/ProductTypeCustomFieldDefinition.ts
new file mode 100644
index 0000000000..0255f3c2d7
--- /dev/null
+++ b/packages/seller-sdk/src/types/generated/ProductTypeCustomFieldDefinition.ts
@@ -0,0 +1,15 @@
+// Typelizer digest 076da32800ce2f65740f68e41950d330
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type ProductTypeCustomFieldDefinition = {
+ id: string;
+ key: string;
+ namespace: string;
+ label: string;
+ field_type: 'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json';
+ required: boolean;
+ sort_order: number;
+}
+
+export default ProductTypeCustomFieldDefinition;
diff --git a/packages/seller-sdk/src/types/generated/index.ts b/packages/seller-sdk/src/types/generated/index.ts
index 64eb1f2432..f132873640 100644
--- a/packages/seller-sdk/src/types/generated/index.ts
+++ b/packages/seller-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2b7959b291060494f5dfb2020d7ac972
+// Typelizer digest 6cc301582be6ae792f11fc45c408196a
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -15,6 +15,8 @@ export type { default as Invitation } from './Invitation'
export type { default as OrderLineItem } from './OrderLineItem'
export type { default as Order } from './Order'
export type { default as Product } from './Product'
+export type { default as ProductTypeCustomFieldDefinition } from './ProductTypeCustomFieldDefinition'
+export type { default as ProductType } from './ProductType'
export type { default as Profile } from './Profile'
export type { default as RequirementCustomField } from './RequirementCustomField'
export type { default as RequirementStatus } from './RequirementStatus'
diff --git a/spree/api/app/controllers/spree/api/v3/admin/product_types_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/product_types_controller.rb
index e1b936a00b..96b0d7c8e4 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/product_types_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/product_types_controller.rb
@@ -9,7 +9,7 @@ module Spree
# custom field list is read live when a product form renders. The one
# path from a type edit to existing products is `apply_to_products`.
class ProductTypesController < ResourceController
- scoped_resource :products
+ scoped_resource :product_types
# Backfills this type's option types and categories onto the products
# that already carry it. Additive and idempotent — nothing is removed.
diff --git a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
index 5cefff99e6..bd70a00a32 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
@@ -32,6 +32,20 @@ module Spree
end
end
+ # PATCH /api/v3/admin/products/:id/approve
+ #
+ # Accepting a product a seller submitted, putting it on sale.
+ def approve
+ run_review_workflow(Spree.product_approve_workflow)
+ end
+
+ # PATCH /api/v3/admin/products/:id/reject
+ #
+ # Turning a submission down. The reason goes back to the seller.
+ def reject
+ run_review_workflow(Spree.product_reject_workflow, reason: params[:reason])
+ end
+
# POST /api/v3/admin/products/bulk_status_update
# Body: { ids: [...], status: 'draft' | 'active' | 'archived' }
def bulk_status_update
@@ -239,6 +253,21 @@ module Spree
private
+ # Approving and rejecting are edits to the catalog, so they answer to
+ # the same key as any other product write.
+ def run_review_workflow(workflow, **arguments)
+ @resource = find_resource
+ authorize!(:update, @resource)
+
+ result = workflow.call(product: @resource, reviewer: try_spree_current_user, **arguments)
+
+ if result.success?
+ render json: serialize_resource(@resource.reload)
+ else
+ render_service_error(@resource.errors.presence || result.error)
+ end
+ end
+
def search_provider
@search_provider ||= Spree::SearchProvider::Database.new(current_store)
end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/product_types_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/product_types_controller.rb
new file mode 100644
index 0000000000..65e3474b4f
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/product_types_controller.rb
@@ -0,0 +1,35 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # The product types a seller may list against.
+ #
+ # Read only, and deliberately so: a type carries the custom fields a
+ # seller fills in, so they have to see it, but what types the
+ # marketplace offers is the operator's decision
+ # (docs/plans/6.0-seller-product-submission.md).
+ #
+ # Types belong to the store rather than to a seller, so this is one of
+ # the few seller collections not rooted in `current_seller` — the
+ # store comes from the seller, which is what keeps it scoped.
+ class ProductTypesController < Seller::ResourceController
+ scoped_resource :product_types
+
+ protected
+
+ def model_class
+ Spree::ProductType
+ end
+
+ def serializer_class
+ Spree.api.seller_product_type_serializer
+ end
+
+ def scope
+ current_store.product_types
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
index 9c3c9268fb..86d2e33e3b 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
@@ -21,6 +21,28 @@ module Spree
class ProductsController < Seller::ResourceController
scoped_resource :products
+ before_action :set_status_resource, only: [:submit, :draft, :archive]
+
+ # PATCH /api/v3/seller/products/:id/submit
+ #
+ # Asking the marketplace to put this product on sale.
+ def submit
+ run_status_workflow(Spree.product_propose_workflow)
+ end
+
+ # PATCH /api/v3/seller/products/:id/draft
+ #
+ # Taking a listing back down. Withdrawing your own product is not a
+ # review decision, so it needs nobody's approval.
+ def draft
+ run_status_workflow(Spree.product_draft_workflow)
+ end
+
+ # PATCH /api/v3/seller/products/:id/archive
+ def archive
+ run_status_workflow(Spree.product_archive_workflow)
+ end
+
protected
def model_class
@@ -33,7 +55,7 @@ module Spree
def permitted_params
attrs = params.permit(
- :name, :description, :slug, :status,
+ :name, :description, :slug,
:meta_title, :meta_description, :meta_keywords,
:product_type_id,
tags: [],
@@ -60,6 +82,29 @@ module Spree
def collection_includes
[:default_variant, :primary_media]
end
+
+ private
+
+ # Named apart from the base class's own resource lookup: overriding
+ # that one changes every action, and these three are the only ones
+ # that move a status.
+ def set_status_resource
+ @resource = find_resource
+ # A status move is a change to the product, so it needs the write
+ # key rather than one of its own — a read-only seller role cannot
+ # submit, take down or archive.
+ authorize!(:update, @resource)
+ end
+
+ def run_status_workflow(workflow)
+ result = workflow.call(product: @resource)
+
+ if result.success?
+ render json: serialize_resource(@resource.reload)
+ else
+ render_service_error(@resource.errors.presence || result.error)
+ end
+ end
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/product_type_custom_field_definition_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/product_type_custom_field_definition_serializer.rb
new file mode 100644
index 0000000000..fa4caedf8a
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/product_type_custom_field_definition_serializer.rb
@@ -0,0 +1,45 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # The schema of one custom field a product type asks for.
+ #
+ # Declared rather than subclassed from the admin serializer, like every
+ # serializer on this branch: what a seller needs is the shape of the
+ # field they are filling in, and inheriting would tie this branch's
+ # generated types to the operator's.
+ class ProductTypeCustomFieldDefinitionSerializer < V3::BaseSerializer
+ typelize id: :string,
+ key: :string,
+ namespace: :string,
+ label: :string,
+ field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
+ required: :boolean,
+ sort_order: :number
+
+ attribute :id do |join|
+ join.custom_field_definition.prefixed_id
+ end
+
+ attribute :key do |join|
+ join.custom_field_definition.key
+ end
+
+ attribute :namespace do |join|
+ join.custom_field_definition.namespace
+ end
+
+ attribute :label do |join|
+ join.custom_field_definition.label
+ end
+
+ attribute :field_type do |join|
+ join.custom_field_definition.field_type
+ end
+
+ attributes :required, :sort_order
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/product_type_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/product_type_serializer.rb
new file mode 100644
index 0000000000..ee98829145
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/product_type_serializer.rb
@@ -0,0 +1,19 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # A product type as a seller sees it: its name and the custom fields it
+ # asks them to fill in.
+ #
+ # No `products_count` and no option-type or category template — those
+ # describe how the operator maintains the type, which is not a seller's
+ # concern.
+ class ProductTypeSerializer < V3::ProductTypeSerializer
+ many :product_type_custom_field_definitions,
+ key: :custom_field_definitions,
+ resource: proc { Spree.api.seller_product_type_custom_field_definition_serializer }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 2749dde2c1..02aa1b722b 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -293,6 +293,10 @@ Spree::Core::Engine.add_routes do
resources :products, concerns: [:custom_fieldable, :translatable] do
member do
post :clone
+ # Closing a review a seller opened
+ # (docs/plans/6.0-seller-product-submission.md).
+ patch :approve
+ patch :reject
end
collection do
post :bulk_status_update
@@ -728,7 +732,19 @@ Spree::Core::Engine.add_routes do
end
end
- resources :products, only: [:index, :show, :create, :update, :destroy]
+ resources :products, only: [:index, :show, :create, :update, :destroy] do
+ # Status moves are actions, not an attribute: putting a product on
+ # sale is the marketplace's call, so a seller asks rather than sets.
+ member do
+ patch :submit
+ patch :draft
+ patch :archive
+ end
+ end
+
+ # The types a seller may pick from and the fields they fill in. Read
+ # only — defining either is the operator's.
+ resources :product_types, only: [:index, :show]
# What this seller has sold. Cancelling is a member action because it
# is a workflow with its own arguments, and fulfilling is nested: a
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index d4b895afc5..fbc2da5a66 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -165,6 +165,8 @@ module Spree
seller_team_member_serializer: 'Spree::Api::V3::Seller::TeamMemberSerializer',
seller_invitation_serializer: 'Spree::Api::V3::Seller::InvitationSerializer',
seller_product_serializer: 'Spree::Api::V3::Seller::ProductSerializer',
+ seller_product_type_serializer: 'Spree::Api::V3::Seller::ProductTypeSerializer',
+ seller_product_type_custom_field_definition_serializer: 'Spree::Api::V3::Seller::ProductTypeCustomFieldDefinitionSerializer',
seller_order_serializer: 'Spree::Api::V3::Seller::OrderSerializer',
seller_order_line_item_serializer: 'Spree::Api::V3::Seller::OrderLineItemSerializer',
seller_fulfillment_serializer: 'Spree::Api::V3::Seller::FulfillmentSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
index 8270f41762..c575c7320c 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
@@ -1348,6 +1348,38 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
end
end
+ # Closing a review a seller opened
+ # (docs/plans/6.0-seller-product-submission.md).
+ describe 'reviewing a submitted product' do
+ let(:submitted) { create(:product, store: store, status: 'proposed') }
+
+ before { request.headers.merge!(headers) }
+
+ it 'approves it onto sale' do
+ patch :approve, params: { id: submitted.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(submitted.reload).to be_active
+ end
+
+ it 'rejects it with a reason the seller can read' do
+ patch :reject, params: { id: submitted.prefixed_id, reason: 'Photos are too dark' }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(submitted.reload).to be_rejected
+ expect(submitted.metadata['rejection_reason']).to eq('Photos are too dark')
+ end
+
+ it 'refuses to approve a product nobody submitted' do
+ draft = create(:product, store: store, status: 'draft')
+
+ patch :approve, params: { id: draft.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(draft.reload).to be_draft
+ end
+ end
+
describe 'POST #clone' do
subject { post :clone, params: { id: product.prefixed_id }, as: :json }
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/product_types_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/product_types_controller_spec.rb
new file mode 100644
index 0000000000..41db872500
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/product_types_controller_spec.rb
@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::ProductTypesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user, seller_role) }
+ end
+ let(:seller_role) do
+ create(:role, name: 'Seller', resource: seller, permissions: %w[write_products read_product_types])
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:product_type) { create(:product_type, store: store, name: 'Apparel') }
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ describe 'GET #index' do
+ it "lists the store's types so a seller can pick one" do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].pluck('name')).to include('Apparel')
+ end
+
+ it "leaves out another store's types" do
+ elsewhere = create(:product_type, store: create(:store), name: 'Elsewhere')
+
+ get :index, as: :json
+
+ expect(json_response['data'].pluck('id')).not_to include(elsewhere.prefixed_id)
+ end
+ end
+
+ describe 'GET #show' do
+ it 'carries the custom fields the seller has to fill in' do
+ get :show, params: { id: product_type.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response).to have_key('custom_field_definitions')
+ end
+ end
+
+ # Defining types is the operator's. A seller sees them to pick one; there is
+ # no route here to create, edit or delete one.
+ describe 'writing a type' do
+ it 'is not routable' do
+ expect(post: '/api/v3/seller/product_types').not_to be_routable
+ expect(patch: '/api/v3/seller/product_types/pt_x').not_to be_routable
+ expect(delete: '/api/v3/seller/product_types/pt_x').not_to be_routable
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
index 6a07450afc..b3c756b034 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
@@ -107,6 +107,59 @@ RSpec.describe Spree::Api::V3::Seller::ProductsController, type: :controller do
end
end
+ # A seller lists; the marketplace decides what goes on sale. These are the
+ # two halves of that: status is not an attribute they can send, and the
+ # actions that do move it never reach `active`.
+ describe 'status' do
+ # The factory ships products `active`, so a draft is stated explicitly
+ # wherever the case needs one.
+ let!(:unlisted) { create(:product, name: 'Unlisted', seller: seller, store: store, status: 'draft') }
+
+ it 'is not writable through update' do
+ patch :update, params: { id: unlisted.prefixed_id, status: 'active' }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(unlisted.reload).to be_draft
+ end
+
+ it 'submits for review' do
+ patch :submit, params: { id: unlisted.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(unlisted.reload).to be_proposed
+ end
+
+ it 'takes a listing back down' do
+ patch :draft, params: { id: mine.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(mine.reload).to be_draft
+ end
+
+ it 'archives a listing' do
+ patch :archive, params: { id: mine.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(mine.reload).to be_archived
+ end
+
+ it "cannot submit another seller's product" do
+ other_draft = create(:product, seller: other_seller, store: store, status: 'draft')
+
+ patch :submit, params: { id: other_draft.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(other_draft.reload).to be_draft
+ end
+
+ it 'refuses to submit a product already on sale' do
+ patch :submit, params: { id: mine.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(mine.reload).to be_active
+ end
+ end
+
describe 'PATCH #update' do
it 'edits their own product' do
patch :update, params: { id: mine.prefixed_id, name: 'Renamed Lamp' }, as: :json
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 3943129219..686358630b 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -42,8 +42,19 @@ module Spree
primary_category buy_box_variants resolved_delivery_profile
purchasable? in_stock? backorderable? digital?]
+ # Statuses an operator sets directly. `bulk_status_update` validates
+ # against this, which is why the review statuses are not in it: reaching
+ # `proposed` is a seller submitting and reaching `rejected` is an operator
+ # deciding, and neither is a value to assign in bulk.
STATUSES = %w[draft active archived].freeze
+ # Where a product sits in the marketplace review lifecycle. Only the
+ # workflows (Products::Propose, ::Approve, ::Reject) move a product in or
+ # out of these; see docs/plans/6.0-seller-product-submission.md.
+ REVIEW_STATUSES = %w[proposed rejected].freeze
+
+ ALL_STATUSES = (STATUSES + REVIEW_STATUSES).freeze
+
TRANSLATABLE_FIELDS = %i[name description slug meta_description meta_title].freeze
RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
@@ -347,7 +358,7 @@ module Spree
# model already owns: `Product.active` stays the currency-aware scope from
# Spree::ProductScopes rather than a plain status lookup.
include Spree::HasStatus
- has_status(*STATUSES, default: :draft)
+ has_status(*ALL_STATUSES, default: :draft)
# @deprecated Call Spree.product_activate_workflow — removed in 6.1.
def activate!
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 4cd3b57d77..bed5b0d9dc 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -72,6 +72,10 @@ module Spree
# under its name, and letting that happen by omission is the wrong
# default for the operator who never thought about it.
preference :auto_approve_sellers, :boolean, default: false
+ # Put a seller's product on sale the moment they submit it. Off for the
+ # same reason as auto_approve_sellers: what the marketplace lists is what
+ # it vouches for.
+ preference :auto_approve_seller_products, :boolean, default: false
# Checkout preferences
# Store-level fallback for the channel-owned `guest_checkout` preference
# (see Spree::Channel::Gating). Retained so existing accessors keep working.
diff --git a/spree/core/app/workflows/spree/products/approve.rb b/spree/core/app/workflows/spree/products/approve.rb
new file mode 100644
index 0000000000..d3e7d2bc7f
--- /dev/null
+++ b/spree/core/app/workflows/spree/products/approve.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Products
+ # The operator accepting a submitted product, putting it on sale.
+ #
+ # Separate from Activate, which is the operator publishing their own
+ # catalog and answers to nobody: this one closes a review a seller opened,
+ # so it refuses anything that is not awaiting one.
+ class Approve < Spree::Workflow
+ hooks :validate, :after_approve
+
+ # @param product [Spree::Product]
+ # @param reviewer [Spree.admin_user_class, nil] who decided
+ # @return [Spree::ServiceModule::Result] value is the product
+ def perform(product:, reviewer: nil)
+ super
+
+ reject!(Spree.t('activerecord.errors.models.spree/product.attributes.base.not_awaiting_review')) unless product.proposed?
+
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :mark_active
+ run_hooks :after_approve
+ end
+
+ product.publish_event('product.approved')
+ success(product)
+ end
+
+ private
+
+ def mark_active
+ failure(product) unless product.update(status: 'active')
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/products/propose.rb b/spree/core/app/workflows/spree/products/propose.rb
new file mode 100644
index 0000000000..0506cbe587
--- /dev/null
+++ b/spree/core/app/workflows/spree/products/propose.rb
@@ -0,0 +1,46 @@
+module Spree
+ module Products
+ # A seller submitting a product for the marketplace to review.
+ #
+ # The only way onto `proposed`: a seller never assigns a status, so this
+ # is what separates "listed something" from "asked for it to go on sale"
+ # (docs/plans/6.0-seller-product-submission.md).
+ #
+ # Chains straight into Approve when the store does not review listings,
+ # mirroring how `auto_approve_sellers` chains seller onboarding.
+ class Propose < Spree::Workflow
+ hooks :validate, :after_propose
+
+ # @param product [Spree::Product]
+ # @return [Spree::ServiceModule::Result] value is the product
+ def perform(product:)
+ super
+
+ reject!(Spree.t('activerecord.errors.models.spree/product.attributes.base.cannot_propose')) if product.active?
+
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :mark_proposed
+ run_hooks :after_propose
+ end
+
+ product.publish_event('product.proposed')
+
+ return Spree.product_approve_workflow.call(product: product) if auto_approve?
+
+ success(product)
+ end
+
+ private
+
+ def mark_proposed
+ failure(product) unless product.update(status: 'proposed')
+ end
+
+ def auto_approve?
+ product.store&.preferred_auto_approve_seller_products.present?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/products/reject.rb b/spree/core/app/workflows/spree/products/reject.rb
new file mode 100644
index 0000000000..1d5b8735ba
--- /dev/null
+++ b/spree/core/app/workflows/spree/products/reject.rb
@@ -0,0 +1,41 @@
+module Spree
+ module Products
+ # The operator turning a submitted product down.
+ #
+ # The reason rides in metadata rather than a column: it is a note back to
+ # the seller, not a queryable concept, and a table for one string would
+ # outlive its usefulness.
+ class Reject < Spree::Workflow
+ hooks :validate, :after_reject
+
+ # @param product [Spree::Product]
+ # @param reason [String, nil] shown to the seller
+ # @param reviewer [Spree.admin_user_class, nil] who decided
+ # @return [Spree::ServiceModule::Result] value is the product
+ def perform(product:, reason: nil, reviewer: nil)
+ super
+
+ reject!(Spree.t('activerecord.errors.models.spree/product.attributes.base.not_awaiting_review')) unless product.proposed?
+
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :mark_rejected
+ run_hooks :after_reject
+ end
+
+ product.publish_event('product.rejected')
+ success(product)
+ end
+
+ private
+
+ def mark_rejected
+ attributes = { status: 'rejected' }
+ attributes[:metadata] = product.metadata.to_h.merge('rejection_reason' => reason) if reason.present?
+
+ failure(product) unless product.update(attributes)
+ end
+ end
+ end
+end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index e2f3d0e72f..f04a29cc9a 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -338,6 +338,8 @@ en:
attributes:
base:
cannot_destroy_if_attached_to_line_items: Cannot delete Products that are added to placed Orders. In such cases, please discontinue them.
+ cannot_propose: This product is already on sale.
+ not_awaiting_review: This product is not awaiting review.
discontinue_on:
invalid_date_range: must be later than available date
spree/product_publication:
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 053b1a2122..cec9424967 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -146,6 +146,12 @@ module Spree
product_archive_workflow: 'Spree::Products::Archive',
product_draft_workflow: 'Spree::Products::Draft',
+ # marketplace review — a seller submits, the operator decides
+ # (docs/plans/6.0-seller-product-submission.md)
+ product_propose_workflow: 'Spree::Products::Propose',
+ product_approve_workflow: 'Spree::Products::Approve',
+ product_reject_workflow: 'Spree::Products::Reject',
+
# price lists
price_list_create_workflow: 'Spree::PriceLists::Create',
price_list_update_workflow: 'Spree::PriceLists::Update',
diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rb
index c380690ea2..a5184313ca 100644
--- a/spree/core/lib/spree/core/permission_configuration.rb
+++ b/spree/core/lib/spree/core/permission_configuration.rb
@@ -291,11 +291,22 @@ module Spree
register_resource(:store_credits, group: :orders, subjects: -> { [Spree::StoreCredit] })
register_resource(:products, group: :catalog, audiences: %i[seller], subjects: -> {
- [Spree::Product, Spree::ProductType, Spree::Variant, Spree::OptionType,
+ [Spree::Product, Spree::Variant, Spree::OptionType,
Spree::OptionValue, Spree::Price, Spree::PriceList, Spree::PriceRule,
- Spree::ProductPublication, Spree::Catalog, Spree::CatalogProduct,
+ Spree::Catalog, Spree::CatalogProduct,
Spree::CatalogAssignment, Spree::CustomField]
})
+ # A seller fills in a type's custom fields; they do not define the types.
+ # Read-only rather than absent, because the product form has to offer the
+ # picker (docs/plans/6.0-seller-product-submission.md).
+ register_resource(:product_types, group: :catalog, write: false,
+ audiences: %i[seller],
+ subjects: -> { [Spree::ProductType] })
+ # Which channels carry a product is marketplace merchandising. Closed to
+ # the seller audience: a seller lists, the marketplace distributes.
+ register_resource(:publishing, group: :catalog, subjects: -> {
+ [Spree::ProductPublication]
+ })
# Media is its own resource because a file is no longer a product's
# alone: one row can be placed on a category or collection, and the
# library lists, traces and deletes across all of them. Reaching a file
diff --git a/spree/core/spec/workflows/spree/products/review_spec.rb b/spree/core/spec/workflows/spree/products/review_spec.rb
new file mode 100644
index 0000000000..a08d5da501
--- /dev/null
+++ b/spree/core/spec/workflows/spree/products/review_spec.rb
@@ -0,0 +1,94 @@
+require 'spec_helper'
+
+# The marketplace review lifecycle: a seller submits, the operator decides.
+# See docs/plans/6.0-seller-product-submission.md.
+RSpec.describe 'Spree::Products review workflows' do
+ let(:store) { Spree::Store.default }
+ let(:seller) { create(:seller, :approved, store: store) }
+ let(:product) { create(:product, store: store, seller: seller, status: 'draft') }
+
+ describe 'Propose' do
+ it 'submits a draft for review' do
+ result = Spree.product_propose_workflow.call(product: product)
+
+ expect(result).to be_success
+ expect(product.reload).to be_proposed
+ end
+
+ it 'refuses a product already on sale' do
+ product.update!(status: 'active')
+
+ result = Spree.product_propose_workflow.call(product: product)
+
+ expect(result).not_to be_success
+ expect(product.reload).to be_active
+ end
+
+ it 'resubmits a rejected product' do
+ product.update!(status: 'rejected')
+
+ expect(Spree.product_propose_workflow.call(product: product)).to be_success
+ expect(product.reload).to be_proposed
+ end
+
+ # The store that does not review listings says so once, rather than
+ # leaving an operator to approve every submission by hand.
+ it 'goes straight on sale when the store approves automatically' do
+ stub_store_preferences(store, auto_approve_seller_products: true)
+
+ result = Spree.product_propose_workflow.call(product: product)
+
+ expect(result).to be_success
+ expect(product.reload).to be_active
+ end
+ end
+
+ describe 'Approve' do
+ it 'puts a submitted product on sale' do
+ product.update!(status: 'proposed')
+
+ result = Spree.product_approve_workflow.call(product: product)
+
+ expect(result).to be_success
+ expect(product.reload).to be_active
+ end
+
+ # Approving is closing a review somebody opened, not a way to publish
+ # anything at all — that is what Activate is for.
+ it 'refuses a product nobody submitted' do
+ result = Spree.product_approve_workflow.call(product: product)
+
+ expect(result).not_to be_success
+ expect(product.reload).to be_draft
+ end
+ end
+
+ describe 'Reject' do
+ it 'turns a submitted product down and keeps the reason' do
+ product.update!(status: 'proposed')
+
+ result = Spree.product_reject_workflow.call(product: product, reason: 'Photos are too dark')
+
+ expect(result).to be_success
+ expect(product.reload).to be_rejected
+ expect(product.metadata['rejection_reason']).to eq('Photos are too dark')
+ end
+
+ it 'refuses a product nobody submitted' do
+ result = Spree.product_reject_workflow.call(product: product)
+
+ expect(result).not_to be_success
+ expect(product.reload).to be_draft
+ end
+ end
+
+ # A product under review is not on sale. The storefront scope keys off
+ # `active` alone, so this holds for any status we add without touching it.
+ it 'keeps products under review out of the storefront' do
+ %w[proposed rejected].each do |status|
+ product.update!(status: status)
+
+ expect(Spree::Product.active.where(id: product.id)).to be_empty
+ end
+ end
+end