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
Update plans
Damian Legawieca7cc9b6cc511
diff --git a/CLAUDE.md b/CLAUDE.mdindex 6cdda484bd..ebd3dd6098 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -24,13 +24,15 @@ Current plans:- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain- `6.0-channels-catalogs-b2b.md` — Channel, Catalog, ProductListing (replaces StoreProduct), Company/CompanyLocation/CompanyContact for B2B- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename-- `6.0-search-provider.md` — Pluggable SearchProvider interface (Database default, Meilisearch/Elasticsearch/Algolia adapters), MetafieldDefinition faceting, autocomplete endpoint-- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator, TaxZone for internal provider only+- `5.4-search-provider.md` — Pluggable SearchProvider interface (5.4: Database + Meilisearch, 6.0: MetafieldDefinition faceting)+- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator, drop Zone model (TaxRate gets direct country/state FKs)- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider, replaces Estimator + Calculator, DeliveryZone with postal code support- `6.0-rich-text-descriptions.md` — Drop ActionText storage, store HTML in text columns, sanitize on write, serve `description` + `description_html` in API-- `5.x-store-api-bridges.md` — Bridge 6.0 naming into 5.5 Store API (fulfillments, delivery, status, remove master_variant)-- `5.x-store-api-naming-standardization.md` — Standardize API naming against industry (address fields, discounts, customer_note, label, brand/last4, etc.)-- `spree-starter-and-create-spree-app.md` — Replace monorepo server/ with spree-starter template repo, always include backend/ in create-spree-app, add spree eject+- `5.4-store-api-naming-standardization.md` — Standardize API naming against industry (address fields, discounts, customer_note, label, brand/last4, etc.)++Completed plans:+- `5.4-store-api-bridges.md` — Bridge 6.0 naming into 5.4 Store API (implemented, PR #13782)+- `spree-starter-and-create-spree-app.md` — Replace monorepo server/ with spree-starter template repo## Monorepo Structurediff --git a/docs/plans/5.x-store-api-bridges.md b/docs/plans/5.4-store-api-bridges.mdsimilarity index 94%rename from docs/plans/5.x-store-api-bridges.mdrename to docs/plans/5.4-store-api-bridges.mdindex 2612c40021..f0e0bdcdd5 100644--- a/docs/plans/5.x-store-api-bridges.md+++ b/docs/plans/5.4-store-api-bridges.md@@ -1,20 +1,20 @@-# Store API 5.x Bridges for 6.0+# Store API 5.4 Bridges for 6.0**Status:** Implemented (PR #13782)-**Target:** Spree 5.5 (next minor)+**Target:** Spree 5.4 (next minor)**Depends on:** None — all changes are serializer/controller renames on existing models**Author:** Damian + Claude**Last updated:** 2026-03-17## Summary-Introduce 6.0 Store API naming NOW in 5.5, with breaking changes. No aliases, no deprecation periods — clean breaks. This gives storefront developers the final API shape before models are renamed in 6.0.+Introduce 6.0 Store API naming NOW in 5.4, with breaking changes. No aliases, no deprecation periods — clean breaks. This gives storefront developers the final API shape before models are renamed in 6.0.-The approach: change the **API surface** (serializers, response keys, endpoint paths) in 5.x while the **models** stay unchanged until 6.0. Serializers are the translation layer.+The approach: change the **API surface** (serializers, response keys, endpoint paths) in 5.4 while the **models** stay unchanged until 6.0. Serializers are the translation layer.## Scope-Only changes where the API field/endpoint name changes between 5.x and 6.0. Purely additive features (new endpoints, new fields, new resources) ship with their 6.0 plan and don't need bridging.+Only changes where the API field/endpoint name changes between 5.4 and 6.0. Purely additive features (new endpoints, new fields, new resources) ship with their 6.0 plan and don't need bridging.## Changes@@ -26,7 +26,7 @@ Already done in current API:- `default_variant_id` field on ProductSerializer ✓- `expand=default_variant` on ProductSerializer ✓-Remove now (5.5):+Remove now (5.4):- Remove `expand=master_variant` from ProductSerializer- Remove `is_master` field from VariantSerializer@@ -49,7 +49,7 @@ one :master,Rename in serializers (model stays `Shipment` until 6.0):-| Before (5.4) | After (5.5) | Serializer change |+| Before (5.4) | After (5.4) | Serializer change ||---|---|---|| `shipments` (nested in Cart/Order) | `fulfillments` | Change `key:` on association || `shipping_rates` (nested in Shipment) | `delivery_rates` | Change `key:` on association |@@ -107,7 +107,7 @@ endModels still use `state` column until 6.0. Serializers translate:-| Serializer | Before (5.4) | After (5.5) |+| Serializer | Before (5.4) | After (5.4) ||---|---|---|| ShipmentSerializer | `state` | `status` (reads `object.state`) || PaymentSerializer | `state` | `status` (reads `object.state`) |@@ -140,7 +140,7 @@ endThe model split (Adjustment → TaxLine, Discount, Fee) happens in 6.0. But the serialized totals can be renamed now for clarity:-| Before (5.4) | After (5.5) | On |+| Before (5.4) | After (5.4) | On ||---|---|---|| `adjustment_total` | `adjustment_total` | Cart/Order — **keep as-is** (sum of all adjustments) || `ship_total` / `display_ship_total` | `delivery_total` / `display_delivery_total` | Cart/Order (covered in #2 above) |@@ -244,7 +244,7 @@ All changes implemented in PR #13782. Versions bumped to 0.12.0 for both `@spree| `default_variant_id` on products | Already exists ✓ || ProductType, Collections, Stock Reservations, Returns/Claims, Channels/Catalogs | Purely additive — ship with 6.0 |-## Prefixed IDs — changed in 5.x+## Prefixed IDs — changed in 5.4Prefixed IDs are updated to match the new vocabulary. The `find_by_prefix_id!` method ignores the prefix during decoding (it splits on `_` and decodes only the Sqids portion), so old IDs with old prefixes still resolve correctly.@@ -255,15 +255,15 @@ Prefixed IDs are updated to match the new vocabulary. The `find_by_prefix_id!` m| ShippingRate | `shpr_` | `dr_` || InventoryUnit | `iu_` | `fi_` |-## NOT changed in 5.x (deferred to 6.0 model rename)+## NOT changed in 5.4 (deferred to 6.0 model rename)### Event names-Event names (`shipment.shipped`, `shipment.canceled`) are **not changed** in 5.x. Webhook subscribers and event listeners depend on these strings. They change in 6.0 to `fulfillment.fulfilled`, `fulfillment.canceled` with old names emitted alongside for one release.+Event names (`shipment.shipped`, `shipment.canceled`) are **not changed** in 5.4. Webhook subscribers and event listeners depend on these strings. They change in 6.0 to `fulfillment.fulfilled`, `fulfillment.canceled` with old names emitted alongside for one release.## Constraints on Current Work-- **All new Store API code must use the 5.5 naming.** No `shipment`, `shipping_method`, `state`, `master_variant` in new endpoints.+- **All new Store API code must use the 5.4 naming.** No `shipment`, `shipping_method`, `state`, `master_variant` in new endpoints.- **SDK examples and docs must use new naming** after this ships.- **Admin API is not affected by this plan.** Admin serializers may keep old naming until 6.0 model renames happen (or can be bridged separately).diff --git a/docs/plans/5.x-store-api-naming-standardization.md b/docs/plans/5.4-store-api-naming-standardization.mdsimilarity index 97%rename from docs/plans/5.x-store-api-naming-standardization.mdrename to docs/plans/5.4-store-api-naming-standardization.mdindex f393a4a21c..2887045ddc 100644--- a/docs/plans/5.x-store-api-naming-standardization.md+++ b/docs/plans/5.4-store-api-naming-standardization.md@@ -2,7 +2,7 @@**Status:** In Progress**Target:** Spree 5.4 (API surface + model aliases); Spree 6.0 (database columns/tables)-**Depends on:** `5.x-store-api-bridges.md` (same pattern: rename API surface now, models/DB later)+**Depends on:** `5.4-store-api-bridges.md` (same pattern: rename API surface now, models/DB later)**Author:** Damian + Claude**Last updated:** 2026-03-19@@ -12,7 +12,7 @@ Standardize Spree Store API entity and attribute names against industry conventi## Key Decisions (do not deviate without discussion)-- All changes are **breaking** in the Store API — no backward compatibility, new names only (same approach as `5.x-store-api-bridges.md`)+- All changes are **breaking** in the Store API — no backward compatibility, new names only (same approach as `5.4-store-api-bridges.md`)- Models get **alias accessors** for new names pointing to old columns — serializers and services use the new names directly- Database column/table renames are deferred to **6.0**- Controllers accept **new param names only** — no backward compat for old names@@ -152,7 +152,7 @@ Removed from `CreditCardSerializer` and `PaymentSourceSerializer`. Added to `Adm**6.0 database:** Covered by `6.0-normalize-state-to-status.md`-### 16. Additional Order model aliases (from 5.x-store-api-bridges)+### 16. Additional Order model aliases (from 5.4-store-api-bridges)These aliases consolidate all naming bridges on `Spree::Order`:- `alias fulfillments shipments`@@ -228,6 +228,6 @@ None — all decisions made.## References-- `5.x-store-api-bridges.md` — prior art for this exact pattern+- `5.4-store-api-bridges.md` — prior art for this exact pattern- `6.0-normalize-state-to-status.md` — covers `state` → `status` DB rename- Industry comparison: Shopify, Medusa, Saleor, Vendure, BigCommerce, commercetools Storefront APIsdiff --git a/docs/plans/6.0-delivery-rate-provider.md b/docs/plans/6.0-delivery-rate-provider.mdindex eca293b031..c81f7f89e7 100644--- a/docs/plans/6.0-delivery-rate-provider.md+++ b/docs/plans/6.0-delivery-rate-provider.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Fulfillment & Delivery (6.0-fulfillment-and-delivery.md) for DeliveryMethod rename**Author:** Damian + Claude-**Last updated:** 2026-03-20+**Last updated:** 2026-03-22## Summary@@ -421,7 +421,7 @@ This enables delivery scenarios that the current Zone model can't handle:- "Express available in London only" (state + postal code)- "International shipping to EU countries" (country-level, same as today)-Tax doesn't use zones at all — TaxRate links directly to country/state (see `6.0-tax-provider.md`). The generic `Zone` model is removed in 6.0, replaced by `DeliveryZone` for delivery and direct country/state FKs on TaxRate for tax.+Tax doesn't use zones at all — TaxRate links directly to country/state (see `6.0-tax-provider.md`). The generic `Spree::Zone` model is **dropped entirely** in 6.0. A shared data migration (rake task `spree:migrate_zones`, defined in the Tax Provider plan) converts existing Zone records used by ShippingMethod/DeliveryMethod into `DeliveryZone` records, and Zone records used by TaxRate into direct country/state FKs. After migration, `spree_zones` and `spree_zone_members` tables are removed.## Constraints on Current Workdiff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.mdindex 94d138dae4..143a247d75 100644--- a/docs/plans/6.0-fulfillment-and-delivery.md+++ b/docs/plans/6.0-fulfillment-and-delivery.md@@ -27,7 +27,7 @@ This is three changes in one:## Entity Rename Map-| Current (5.x) | 6.0 | Prefix ID | Table |+| Current (5.4) | 6.0 | Prefix ID | Table ||---|---|---|---|| `Spree::Shipment` | `Spree::Fulfillment` | `ful_` | `spree_fulfillments` || `Spree::ShippingMethod` | `Spree::DeliveryMethod` | `dm_` | `spree_delivery_methods` |diff --git a/docs/plans/6.0-platform-auth.md b/docs/plans/6.0-platform-auth.mdindex 3ba29d2d2b..97d4e52fdb 100644--- a/docs/plans/6.0-platform-auth.md+++ b/docs/plans/6.0-platform-auth.md@@ -1,7 +1,7 @@# Platform-Owned Authentication & User Model Rename-**Status:** In Progress (RefreshToken shipping in 5.5, rest in 6.0)-**Target:** Spree 5.5 (RefreshToken) + Spree 6.0 (Devise removal, User→Customer rename)+**Status:** In Progress (RefreshToken shipping in 5.4, rest in 6.0)+**Target:** Spree 5.4 (RefreshToken) + Spree 6.0 (Devise removal, User→Customer rename)**Depends on:** Admin SPA (6.0-admin-spa.md — removes Rails admin, kills Devise dependency) for Devise removal**Author:** Damian + Claude**Last updated:** 2026-03-17@@ -69,7 +69,7 @@ Two changes in one plan:- **`has_secure_password` is the foundation.** Rails core, no gem dependency. Handles bcrypt hashing, `authenticate(password)` method, password confirmation validation.- **JWT stays as-is.** Short-lived access tokens, separate audiences for store (`store_api`) and admin (`admin_api`). Already implemented and working.- **Strategy pattern stays as-is.** `Spree.store_authentication_strategies` and `Spree.admin_authentication_strategies` for registering custom providers.-- **Add refresh token support (5.5).** Short-lived access JWT (15 min) + long-lived refresh token (stored in DB, rotatable, revocable). Better UX for React admin and Next.js storefront — silent refresh instead of forced re-login. Ships in 5.5 — can't wait for 6.0 because every storefront has broken session management without it.+- **Add refresh token support (5.4).** Short-lived access JWT (15 min) + long-lived refresh token (stored in DB, rotatable, revocable). Better UX for React admin and Next.js storefront — silent refresh instead of forced re-login. Ships in 5.4 — can't wait for 6.0 because every storefront has broken session management without it.- **Rate limiting on auth endpoints.** Use Rails `rate_limit` DSL on login, register, and password reset endpoints. Baked in, not optional.- **Account lockout after failed attempts.** Track `failed_attempts` and `locked_at` on Customer/AdminUser model. Simple, no Devise dependency.- **Remove all Devise generators.** Drop `spree/authentication/devise/` generator directory.diff --git a/docs/plans/6.0-returns-exchanges-claims.md b/docs/plans/6.0-returns-exchanges-claims.mdindex dbb9a919e6..f3f55a1ee2 100644--- a/docs/plans/6.0-returns-exchanges-claims.md+++ b/docs/plans/6.0-returns-exchanges-claims.md@@ -2,9 +2,9 @@**Status:** Draft**Target:** Spree 6.0-**Depends on:** Fulfillment & Delivery rework (6.0-fulfillment-and-delivery.md), Split Adjustments (6.0-split-adjustments.md)+**Depends on:** Fulfillment & Delivery rework (6.0-fulfillment-and-delivery.md), Split Adjustments (6.0-split-adjustments.md), Normalize state→status (6.0-normalize-state-to-status.md)**Author:** Damian + Claude-**Last updated:** 2026-03-16+**Last updated:** 2026-03-22## Summarydiff --git a/docs/plans/6.0-stock-reservations.md b/docs/plans/6.0-stock-reservations.mdindex ca896c52d5..8650307d77 100644--- a/docs/plans/6.0-stock-reservations.md+++ b/docs/plans/6.0-stock-reservations.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Cart/Order split (6.0-cart-order-split.md)**Author:** Damian + Claude-**Last updated:** 2026-03-16+**Last updated:** 2026-03-22## Summary@@ -27,7 +27,7 @@ Every modern commerce platform solves this with time-limited reservations.- **New model `Spree::StockReservation`** — concrete FKs to `stock_item`, `line_item`, `order`. No polymorphism.- **`StockItem.count_on_hand` is never modified by reservations.** It only changes on order completion (decrement) or stock adjustment. Reservations are a soft hold computed at query time.-- **Available quantity = `count_on_hand - active_reservations`** — the `Quantifier` is updated to subtract active reservations from physical stock.+- **Available quantity = `count_on_hand - allocated_count - active_reservations`** — the `Quantifier` is updated to subtract both allocations (from 6.0-typed-stock-movements.md) and active reservations from physical stock. When Typed Stock Movements ships, `allocated_count` is included; before that, it's zero.- **Configurable trigger** — `Spree::Config[:reserve_stock_on]` controls when reservations are created: `:checkout` (when entering checkout, default) or `:cart` (when adding to cart). Cart-level is more aggressive, checkout-level is the standard.- **Configurable TTL per store** — `store.preferred_stock_reservation_ttl` (default: 10 minutes). Merchants can tune this based on their checkout complexity.- **Reservations extend on activity** — each checkout interaction (address update, shipping selection, payment) resets `expires_at` to prevent expiry during active checkout.@@ -82,12 +82,22 @@ endclass Spree::Stock::Quantifierdef total_on_hand@total_on_hand ||= if variant.should_track_inventory?- raw_count_on_hand - reserved_quantity+ available_stock - reserved_quantityelseBigDecimal::INFINITYendend+ # Physical stock minus allocated (pending fulfillment)+ # allocated_count comes from 6.0-typed-stock-movements.md (zero until that ships)+ def available_stock+ if association_loaded?+ stock_items.sum(&:available_count)+ else+ stock_items.sum('count_on_hand - allocated_count')+ end+ end+def reserved_quantityreturn 0 unless Spree::Config[:stock_reservations_enabled]@@ -97,7 +107,7 @@ class Spree::Stock::Quantifier.sum(:quantity)end- # Existing: physical count without reservations (for admin/reporting)+ # Physical count without reservations or allocations (for admin/reporting)def raw_count_on_handif association_loaded?stock_items.sum(&:count_on_hand)diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex 015615d944..2eb8dac9bf 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Split Adjustments (6.0-split-adjustments.md) for TaxLine model, Channels/Catalogs/B2B (6.0-channels-catalogs-b2b.md) for Company.tax_exempt**Author:** Damian + Claude-**Last updated:** 2026-03-20+**Last updated:** 2026-03-22## Summary@@ -89,7 +89,7 @@ Provider (order lifecycle)```ruby# Two-phase: estimate during checkout, commit on completion-provider.estimate(order, items) # → writes TaxLine records (or Adjustments in 5.x)+provider.estimate(order, items) # → writes TaxLine records (or Adjustments in 5.4)provider.commit(order) # → finalizes with external service, no-op for internalprovider.void(order) # → cancels committed tax document, no-op for internal```@@ -157,7 +157,7 @@ scope :for_address, ->(address) {State-level rates override country-level (more specific wins). A rate with `country=US, state=CA` takes precedence over `country=US, state=nil` for California addresses.-The generic `Zone` model is replaced by `DeliveryZone` for shipping (see `6.0-delivery-rate-provider.md`) — delivery needs country grouping and postal code granularity that tax doesn't.+The generic `Spree::Zone` model is **dropped entirely** in 6.0. A data migration (rake task) converts existing Zone records into `TaxRate` country/state FKs (for tax) and `DeliveryZone` records (for shipping, see `6.0-delivery-rate-provider.md`). After migration, `spree_zones` and `spree_zone_members` tables are removed.This matches the natural scope hierarchy:@@ -196,7 +196,7 @@ module Spree# Estimate tax for items in an order. Called during checkout recalculation.# Must be idempotent — repeated calls update existing tax records.#- # Creates/updates TaxLine records (6.0) or Adjustment records (5.x).+ # Creates/updates TaxLine records (6.0) or Adjustment records (5.4).## @param order [Spree::Order]# @param items [Array<Spree::LineItem, Spree::Shipment>] items to tax@@ -453,7 +453,8 @@ class Spree::TaxExemptionCertificate < Spree.base_classhas_prefix_id :certbelongs_to :company, class_name: 'Spree::Company'- belongs_to :zone, class_name: 'Spree::Zone', optional: true # jurisdiction+ belongs_to :country, class_name: 'Spree::Country', optional: true # jurisdiction (nil = all countries)+ belongs_to :state, class_name: 'Spree::State', optional: true # state-level (nil = entire country)validates :certificate_number, presence: truevalidates :status, presence: true # pending, verified, expired, revoked@@ -467,7 +468,10 @@ class Spree::TaxExemptionCertificate < Spree.base_classhas_one_attached :document # uploaded certificate PDF/imagescope :active, -> { where(status: 'verified').where('expires_at IS NULL OR expires_at > ?', Time.current) }- scope :for_zone, ->(zone) { where(zone: zone).or(where(zone: nil)) }+ scope :for_address, ->(address) {+ where(country: [address.country, nil])+ .where(state: [address.state, nil])+ }def active?status == 'verified' && (expires_at.nil? || expires_at > Time.current)@@ -482,11 +486,11 @@ def exempt?(order)return true if order.company&.tax_exempt?return true if order.company_location&.tax_exempt?- # Check for active certificate covering the order's tax zone+ # Check for active certificate covering the order's tax addressif order.companyorder.company.tax_exemption_certificates.active- .for_zone(order.tax_zone)+ .for_address(order.tax_address).exists?elsefalse@@ -518,7 +522,8 @@ class CreateSpreeTaxExemptionCertificates < ActiveRecord::Migration[7.2]def changecreate_table :spree_tax_exemption_certificates do |t|t.references :company, null: false- t.references :zone+ t.references :country+ t.references :statet.string :certificate_number, null: falset.string :status, null: false, default: 'pending't.datetime :issued_at@@ -545,7 +550,31 @@ When `6.0-split-adjustments.md` ships:- Adjuster reads from `tax_lines` instead of `adjustments.tax`- `TaxRate.adjust` internally updated to create TaxLines-### Phase 5: Reference external provider (separate gem)+### Phase 5: Drop Zone model + data migration++Coordinate with `6.0-delivery-rate-provider.md` — both plans share this migration:++```ruby+# rake spree:migrate_zones+#+# For each Zone used by TaxRate:+# Extract country/state from ZoneMembers → set TaxRate.country_id / TaxRate.state_id directly+# (Zone with multiple countries = one TaxRate per country)+#+# For each Zone used by ShippingMethod (DeliveryMethod):+# Create DeliveryZone + DeliveryZoneMembers from ZoneMembers+#+# After migration:+# Drop spree_zones and spree_zone_members tables+# Remove Zone, ZoneMember models+```++- Add `country_id` and `state_id` columns to `spree_tax_rates`+- Run data migration rake task+- Remove `zone_id` FK from TaxRate+- Drop `spree_zones` and `spree_zone_members` tables (shared with Delivery Rate Provider plan)++### Phase 6: Reference external provider (separate gem)- Create `spree_tax_avalara` gem as reference implementation- Implements estimate/commit/void/refund against Avalara AvaTax APIdiff --git a/docs/plans/6.0-typed-stock-movements.md b/docs/plans/6.0-typed-stock-movements.mdindex d1fea89834..48df07a891 100644--- a/docs/plans/6.0-typed-stock-movements.md+++ b/docs/plans/6.0-typed-stock-movements.md@@ -2,9 +2,9 @@**Status:** Draft**Target:** Spree 6.0-**Depends on:** Stock Reservations (6.0-stock-reservations.md), Remove Master Variant (6.0-remove-master-variant.md)+**Depends on:** Stock Reservations (6.0-stock-reservations.md), Remove Master Variant (6.0-remove-master-variant.md), Cart/Order Split (6.0-cart-order-split.md)**Author:** Damian + Claude-**Last updated:** 2026-03-16+**Last updated:** 2026-03-22## Summary