Upgrading to Spree 6.0

• Cart and Order are separate models. Spree::Cart owns shopping and checkout; completing checkout copies the cart into an immutable Spree::Order. The order state machine is gone.
• Checkout has no server-side state machine. Steps are advisory metadata for your frontend; the backend enforces exactly one hard gate — completion.
• Adjustments are typed rows. The polymorphic Spree::Adjustment is replaced by Spree::TaxLine, Spree::Discount and Spree::Fee.
• Master Variant is gone, replaced by a default_variant_id foreign key on Spree::Product. There’s no hidden/dummy Variant created now, the default variant is a real Variant with its own SKU, price, stock, etc.
• Fulfillment vocabulary. Shipment → Fulfillment, ShippingMethod → DeliveryMethod, Zone → DeliveryZone, with a pluggable FulfillmentProvider strategy.
• Two-tier services. Plain services in app/services, plus Spree::Workflow classes in app/workflows for the curated multi-step flows (completion, cancellation, recalculation) — with named steps, instrumentation and extension hooks.

1. Update the Ruby gems
2. Run database migrations
3. Run data backfills — convert your existing records into the new schema
4. Review behavioral changes — this release changes runtime behavior, not just schema

​

How to upgrade

spree upgrade

# cd backend if you're in the monorepo root
bundle update
bundle exec rake spree:install:migrations && bin/rails db:migrate
bundle exec rake spree:upgrade

# Gemfile
gem 'spree_dashboard'

​

What the upgrade does

​

Store preferences as JSON

spree rake spree:upgrade:preferences_json
spree rake spree:upgrade:encrypt_secret_preferences

bundle exec rake spree:upgrade:preferences_json
bundle exec rake spree:upgrade:encrypt_secret_preferences

​

Convert incomplete orders into carts

bundle exec rake spree:migrate_incomplete_orders_to_carts

​

Convert legacy adjustments into typed rows

bundle exec rake spree:migrate_adjustments_to_typed_rows

​

Backfill fulfillment and delivery naming

bundle exec rake spree:migrate_shipping_to_delivery
bundle exec rake spree:migrate_zones_to_delivery_zones
bundle exec rake spree:migrate_calculator_bounds_to_delivery_method_rules

​

Remove master variants

bundle exec rake spree:remove_master_variant

​

Categories and collections

bundle exec rake spree:migrate_taxons_to_categories_and_collections

​

Move rich text out of Action Text

bundle exec rake spree:migrate_rich_text_to_columns

# config/initializers/spree.rb
Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td]
Spree::RichTextSanitizer.allowed_attributes += %w[colspan rowspan]

require 'action_text/engine'
require 'action_cable/engine'

​

Backfill order coupon codes

bundle exec rake spree:backfill_order_coupon_codes

​

Markets on orders

bundle exec rake spree:markets:migrate_checkout_zones
bundle exec rake spree:backfill_order_markets

​

Fill in the stock level counters

bundle exec rake spree:stock:recount_levels

​

Name who performed past actions

bundle exec rake spree:upgrade:backfill_actor_types

​

Move users onto the Customer and AdminUser models

bundle exec rake spree:upgrade:migrate_users_to_customers

​

Name countries and states by ISO code

bundle exec rake spree:upgrade:migrate_country_state_codes

​

Record which store owns every uploaded file

bundle exec rake spree:uploads:assign_stores

​

Enable Active Record encryption

%i[primary_key deterministic_key key_derivation_salt].each do |key|
  value = ENV["ACTIVE_RECORD_ENCRYPTION_#{key.upcase}"].presence ||
    credentials.dig(:active_record_encryption, key).presence
  config.active_record.encryption[key] = value if value
end

spree encryption init           # adds a set to your project's .env (never overwrites existing keys)
spree encryption init --print   # prints a set for your production host

bin/rails db:encryption:init    # prints a set; put it in env vars or encrypted credentials

​

Preferences are stored as JSON

• The raw preferences hash has string keys. It still answers to symbols (calculator.preferences[:amount]), but preferences.keys returns strings. Decimals sit in it as exact strings ("9.99"); read them through preferred_*, which returns a BigDecimal.
• Secrets are not in preferences. Preferences declared :password live in the encrypted secret_preferences column. Read them with preferred_* or get_preference. A secret you assign as part of a whole hash (update(preferences: { secret_key: ... })) is moved there when the record is saved. To declare a secret on a model other than a payment method or an integration, see Secret preferences.
• Your own preference tables need a JSON column. The migration converts every table a model storing Spree preferences reads, including your application’s own; a table another library owns is left alone. A new table should use t.jsonb :preferences on PostgreSQL, the default database (t.json on MySQL or SQLite).
• Tiered calculators take a list of tiers. Spree::Calculator::TieredPercent and TieredFlatRate store tiers as a list instead of a hash keyed by threshold, in Ruby and in the Admin API. The migration converts existing calculators.
  // Before
  { "tiers": { "100": 10, "250": 15 } }
  // After
  { "tiers": [{ "threshold": "100", "value": "10" }, { "threshold": "250", "value": "15" }] }
  
  value is a percentage for TieredPercent and an amount for TieredFlatRate.
