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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
docs(plans): keep collection merchandising config out of the Store API
Łukasz Adamczykb8c3479c35bd
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.mdindex c9adccb7bb..35c523792b 100644--- a/docs/plans/6.0-replace-taxons-with-categories.md+++ b/docs/plans/6.0-replace-taxons-with-categories.md@@ -397,7 +397,7 @@ PATCH /api/v3/admin/collections/:idDELETE /api/v3/admin/collections/:id```-Collection response:+Collection response (**Admin** — the Store serializer omits the merchandising config `automatic`, `rules_match_policy`, and `rules`; that's back-office state, not customer-facing):```json{"id": "coll_k5nR8xLq",@@ -413,12 +413,13 @@ Collection response:"slug": "summer-sale"}```+The **Store** response is the customer-facing subset — `id`, `name`, `slug`/`permalink`, `description`/`description_html`, `image_url`/`square_image_url`, `sort_order`, `hide_from_nav`, `position`, `meta_*`, `products_count` (+ `custom_fields` on expand) — with **no** `automatic`/`rules_match_policy`/`rules` (internal merchandising state stays out of the Store API, per the store-vs-admin serializer rule).### Collection product listing (Store API)Products in a collection are served by a **dedicated endpoint**, not a filter on `/products`. This follows the Shopify Storefront GraphQL model (`collection { products }`) where the collection is the path context and filters/sort layer on top. (Most REST APIs — WooCommerce, Medusa, commercetools, BigCommerce — use a `?collection_id=` filter instead; we deliberately choose the nested style for cleaner requests and to apply the collection's own default sort automatically. `in_collection` is still kept as a Ransack scope for composite queries.)-- `GET /api/v3/store/collections/:id/products` — a thin controller that resolves the collection and **delegates to the same search-provider flow** as `/products` (query, Ransack filters, pagination, serializer). `def scope` stays the **base visibility scope** (`available` + `accessible_by`) — it is **not** pre-scoped to the collection. Instead the controller injects `in_collection: collection.id` into the filters, and each provider applies it: the DB provider via the `in_collection` Ransack scope, Meilisearch via the `collection_ids` filter. Collection scoping has to be a provider filter (not an AR pre-scope) because Meilisearch does its own filtering/counting/pagination and treats the AR scope only as a post-search visibility guard. No logic duplication.+- `GET /api/v3/store/collections/:id/products` — a thin controller that resolves the collection and **delegates to the same search-provider flow** as `/products` (query, Ransack filters, pagination, serializer). `def scope` stays the **base visibility scope** (`available` + `accessible_by`) — it is **not** pre-scoped to the collection. Instead the controller injects `in_collection: collection.prefixed_id` into the filters, and each provider applies it: the DB provider via the `in_collection` Ransack scope, Meilisearch via the `collection_ids` filter. Collection scoping has to be a provider filter (not an AR pre-scope) because Meilisearch does its own filtering/counting/pagination and treats the AR scope only as a post-search visibility guard. No logic duplication.- **Sort precedence.** Effective sort = the request's `sort` param if present, otherwise the collection's `sort_order`. Position ordering (`ProductCollection.position`) applies **only when the effective sort is `manual`**; any dynamic sort — whether from the collection's own default or a shopper override — dismisses it. Because the listing runs through the provider (for the `in_collection` filter, pagination, and faceting), manual sort **cannot** be handled by bypassing the provider with a direct AR query — it must be implemented *in* the provider. That's the same provider-level manual-sort fix categories need, which is **unresolved** (Open Question #1, approach TBD); until it lands, a `sort_order: 'manual'` collection falls back to default order. The dedicated endpoint does **not** sidestep the v3 manual-sort gap.- **Facets/sort metadata** reuse the existing `GET /api/v3/store/products/filters` with a new **`collection_id`** param (parallel to `category_id`): it resolves the collection, scopes `in_collection`, and passes **only the collection's `sort_order`** to `FiltersAggregator` — via a `sort_order:` string param, **not** the `Collection` object (the aggregator stays decoupled from the model). No child facet (collections are flat).- **Model:** `Spree::Product.in_collection` scope (flat join to `spree_product_collections`, no descendants), whitelisted as a ransackable scope. (No `in_collections` plural — the collection surface is single-collection; add it only if a real multi-collection filter appears.)