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
Documented which filters each list endpoint accepts
Damian Legawiec7415e39d4341
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdxindex 090e3eeeb4..fedad88238 100644--- a/docs/developer/core-concepts/search-filtering.mdx+++ b/docs/developer/core-concepts/search-filtering.mdx@@ -261,6 +261,21 @@ The Store API uses query parameters prefixed with `q[]` for filtering any resourOnly attributes explicitly allowed by each resource can be used for filtering. Attempting to filter on unsupported fields will be silently ignored.</Info>+### Making a field filterable++A resource's filters come from its model's allowlists, and nowhere else. The API reference and the SDK types are generated from them, so whatever you add appears in the [Querying](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts) reference and in the typed `list()` parameters without further work.++```ruby server/config/initializers/spree.rb+Spree.ransack.add_attribute(Spree::Product, :erp_id)+Spree.ransack.add_association(Spree::Product, :brand)+Spree.ransack.add_scope(Spree::Product, :featured, type: 'boolean')+Spree.ransack.add_scope(Spree::Product, :by_brand, type: 'id')+```++Declare the `type` of a scope's argument: `'boolean'` for a scope taking none (`q[featured]=true`), or `'text'`, `'id'`, `'decimal'`, `'integer'`, `'date'` or `'datetime'` for one value. A list of kinds (`%w[decimal decimal]`) means several arguments in order, and `{ list: 'id' }` means any number of them. A scope declared without a type is published as taking one text value.++Every entry is a filter any caller of that API can run. Keep back-office fields out of the Store API with `private_ransackable_attributes`, and add associations the storefront may filter through to `storefront_ransackable_associations`.+## PaginationAll list endpoints support pagination:diff --git a/docs/developer/tutorial/model-and-api.mdx b/docs/developer/tutorial/model-and-api.mdxindex 411cb3f981..309563e7de 100644--- a/docs/developer/tutorial/model-and-api.mdx+++ b/docs/developer/tutorial/model-and-api.mdx@@ -175,7 +175,7 @@ attribute(:brand_id) { |product| product.brand&.prefixed_id }has_one :brand, serializer: Spree::Api::V3::BrandSerializer```-The model has to allow filtering by it, or `?q[brand_id_eq]=…` is rejected:+The model has to allow filtering by it, or `?q[brand_id_eq]=…` is ignored:```ruby server/app/models/spree/product_decorator.rbbase.whitelisted_ransackable_attributes |= %w[brand_id]diff --git a/docs/plans/6.0-typed-filters.md b/docs/plans/6.0-typed-filters.mdindex 0dd6beeb08..04da8c0f69 100644--- a/docs/plans/6.0-typed-filters.md+++ b/docs/plans/6.0-typed-filters.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** nothing unbuilt. Decimal values are already strings in the generated SDK types.**Author:** Damian + Claude-**Last updated:** 2026-10-09+**Last updated:** 2026-10-09 (PR A built)**Tracking:** Linear V-3740 · GitHub spree/spree#14851## Summary@@ -37,10 +37,10 @@ Ransack rejects unknown filters with a 400 instead of ignoring them. Nothing abo| Value kind | Predicates || --- | --- |- | text | `eq` `not_eq` `in` `not_in` `cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |+ | text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` || decimal, integer, date, datetime | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` || enum, prefixed ID, short-name type | `eq` `not_eq` `in` `not_in` `null` `not_null` |- | boolean | `eq` `true` `false` `null` |+ | boolean | `eq` `not_eq` `in` `not_in` `true` `false` `null` |A predicate outside the set for its kind is rejected, even when Ransack would accept it.- **Associations are typed and accepted to depth 2.** Depth 2 covers the dashboard's deepest filter today (`sku_or_variant_product_name_cont` on stock items). Each hop uses the associated model's own allowlist for the same audience. Deeper paths are rejected. The Store and Seller APIs already expose only `storefront_ransackable_associations`, so their tables stay small.@@ -68,6 +68,10 @@ Ransack rejects unknown filters with a 400 instead of ignoring them. Nothing abo- **Seller filters reach no associations (2026-10-09).** The Seller API keeps today's behaviour: a restricted audience other than `:store` gets an empty association list, so the seller tables hold the model's own attributes and scopes only. A seller list needing a related filter declares a scope. Rejected: a separate `seller_ransackable_associations` list (each entry is a join a seller can probe and needs its own review), and reusing the storefront list (widening one audience would silently widen the other).- **`_in` / `_not_in` take arrays only (2026-10-09).** `q[key][]=a&q[key][]=b`, or the indexed hash form, is the only encoding. Ransack never split comma-separated strings, so `q[status_in]=a,b` already matched nothing; PR C turns it into a 400. Rejected: splitting commas on the server, which makes a value containing a comma unfilterable.- **No 5.x deprecation release (2026-10-09).** 6.0 is a major version. The upgrade guide documents the change, and PR C adds a `Spree.api.strict_filters` setting (default on) that a store can switch off for one release while it fixes its integrations. Rejected: a 5.x warning header (maintenance-branch work and a separate release) and strict-only with no setting.+- **The dashboard's predicates are in the set (2026-10-09, amended while building PR A).** Every text filter in the dashboard sends `i_cont`, and its two-choice filters on true/false columns send `not_eq`, `in` and `not_in`, so those join the text and boolean rows. Leaving them out would have made PR C break every text filter in the admin.+- **Value kinds come from more than the column type (2026-10-09).** Enum values are read from `has_status`, Rails `enum` declarations and inclusion validations with a fixed list (`Order#payment_status`). A scope's argument types fall back to its method signature for a plain class method (no arguments is a flag, `*ids` is a list); only `scope` lambdas, whose signature Ruby hides, need `ransackable_scope_types`. Extensions declare theirs with `Spree.ransack.add_scope(model, name, type:)`.+- **Endpoints describe what they add (2026-10-09).** `ResourceController#filterable?` (false for an index that ignores `q` or picks its model per request), `#additional_sort_fields` (product sorts outside Ransack: `price`, `best_selling`, `manual`) and `#custom_field_filters?` (the store's `cf_*` keys, typed as an open pattern) cover what the allowlists cannot.+- **SDK specifics (2026-10-09).** The generated file is `src/types/filters.generated.ts`, outside `types/generated/`, which the Zod generator and Typelizer own. Filter types get no Zod schemas: they describe requests, and the schemas validate responses. Decimal filters accept `string | number`, since a query string carries no precision. The Store SDK keeps `ProductListParams`, `CategoryListParams`, `CollectionListParams` and `OrderListParams` as aliases of the generated types. Code that builds filters at runtime (the dashboard's tables and the pages shared by both panels) passes them through `runtimeListParams`, the one place that is not checked.- **This run builds PR A only (2026-10-09).** PR B's logging belongs to Spree Cloud, and PR C waits for what it finds.- **One direction of generation.** Model declarations → the swaggerize run (which already has a database, so the rule against `typelize_from` still holds) → `x-spree-filters` in `docs/api-reference/*.yaml` → SDK types. CI fails when the committed SDK filter types do not match the specs.@@ -110,7 +114,7 @@ This is the black-box specification a non-Ruby implementation must pass. It need## Migration Path-**PR A: table and types (no behaviour change)**+**PR A: table and types (no behaviour change)** — built 2026-10-09. The dashboard type-check and an audit of every table's filter and sort keys found ten filters and sorts the API was ignoring (allowed-origins search, delivery zones by profile, payment method type and active, seller status and email, option type kind, custom field type, market currency and locale, gift card currency and expiry); they are now declared, and four SDK examples that nested filters under `q` are fixed.1. Add `FilterPredicates`, `FilterTable` and `ransackable_scope_types` (optional), with a spec that fails for any list endpoint whose table cannot be built.2. Add `filter_parameters_for` to `swagger_helper`; replace the hand-written `q[...]` parameters in integration specs; regenerate the specs with `x-spree-filters`.3. Generate SDK filter types; type every list method with `ListParams<Filters, Sort>`; delete the hand-written filter interfaces.@@ -129,6 +133,8 @@ Verification per PR: `pnpm test:changed`, then `pnpm test:rspec api`; `pnpm type## Constraints on Current Work+- A list endpoint without an integration spec has no filter table in OpenAPI, so its SDK method keeps loose parameters. 44 endpoints are in that state (claims, returns, exchanges, variants, order groups, nested custom fields and others); each one gains typed filters when it gains an integration spec with `filter_parameters_for`.+- Declare filterable attributes, associations and scopes on the model allowlists only. Never parse `params[:q]` by hand in a controller; add a scope instead.- A new scope taking an argument adds its types to `ransackable_scope_types`.- Never hand-write `q[...]` parameters in an integration spec; use `filter_parameters_for`.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 91acee5767..5d62223ec3 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -4,6 +4,8 @@**Decision:** The Seller API reaches no associations through filters, as today; related-data filters for sellers are scopes. `_in` and `_not_in` accept arrays only, never comma-separated strings. There is no 5.x deprecation release: the upgrade guide covers the change, and PR C adds a `Spree.api.strict_filters` setting (default on) that a store can turn off for one release.+The published predicate set also gains `i_cont` for text and `not_eq`/`in`/`not_in` for true/false attributes, which the dashboard's filters already send.+**Consequences:** Seller SDK filter types stay attribute-only. A client sending `q[status_in]=a,b` gets a 400 once enforcement lands, which is the same empty result it already gets, made visible. Self-hosted stores learn of undeclared filters from the upgrade guide and the escape hatch, not from a warning in production.**Plan:** `6.0-typed-filters.md`.