• Spree no longer allows extra classes in YAML columns. It used to add Symbol, BigDecimal and a few time classes to config.active_record.yaml_column_permitted_classes. If your application serializes its own columns as YAML with those classes, add them in config/application.rb yourself.
• Preference change methods follow Rails’ naming. Each preference is a Rails store accessor, so preferred_<name>_changed?, preferred_<name>_change and preferred_<name>_was work as before, while the after-save forms are Rails’ own: saved_change_to_preferred_<name>? replaces preferred_<name>_previously_changed?, saved_change_to_preferred_<name> replaces preferred_<name>_previous_change, and preferred_<name>_before_last_save replaces preferred_<name>_previously_was.
• Per-preference helper methods are gone. Use preference_type(:name), preference_default(:name) and preference_deprecated(:name) instead of preferred_<name>_type, preferred_<name>_default and preferred_<name>_deprecated. clear_preferences, restore_preferences_for, preferences_of_type, the class methods preference_getter_method, preference_setter_method and prefers_query_method, Spree::Preferences::ScopedStore, Spree::Preferences::Store and the Spree::Preference model are removed.
• The spree_preferences table is dropped. The installation id it held is not carried over: the default store generates a new one the next time it is saved. Rows an application wrote there itself are dropped with it: copy any you need before upgrading.
• Preferences live only on models. Spree::Preferences::Preferable is included by Spree::Base and needs a preferences JSON column; including it in a plain Ruby class is no longer supported. A hash stored inside a preference comes back with string keys.
• A record whose preferences still hold YAML cannot be read. The migration converts every row, so this only happens to rows written by older code after it ran. Run spree rake spree:upgrade:preferences_json (bundle exec rake spree:upgrade:preferences_json without the Spree CLI) to convert it.

​

The Cart/Order split

• Spree::Cart (spree_carts, prefixed IDs cart_...) owns the shopping and checkout phase: line items, addresses, payments-in-progress, delivery proposals, promotions, stock reservations. Carts have no status column — completed_at is the only lifecycle marker.
• Spree::Order is created by completion — the cart is copied into it (line items, fulfillments, addresses, typed money rows — copies, never shared rows). Orders carry status (draft / placed / canceled) and are money-frozen once placed.

• Completed carts are read-only. The cart is retained after completion (abandonment analytics, idempotent replay) but rejects every write. Post-checkout life belongs to the order.
• Completion is idempotent. Spree::Carts::Complete guards with a unique spree_orders.cart_id index and a completing_at lock: a double-clicked Place Order returns the same order, a crashed completion replays safely, and a pre-capture payment failure rolls the draft order back and re-points payments to the cart.
• The guest token carries over from cart to order, so confirmation pages keep working with the credential the guest already holds.
• Dual concrete FKs, not polymorphism. Records owned by either side (LineItem, Fulfillment, TaxLine, Discount, Fee, Payment, StockReservation) carry nullable cart_id + order_id with an exactly-one rule and an #owner method. Code that assumed line_item.order is always present must read line_item.owner.
• Shared model surface lives in Spree::Purchase::* concerns (addresses, taxation, store credits, gift cards, digital items, payment processing, market/channel/currency/locale resolution) — included by both Cart and Order. Decorators targeting Spree::Order methods that moved should decorate the concern or the new owner.

​

Checkout without a state machine

• Steps are advisory. cart.checkout_steps, current_checkout_step and completed_checkout_steps are derived from cart data — there is no stored step and no server-side sequencing. Clients may write any checkout field in any order. “Steps” are a grouping label telling your frontend which page an unmet requirement belongs to.
• One hard gate. Spree::Carts::Complete is the only place checkout is enforced. It validates the full requirement battery (line items, email, addresses, delivery selection, payment coverage, per-item stock, discontinued products, guest policy) and returns structured { step, field, code, message } errors.
• Spree::Checkout::Registry is the extension surface. One declaration serves both the advisory feed and the completion gate:

# config/initializers/spree.rb
Spree::Checkout::Registry.add_requirement(
  step: :payment,
  field: :po_number,
  message: 'PO number is required',
  satisfied: ->(cart) { cart.metadata['po_number'].present? },
  applicable: ->(cart) { cart.customer.present? }
)

• The API requirements array now carries a stable code on every entry (email_required, out_of_stock, guest_checkout_not_allowed, …). Additive change — existing consumers keep working.
• The delivery requirement is keyed by its code, delivery_method_required. Its entry is { step: 'delivery', field: 'shipping_method', code: 'delivery_method_required' }. The field keeps its 5.6 name until 6.1, when it becomes delivery_method, so a 5.6 storefront that matches the field keeps working. Match the code instead, which does not change. The spree.checkout_requirements.shipping_method_required translation key was renamed to spree.checkout_requirements.delivery_method_required — override it under the new key.
• “Logic between steps” has no backend home by design. Side effects hang off data writes (workflow hooks such as Carts::Complete’s before_finalize and Carts::AddItem’s after_item_added) and events (cart.updated, order.placed) — not step transitions.

​

Statuses: derived, then persisted

• Nothing else writes these columns. If your code assigned order.payment_state = 'paid', replace it with the underlying records (payments/refunds) and let the recompute derive.
• The payment_status domain gains overcharged and voided; fulfillment_status includes backorder. Money comparisons are quantized to currency precision and refunds are netted before comparing.
• A completed payment updates only the payment side of the ledger (payment_total + statuses). It never re-sums item or adjustment money.
• Fulfillment is a fact: a fulfilled fulfillment is never downgraded by later payment-state changes.

​

Recalculation on write

• Spree::Carts::RecalculateTotals is the single totals seam: money inputs, typed-row regeneration (promotions via the winner-only adjuster, tax via the market’s tax provider, falling back to Spree.default_tax_provider), folding and one persist. It runs on the writes that matter — item changes, address/market changes (which also re-price items and rebuild delivery proposals) — not on step transitions.
• Promotion eligibility is evaluated against current totals in the same recalculation — a cart crossing a coupon threshold gets the discount on that recalculation, not the next one.
• Completed orders are money-frozen. Typed rows are never regenerated post-placement; recalculation only re-sums them. Post-placement money edits go through the explicit admin services (Orders::Discounts::*, Orders::Fees::*), which write rows and re-sum.
• Spree::OrderUpdater and Spree::CartUpdater remain as deprecated shells — every method warns and runs the full recalculation. Removed in 6.1.

​

Completion, in one workflow

• Order#finalize! is deprecated (removed in 6.1) and delegates to the workflow. Behavioral change: finalizing an already-completed order is now a no-op — the workflow halts idempotently instead of re-running side effects.
• Completion side effects moved out of the model. Newsletter subscription, checkout account creation and risk assessment run in the synchronous Spree::OrderPlacedSubscriber on the order.placed event. Decorators that patched finalize! should become event subscribers or before_finalize hook handlers.
• order.placed is the completion event. order.completed still fires as a deprecated alias for one release (webhook consumers should migrate; wildcard subscribers can dedupe on the deprecated_alias_of metadata marker).
• Order.register_update_hook no longer runs during completion.

​

Addresses

• Address writes deduplicate against the customer’s address book and promote checkout addresses to the customer’s defaults (quick-checkout wallet addresses excluded).
• ship_address_id= / bill_address_id= are ownership-guarded: an address not owned by the record’s customer resolves to nil.
• A signed-in customer entering checkout gets blank address slots auto-filled from their saved defaults.
• use_billing is deprecated (removed in 6.1): the shipping address is canonical — use use_shipping to copy ship → bill.
• The firstname, lastname and zipcode columns are renamed to first_name, last_name and postal_code. The API has used the new names since 5.4, but two things carried the old ones and now change: validation error keys (a client sending postal_code used to get its error back under zipcode) and Ransack filter keys (q[zipcode_cont] becomes q[postal_code_cont]). The old method names still read for one release. The Admin and Seller APIs no longer accept firstname and lastname in an address payload: send first_name and last_name.

​

Returns, exchanges and claims

​

No state machines

Spree::Return.add_status('inspecting', after: 'received')

​

Eligibility is a hook, not a validator chain

# config/initializers/spree.rb
Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')

# The same validator guards exchanges — swap it there too if your policy should cover them:
Spree.hooks.unregister('exchanges.create.validate', 'Spree::Returns::EligibilityValidator')
Spree.hooks.register('exchanges.create.validate', 'MyStore::ReturnPolicy')

​

Other behavioral changes

• Return#refunded_total counts store credits. Store credit is a separate ledger and never creates a Spree::Refund row, so the old sum reported zero for a store-credit refund.
• Order#outstanding_balance replaced its reimbursement term with refunds made for returns, claims and exchanges (returned_items_refund_total). Those refunds net out of payment_total, and adding them back is what keeps a refunded return from reading as a balance due. A refund made for nothing in return still reads as owed, as in 5.x.
• The reimbursement email is now Spree::ReturnMailer#refunded_email, sent on return.refunded (in the optional spree_emails gem, like the other transactional mail).
• Refund#originator points at the new records.
• Events are return.requested / .approved / .received / .refunded / .canceled, and the matching exchange.* and claim.* families.
• Digital downloads redirect instead of streaming. The download endpoint now answers 302 with a short-lived signed URL rather than sending the file bytes directly, so a large download no longer occupies a web worker. Clients that read the response body must follow redirects (most HTTP clients and every browser already do). The link’s own lifetime is unchanged; digital_asset_link_expire_time (default 300 seconds) — previously unused — now sets how long the signed URL stays valid, and is capped at one hour because that URL is a bearer credential. The signed URL is additionally clamped so it can never outlive the download link that issued it.
• Download limits can be set per asset. authorized_clicks and authorized_days on a digital asset override the store’s download settings; left blank, the store settings apply as before.
• A successful download publishes digital_link.downloaded, so downloads are visible to webhooks and subscribers for the first time.
• Customers are emailed their download links when the order is placed, from the new Spree::DigitalAssetMailer in the optional spree_emails gem. Hosts that already send their own download email should either suppress it (send_consumer_transactional_emails) or drop their own. The dashboard’s order page can re-send it.
• Digital assets are managed through the Admin API and dashboard, and signed-in customers can list everything they have bought at GET /api/v3/store/customers/me/digital_links.

​

Free-gift promotions price their own gift

​

Dependency injection changes

​

Cancelling an order is final

​

File uploads

production:
  purge_unattached_uploads:
    class: Spree::Uploads::PurgeUnattachedJob
    schedule: every day at 4am

​

Payment source IDs use the psrc_ prefix

​

Type values are short names, not class names

​

Preferences are typed in the API

​

Every event is declared

• notify_customer moved to metadata on order.placed, order.completed, order.canceled and order_group.completed. Read event.metadata['notify_customer'] in subscribers and metadata.notify_customer in webhook receivers.
• customer.anonymized carries the customer record; the store and the requester moved to metadata (store_id, requested_by_id).
• Purchase order, stock receipt, supplier and shipping label events carry a short payload — status, related record IDs and timestamps. Costs, notes, contact details and label files are read from the Admin API.
• saved_report.* no longer includes the author’s name.
• Subscribing an endpoint to customer.password_reset_requested needs the permission to manage customers. The staff and seller reset events are still never sent to webhooks.

​

Removed in 6.0

​

Custom fields replace metafields

• Visibility is a boolean. The tri-state display_on column collapses into storefront_visible. Definitions that were back_end become storefront_visible: false; everything else becomes true. The front_end-only value never meant hidden-from-staff and folds into true.
• Two columns are renamed. name becomes label, and metafield_type becomes field_type. Reading field_type returns the API token (short_text) rather than the Ruby class name; use field_type_class_name when you need the class.
• Rich-text values leave Action Text. Spree::CustomFields::RichText stores sanitized HTML in the same value column as every other type, so reading value returns a String rather than an ActionText::RichText. Existing bodies are copied across by the migration; the Action Text rows stay behind as a rollback path until 6.1. Code calling custom_field.value.body should read value directly.

​

Unused services are gone

​

Products no longer touch their categories

​

The Legacy order-routing strategy is gone

​

belongs_to is required by default

• Your own models change with it. Anything inheriting from Spree::Base picks up the new default, so an association that is legitimately blank now needs optional: true on it. A model that relied on the old behaviour will start failing validation until you say which associations are optional.
• The message changed. A missing association reports "must exist" rather than "can't be blank". Code that matches on the old wording — a test, or a client reading details out of a 422 — needs updating.

​

Store.default no longer builds a store

​

The DefaultPrice concern is gone — price_in / set_price is the interface

• Ransack: default_price is no longer a searchable association on Variant; query prices instead.
• Prices in permitted params: the dead :price and :compare_at_price entries are gone. Prices were already written as nested prices: [{ amount:, currency: }] under variants — the top-level keys had no writer behind them. (Spree::PermittedAttributes itself is removed in 6.0 — see below.)
• Prices are written as numbers or canonical decimal strings: set_price(currency, '1599.99'). A localized string such as '1,599.99' raises Spree::Money::InvalidFormat (see Money).
• The variant validation that inferred a missing price from the product’s default variant is gone. Set prices explicitly (the product and variant factories already do).

​

Spree::PermittedAttributes is removed

​

How to migrate

grep -rn "PermittedAttributes" app config lib
grep -rnE "permitted_[[:alnum:]_]+_attributes" app config lib

# Before
Spree::PermittedAttributes.product_attributes << :brand_id

# After
Spree::Product.additional_permitted_attributes += [:brand_id]

class BrandsController < Spree::Api::V3::Admin::ResourceController
  protected

  def model_class
    Spree::Brand
  end

  # Before: no such method — the base class inferred `brand_attributes`
  # from the model name. Now you say what you accept.
  def resource_permitted_attributes
    [:name, :slug, :description]
  end
end

patch "/api/v3/admin/products/#{product.prefixed_id}",
      params: { brand_id: brand.id }, headers: headers

expect(product.reload.brand_id).to eq(brand.id)

​

StateChange and LogEntry are gone

​

Spree::Report is gone

​

Emails render from Liquid templates

• Subjects moved into the templates. Each template’s front matter holds its subject. Spree::BaseMailer#order_email_subject is removed.
• The mailer view helpers are removed. Spree::MailHelper (name_for), Spree::BaseHelper (spree_storefront_resource_url), Spree::FulfillmentHelper and Spree::DigitalAssetHelper are gone, and so are spree_image_tag and spree_asset_aspect_ratio from Spree::ImagesHelper (spree_image_url stays). Templates get the same values as serializer fields, such as order.customer_name and item.url.
• Every email has a plain-text part, generated from the HTML. Seven emails that had none now have one.
• Alba moved into spree_core, with its configuration, so core’s staff emails render in installations without spree_api.
• Your own mailers keep working. A mailer that inherits Spree::BaseMailer and calls mail with its own ERB views is wrapped in the new email layout, and the spree/shared/mailer_hero and mailer_button partials remain for its views. See Your own mailers.

​

Money

• Numbers are no longer parsed by locale. Price, variant, payment, refund, store credit, gift card, discount and fee amounts take a number or a canonical decimal string ("1234.56"); any other text raises Spree::Money::InvalidFormat, which the API answers with invalid_money_format. Before 6.0 they were re-read under the request’s language, so a store whose language writes a comma decimal (Dutch, German, French) saved the dashboard’s 49.50 as 4950, and an unchanged price grew tenfold on each save. Send canonical decimal strings ("1234.56") and convert localized input in the client. Spree::LocalizedNumber still works with a warning until 6.1. If your prices were saved in a comma-decimal store before upgrading, check them.
• Rounding follows the currency. Taxes, percentage discounts, promotion splits and shipping markups round to the currency’s own decimal places from the ISO 4217 table: whole yen, three decimals for dinar. Two-decimal currencies are unchanged. Open carts in other currencies may change by less than one minor unit the next time they are recalculated. Placed orders do not change. Spree now gives the Hungarian forint two decimal places, as ISO 4217 does.
• Money on the API is written to each currency’s decimals. Every amount in the Store, Admin and Seller APIs, and so in webhook payloads and email variables, is a decimal string with exactly its currency’s decimal places: "10.00" (was "10.0"), "1000" in yen (was "1000.0"), "1.500" in dinar. Unit prices keep up to four decimals. Fields that were JSON numbers are now strings: cart.order_minimum and order_minimum_shortfall, the product filter price range min/max, report money metrics and percentages, and the store’s default_minimum_payout_amount and default_commission_tax_rate. Clients comparing these strings, or parsing them as numbers, should switch to exact decimal arithmetic; the SDKs export sumMoney, subtractMoney, multiplyMoney, compareMoney and isZeroMoney.
• Admin and Seller writes refuse JSON numbers for money. Amounts and rates, including those inside preferences, must be canonical decimal strings ("19.99"). A number, a localized or grouped string, or more decimals than the field holds is answered with 422 and invalid_money_format, naming the field.
• Amounts may not carry more decimals than they can keep. Now that the columns hold four decimals, the database no longer rounds away a fraction of a cent, so a payment, refund, store credit, gift card, fee or discount with more decimals than its currency has (10.0049 dollars) fails validation with too_many_decimals. Unit prices and cost prices allow four, tax rates five decimals of the fraction (rate_percent "7.125", not "7.1255"), and price list percentages three. Round in your own code before saving. A manual order discount’s value and a commission rate’s value are read as strictly as other money fields.
• The Admin and Seller APIs no longer return display_* money fields. Responses carry the amount ("29.99") with its currency, and the client formats it in the reader’s own language. Before 6.0 the server formatted a copy in the request’s language, which could disagree with the editable amount beside it. Format with Intl.NumberFormat or your platform’s equivalent. The Store API and webhook payloads keep their display_* money fields until 6.1, marked deprecated in the API reference and the SDK types; format the amount beside each one instead (total for display_total). Labels such as display_name are unchanged.
• Money preferences have their own type. Calculator, rule and store preferences holding an amount (amount, first_item, minimal_amount, amount_min, min_amount, default_minimum_payout_amount and the like) are declared :money instead of :decimal, report money in preference_schema, and are written with the decimals of the calculator’s currency ("12.50" rather than "12.5"). Declare your own extensions’ amounts with :money so the dashboard shows their currency. A :decimal or :money preference now refuses text such as "1,599.99" instead of reading it as 1. Money preferences are checked by their type on write: a value that is not a decimal string, or has more decimals than its currency, is refused with invalid_preferences and a pointer to the field (/calculator/preferences/amount), rather than invalid_money_format.
• Rates are decimal strings, and tax rates are renamed. Rates and percentages read and write as strings without trailing zeros. A tax rate’s amount (a fraction) is now rate, and amount_percentage is rate_percent; Spree::TaxRate#amount_percentage keeps working with a warning until 6.1.
• amount_in_cents and compare_at_amount_in_cents are deprecated on Store API prices and price history, and removed in 6.1. They still hold the amount in hundredths, which is wrong for currencies without two decimals. Read amount, and each currency’s decimal_places (new on GET /api/v3/store/currencies) if you need minor units. The Admin and Seller APIs no longer return them.
• Money columns widen to decimal(19,4). They now hold a Kuwaiti dinar’s third decimal, unit prices below a cent (0.0125), and very large amounts in currencies like the Vietnamese dong. No stored value changes. Totals, payments and refunds are still rounded to the currency’s decimals; only unit prices (price, compare_at_amount, cost_price, unit_cost) keep up to four. The migration rewrites each money table while it runs, which locks spree_orders, spree_line_items and spree_adjustments for as long as that takes. If you cannot take that lock, widen those columns online first (add a decimal(19,4) shadow column, backfill it in batches, swap it in), and the migration skips any column already at (19,4). Extensions with their own money tables, such as spree_stripe_payment_intents from the standalone Stripe gem, should widen theirs the same way.
• Payment gateways receive the amount with its currency. authorize, purchase, capture and credit are called with a Spree::Money (amount and currency) instead of an integer in hundredths, which was wrong for yen and dinar. A gateway opts in with self.accepts_money_amounts = true and converts the amount to its provider’s unit (Stripe’s rules live in SpreeStripe::Units). A gateway that has not opted in still receives hundredths, with a deprecation warning, until 6.1. Spree.payment_capture_workflow.call(amount:) takes the amount in the currency’s own units; an Integer is still read as hundredths, with a warning.
• Stripe refuses amounts it cannot take. Stripe charges three-decimal currencies (Bahraini, Jordanian, Kuwaiti and Omani dinar, Tunisian dinar) only in steps of 0.010, and pays out Hungarian forint and New Taiwan dollars only in whole units. spree_stripe now raises a gateway error naming the rule, rather than rounding to a sum other than the one the order records.
• Capture records in yen and dinar written before 6.0 may be wrong. A capture in a currency without two decimals could be recorded in the wrong unit: 100 times too much in yen, a tenth in dinar. New captures are recorded exactly. To list the old records, writing nothing, run:

spree rake spree:money:audit_capture_events

bundle exec rake spree:money:audit_capture_events

​

Locale codes come from a fixed list

​

Translations ship with Spree

• Remove spree_i18n from your Gemfile. Its last release is empty and only warns. Older releases load their own, larger files over Spree’s.
• Use I18n.t with the full key. Spree.t(:free) becomes I18n.t('spree.free'), and Spree.t(:x, scope: :api) becomes I18n.t('spree.api.x'). Spree.t keeps working until 6.1 with a deprecation warning.
• A missing key is plain text. Spree.t used to return a <span class="translation_missing"> HTML element for a key it could not find. It now returns what I18n.t returns.
• Untranslated keys fall back to English. Spree’s translations are complete only in English. With config.i18n.fallbacks = true, as Rails generates for production, Spree adds English after your default locale. An app that sets its own fallback list or turns fallbacks off keeps its choice.
• spree/testing_support/i18n does nothing. Set config.i18n.raise_on_missing_translations = true in your test environment to catch missing keys.
• Kaminari is no longer loaded. It came in through spree_i18n. Spree paginates with Pagy, and the Spree::Base.page bridge for a custom Kaminari page_method_name is gone. Add kaminari to your Gemfile if your own code uses it.
• Translations for removed screens are gone. Keys used only by the old admin and storefront, and by the v2 API, were removed. If your code reads one, copy it into your app’s locale files.

​

Deprecated in 6.0, removed in 6.1

​

Meilisearch moved to its own gem

# Gemfile
gem 'spree_meilisearch'

# config/initializers/spree.rb
Spree.search_provider = 'SpreeMeilisearch::SearchProvider'

​

Staff permissions: roles are data

# db/seeds.rb — "roles as code" is plain ActiveRecord now
Spree::Store.default.roles.find_or_create_by!(name: 'support')
  .update!(permissions: %w[read_orders read_customers])

Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> { [SpreeReviews::Review] })

• JWT staff pass the same per-controller key gate as secret keys. A request whose principal lacks <read|write>_<resource> gets a 403 with details.required_permission naming the missing key.
• Staff endpoints moved out of the settings scope. /admin_users, /invitations, and /roles now require the new read_staff / write_staff scopes; secret keys minted with settings before 6.0 lose those endpoints. /countries and /locales became scope-exempt reference data.

​

Rich-text fields read as plain text plus HTML

• Hydrate editors from *_html. The plain field is tag-stripped, so binding an editor to description and saving it back would flatten the markup on every save.
• The field holds HTML. That is true of every writer — the Admin API, CSV import, the console — so send markup, not plain text with newlines in it.

​

Upgrading a storefront

1. Upgrade @spree/sdk to 2.x and run the type checker (pnpm exec tsc --noEmit, or your framework’s build).
2. Match each error against the table below and apply its fix. Fix values where they come from (a context, a form, an API response), not with a cast at each call site.
3. Search for the deprecated names in the deprecated fields section and switch them, even where nothing fails to compile.

​

Upgrade with a coding agent

Upgrade this storefront from Spree 5.6 to Spree 6.0: move it to @spree/sdk 2.x and remove every use of a Store API field, SDK name or webhook event that 6.0 deprecates for removal in 6.1.

Read the "Upgrading a storefront" section of the upgrade guide first and keep it open (plain-text version):
https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0.md

Work on a new branch. Steps:

1. Install the latest @spree/sdk 2.x and run the type checker. Fix each error at the place the value comes from (a context, a form, a data loader, an API response), not with a cast at each call site. The guide's table maps each error to its fix.

2. Go through the guide's "Deprecated fields still work until 6.1" table and replace every entry, even where nothing fails to compile. Search the code for each name. When you finish, none of them may remain.

3. Money:
   - Replace display_* fields with formatMoney(amount, currency, locale) from @spree/sdk, in the reader's language. Pass { unitPrice: true } for unit prices (line item price, product and variant prices), which can carry up to four decimals.
   - Payments, fulfillments, delivery rates and applied promotions carry no currency. Use the currency of the cart or order they belong to.
   - formatMoney returns an empty string, never null, for a missing amount. Fallbacks written as `formatMoney(...) ?? "—"` never trigger; use `||`. Check every place that tested a display_* value for truthiness.
   - Amounts are decimal strings and can be null when the store hides prices. Compare them with compareMoney or isZeroMoney. Never compare amount_in_cents, and never parse money into a float for arithmetic.
   - A delivery rate whose cost is null has no price yet (a freight quote, for example). Do not show it as free, in a wallet payment sheet or anywhere else.

4. Addresses: read and write country_code and state_code. If your form state uses the old names, rename the form fields to match the API. Type a cart's addresses as CartAddressParams and address book writes as AddressCreateParams or AddressUpdateParams. Country codes typed by a person or sent by a wallet are plain strings; convert them to CountryCode once, where they enter your code.

5. Names: name countries, currencies and languages in the reader's language with Intl.DisplayNames, and sort them with Intl.Collator. Create one DisplayNames object per locale and reuse it; do not build one on every render or inside a sort comparison.

6. Order groups: carts.complete() and orders.get() return Order | OrderGroup. In a marketplace, a cart holding several sellers' goods becomes one order per seller under a group. Narrow with isOrderGroup. Read totals, payments and addresses from the group, and items and fulfillments from group.orders. Remove casts that hide this, such as `as unknown as Cart`. Report a group as one purchase in analytics.

7. Statuses: map the old values to the new ones using the guide's "Status values changed" tables. That covers fulfillment status, and an order's fulfillment_status and payment_status. Keep the old values mapped as well, because orders saved before the upgrade can still carry them. Add a translated label for every new value in every language the storefront ships. A status with no translation should show its own words, not a raw translation key.

8. Gift cards and store credit: store_credit_total no longer includes what a gift card paid. Show the gift card and store credit rows independently, not one or the other.

9. Webhooks: handle order.placed in place of order.completed, and order.fulfilled in place of order.shipped. Fulfillment status "shipped" is now "fulfilled" (or "delivered"). Type handlers by event name: WebhookEvent<"order.placed">. Update any documentation or environment examples that list the subscribed events.

10. Filters: the price filter's min and max are decimal strings. Send amount filters as strings ("20.00"). Narrow a sort read from the URL to ProductSort where it is read. Match the cart's delivery requirement by its code, delivery_method_required.

11. Update test fixtures and mocks to the 6.0 shapes. Run the type checker, linter, unit tests and end-to-end tests, and make them all pass.

Do not change behaviour beyond what the upgrade requires, and keep every user-visible string translated. When done, list what you changed, and anything that needs a person, such as subscribing the webhook endpoint to the new event names before deploying.

​

List filters and sort are typed

• A sort value read from the URL is a plain string. Narrow it where you read it; the API still validates the value at runtime:
  src/lib/utils/product-query.ts

  import type { ProductListParams, ProductSort } from '@spree/sdk'
  
  params.sort = filters.sortBy as ProductSort
  
• Filters your backend adds are compile errors until you declare them. The published types list only the filters Spree itself declares. Any filter or scope your backend adds (through Spree.ransack.add_attribute, add_scope or a model decorator) still works in the API, but TypeScript rejects the key. Generate the declarations from your app, and run the command again whenever a filter changes:
  spree filters types
  
  It writes a declaration file into each app under apps/, for the SDK that app uses (the storefront, the dashboard and the seller panel). For a one-off filter, send it inside q instead (list({ q: { erp_id_eq: 'ERP-1' } })), which is not type checked. See using your own filters from TypeScript for both, and for declaring filters by hand.
• Amount filters take decimal strings. price_gte, price_lte and the other money filters are typed as strings, like every money value in 6.0. Send '20.00', not 20.
• Prefer search. Products, categories and collections take q[search] (the SDK’s search key), which matches more than name_cont. See which filters an endpoint accepts.

​

Completing a cart can return an order group

import { isOrderGroup } from '@spree/sdk'

const result = await client.carts.complete(cartId)
const orders = isOrderGroup(result) ? result.orders : [result]

​

Store credit no longer includes gift cards

​

Request types match the API

• A cart’s addresses take CartAddressParams, not AddressParams. AddressParams is the customer’s address book entry. A cart address also takes id (an address from the book) and quick_checkout (relaxed validation for a wallet’s partial address):
  src/lib/data/express-checkout-flow.ts

  import type { CartAddressParams } from '@spree/sdk'
  
  const shipping_address: CartAddressParams = { ...walletAddress, quick_checkout: true }
  await client.carts.update(cartId, { shipping_address })
  
• Some requirements relaxed. AddLineItemParams.quantity is optional (it defaults to 1), and RegisterParams.password_confirmation is optional.
• Renamed types keep their old names until 6.1, marked deprecated: LineItemInput is LineItemInputParams. AddressParams and CompanyAddressParams are split by action into AddressCreateParams / AddressUpdateParams and CompanyAddressCreateParams / CompanyAddressUpdateParams: creating requires the name, street, city and country, and updating takes any of them.

​

Country and currency codes are typed

import type { CountryCode, CurrencyCode } from '@spree/sdk'

interface StoreContextValue {
  currency: CurrencyCode
  country: CountryCode
}

const country = market.country_codes.find((code) => code === params.country.toUpperCase())

​

Money can be null

​

Store credit amounts are decimal strings

await client.carts.storeCredits.apply(cartId, '25.00', options) // not 25

​

The price filter’s range is text

import type { PriceRangeFilter } from '@spree/sdk'

const range = filters.find((filter): filter is PriceRangeFilter => filter.type === 'price_range')
const slider = range && { min: Number(range.min), max: Number(range.max) } // display only

​

Status values changed

​

Deprecated fields still work until 6.1

​

Other Store API changes to check

​

For extension authors

• Don’t reach for model business methods from services — 6.0 code style writes behavior inline in service/workflow steps; models keep data, validations, predicates and persistence primitives. Extensions patching removed model methods (finalize! internals, updater hooks) should move to workflow hooks (Spree.hooks.register('carts.complete.before_finalize') { |flow| ... } — handlers receive the workflow instance) or event subscribers.
• Store-scoped data is single-owner. Product, Promotion and PaymentMethod belongs_to :store; the stores: [...] writers are gone, they will work until 6.1 release with a deprecation warning
• The Store API v3 contract is stable across the split — cart endpoints keep their shapes; requirements gains code (and renames the delivery entry’s field/code to delivery_method, see above), and serializer number on carts is bridged as described above.