This release includes a huge number of fixes and improvements from the Spree community! 🌟

Highlights

New CSV importer

Importer now runs in parallel, greatly shortening the time required to import large CSV files (e.g., 100k rows).

New payment integrations

Adyen and PayPal are now officially available, and both are now supported by Storefront out of the box!

Products API improvements

Products API can now easily handle a large collection of SKUs (100k+) with great performance, both with database and Meilisearch.

Other changes

Core

• Fix Carmen deprecation warning for Rails 8.2 compatibility by @damianlegawiec in https://github.com/spree/spree/pull/13917
• Fix duplicate event logging across Zeitwerk reloads by @damianlegawiec in https://github.com/spree/spree/pull/13922
• Fix error when creating promo coupon code with blank expiration date by @KacperMekarski in https://github.com/spree/spree/pull/13925
• Fix nil errors when trying to call Address#country_iso without coun… by @damianlegawiec in https://github.com/spree/spree/pull/13927
• Consolidate pagy dependency to spree_core by @damianlegawiec in https://github.com/spree/spree/pull/13931
• Move CreditCard/PaymentSource post-destroy cleanup to models/concern by @damianlegawiec in https://github.com/spree/spree/pull/13941
• Parallel CSV import processing for large files by @damianlegawiec in https://github.com/spree/spree/pull/13944
• Fix PostgreSQL volume mount path in docker-compose by @damianlegawiec in https://github.com/spree/spree/pull/13947
• Add 30s delay to AutoMatchTaxonsJob by @damianlegawiec in https://github.com/spree/spree/pull/13956
• Fix applying gift cards in a multi-store scenario by @mad-eel in https://github.com/spree/spree/pull/13958

API

• Fix FulfillmentSerializer crash when line item is deleted by @damianlegawiec in https://github.com/spree/spree/pull/13918
• fix changing shipping rate when gift card is applied by @KacperMekarski in https://github.com/spree/spree/pull/13928
• Allow payment session lookup by external_id by @damianlegawiec in https://github.com/spree/spree/pull/13935
• Fixed Payment Sessions API concurrency issues by @damianlegawiec in https://github.com/spree/spree/pull/13938
• Improve performance of Products API with database adapter for large S… by @damianlegawiec in https://github.com/spree/spree/pull/13945

Admin

• Use Spree::Money instance correctly as an argument for money column type by @KacperMekarski in https://github.com/spree/spree/pull/13924
• Paginate option values in admin option type form by @damianlegawiec in https://github.com/spree/spree/pull/13949

Documentation

• How-to Guide: Set Up Multiple languages by @jaburghes in https://github.com/spree/spree/pull/13923
• Update PayPal setup guide by @jaburghes in https://github.com/spree/spree/pull/13933
• Updated Adyen setup guide by @jaburghes in https://github.com/spree/spree/pull/13934
• improve CONTRIBUTING guide by @damianlegawiec in https://github.com/spree/spree/pull/13959

Installation

npx create-spree-app@latest my-store

Updating

1. Update gems

bundle update

2. Run DB migrations

This release includes a small database migration as well:

bin/rake spree:install:migrations
bin/rails db:migrate

Feedback / Support

Join our Discord server to chat with Spree core team members and other Spree developers!

Full Changelog: https://github.com/spree/spree/compare/v5.4.1...v5.4.2

What's Changed

• Added ability to extend SDK, plus improved documentation and tutorial by @damianlegawiec in https://github.com/spree/spree/pull/13913
• Added missing totals for DeliveryRate and Fulfillment by @damianlegawiec in https://github.com/spree/spree/pull/13916

Full Changelog: https://github.com/spree/spree/compare/@spree/[email protected]...@spree/[email protected]

What's Changed

Core

• Fix promotion usage count double-counting with multiple actions by @55728 in https://github.com/spree/spree/pull/13889
• Fix taxon permalink unique constraint violation on rename by @55728 in https://github.com/spree/spree/pull/13884
• Fix markets:migrate_checkout_zones failing with validation error by @agnieszkajacek in https://github.com/spree/spree/pull/13892
• Remove broken remove_transition that skips confirm step by @55728 in https://github.com/spree/spree/pull/13901
• Expand shipping zones and markets to additional continents by @damianlegawiec in https://github.com/spree/spree/pull/13898
• fix doubled order canceled event by @KacperMekarski in https://github.com/spree/spree/pull/13899
• Relax active_storage_validations version constraint by @damianlegawiec in https://github.com/spree/spree/pull/13915
• extract CSV stock location to make it editable in spree extensions by @KacperMekarski in https://github.com/spree/spree/pull/13914

API

• Add store resolution to webhook payments controller by @damianlegawiec in https://github.com/spree/spree/pull/13910
• Consolidate customer creation params and support current_password by @damianlegawiec in https://github.com/spree/spree/pull/13912
• Added missing totals for DeliveryRate and Fulfillment by @damianlegawiec in https://github.com/spree/spree/pull/13916

Admin

• Add return_quantity to permitted attributes for return items by @55728 in https://github.com/spree/spree/pull/13885
• Fix duplicate HTML ids in variant template price and stock inputs by @55728 in https://github.com/spree/spree/pull/13883
• Fix I18n.default_locale leak in Spree::Admin::BaseController spec by @55728 in https://github.com/spree/spree/pull/13905
• Fix admin datetime fields to respect store timezone by @55728 in https://github.com/spree/spree/pull/13900

Documentation

• Added user docs for translations and multi-currency imports by @jaburghes in https://github.com/spree/spree/pull/13896
• SDK docs fixes: use media instead of images and custom_fields i… by @damianlegawiec in https://github.com/spree/spree/pull/13906

New Contributors

• @55728 made their first contribution in https://github.com/spree/spree/pull/13889

Full Changelog: https://github.com/spree/spree/compare/v5.4.0...v5.4.1

@spree/sdk 1.0.0 — Official TypeScript SDK for Spree

The official TypeScript SDK for Spree Commerce Store API v3 is now stable!

@spree/sdk gives TypeScript and JavaScript developers a fully typed, ergonomic client for building storefronts on top of Spree. It ships as the recommended way to interact with the Store API - whether you're using the Next.js storefront, building your own, or integrating Spree into any frontend or mobile framework.

npm install @spree/sdk

Highlights

• Full Store API v3 coverage — products, cart, checkout, orders, payments, customer accounts, wishlists, categories, markets, and geography
• Payment Sessions API — provider-agnostic payment flow that works with Stripe, Adyen, PayPal, and any gateway through a single interface
• Markets support — multi-market resolution, per-market countries, automatic currency/locale handling
• Complete TypeScript types — generated from API serializers, covering all Store API resources, request params, and response shapes
• Three auth modes — publishable key (guest), JWT (authenticated customer), and order token (guest checkout)
• Resource builder pattern — intuitive nested resources (client.store.orders.lineItems.create(...))
• Custom fetch support — bring your own fetch implementation for SSR, edge runtimes, or testing
• Structured error handling — typed SpreeError with status codes, error codes, and validation details
• Dual CJS + ESM bundles — works everywhere via tsup
• Tested with MSW — network-level API mocking with Vitest and E2E against real Spree instance

Quickstart

import { createClient } from '@spree/sdk';

const client = createClient({
  baseUrl: 'https://demo.spreecommerce.org',
  publishableKey: 'pk_xxx',
});

const products = await client.products.list({
  limit: 10,
  expand: ['variants'],
  fields: ['name', 'price', 'slug']
});

We're excited to announce Spree 5.4 — a generational release that transforms Spree into a modern, API-first commerce platform accessible to any developer, regardless of their backend language of choice.

This release includes 600+ commits on top of Spree 5.3 and introduces a new REST API, TypeScript SDK, Next.js storefront, multi-region support, full-text search integrations, and a completely new developer onboarding experience.

Highlights

Store API v3

A brand new REST API designed for building headless storefronts. Key design decisions:

• 10x performance over API v2 - new API was rebuilt from the ground up to be as fast as possible
• Security in mind - rate limiting, publishable keys, allowed origins - all best practices baked in
• Prefixed IDs — all resources use human-readable prefixed identifiers (e.g. prod_86Rf07xd4z, or_m3Rp9wXz) instead of sequential integers
• Flat JSON — no nested JSON:API compound documents; simple, unwrapped singular responses and { "data": [], "meta": {} } collections
• expand parameter — selectively include related resources without over-fetching
• Full TypeScript types — auto-generated from API serializers via Typelizer

TypeScript SDK (@spree/sdk)

A fully-typed SDK for interacting with the Store API:

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'pk_xxx',
})

const products = await client.products.list()
const cart = await client.cart.create()

Flat namespace (client.products, client.cart, client.categories), full autocomplete, and generated Zod schemas for runtime validation.

Next.js Storefront

A production-ready storefront template built with Next.js, React 19, and shadcn/ui. Features a one-page checkout and multi-regional support via Markets. Designed as a starting point, you own and customize — not a locked-down theme.

Payment Sessions API

A unified, provider-agnostic payment interface replacing the legacy payment flow. Works with Stripe, Adyen, PayPal, and any gateway that supports session-based payments:

• session_required flag on payment methods distinguishes session-based gateways from direct methods (Check, COD, Bank Transfer)
• Two-phase flow: create a Payment Session → customer pays via provider's frontend SDK → complete the session
• Full 3D Secure and PCI compliance out of the box — card data never touches your server
• Webhook-driven completion ensures payments are captured even if the customer closes their browser

Markets

Multi-region commerce is built into the core. Markets bundle geography, currency, and locale into distinct selling regions within a single store — enabling region-specific pricing, shipping, and tax rules without multi-store overhead.

Full-text search support with Meilisearch

Spree now includes provider agnostic Search Providers with database and Meilisearch providers included in core. Meilisearch is the default choice when using create-spree-app.

Agents-native development

Running npx create-spree-app@latest my-store will now automatically add AGENTS.md/CLAUDE.md files for both backend and storefront apps.

Also, it will automatically include the entire Spree documentation, available offline in markdown format for your agents, such as Claude Code, which will have that injected into the work context from the start!

create-spree-app

Zero-to-running in one command:

npx create-spree-app@latest my-store

Interactive CLI that scaffolds a full-stack project (Docker-based Spree backend + Next.js storefront) or backend-only setup. No Ruby installation required for the Docker path. However, you can freely opt-out from docker and run Spree natively.

Docker-First Deployment

Official multi-arch Docker images (linux/amd64 + linux/arm64) are published to GitHub Container Registry on every release. The Spree CLI (@spree/cli) manages the full lifecycle:

spree init          # First-run setup, seed DB, generate API keys
spree start         # Start all services
spree update        # Pull latest image, run migrations

Bulk export and import for multi-currency and translations

Product exports and imports now support multiple currencies. We've also added a Translation center for easy product translation management, also with bulk import/export of translations.

🇪🇺 EU omnibus directive support

Spree now automatically records price changes to comply with the EU Omnibus Directive. When a product goes on sale, EU regulations require that the lowest price in the preceding 30 days be displayed alongside the discounted price. Spree API now exposes Price history, so you can easily implement it on the storefront. Price changes are tracked and automatically persisted in the database.

Color swatches

You can now select the kind of OptionType: buttons, color swatch, or dropdown. Option Values now allow you to store hex color values for color swatches. Next.js Storefront supports this out of the box.

Installation

npx create-spree-app@latest my-store

More installation options

Updating

To update your Spree installation, follow our guide. You can also share this URL with your agent.

New Contributors

• @samuel-sarmah made their first contribution in https://github.com/spree/spree/pull/13718

Full Changelog: https://github.com/spree/spree/compare/v5.3.5...v5.4.0

This patch release includes bug fixes and security improvements. We recommend updating as soon as possible!

Changes

Core

• Fix store credit amount validation with non-English locales https://github.com/spree/spree/commit/638e31d12410eea03786df99869b90fc25478d02
• FIX gift card overspend race condition potential vulnerability https://github.com/spree/spree/commit/1ab03d54556ddb3901b635f61de67755eb1170bc
• Fix: Replace deprecated Image#plp_url with cdn_image_url variant(:xlarge) https://github.com/spree/spree/commit/b3e259cdf230464eb924ab0312fb83927a3afbcd
• Fix Order#order_refunded? method when store credits are used https://github.com/spree/spree/commit/d2b92570b2cbdadc50ef04488f7ea9751b285ca7

API

• Improved webhooks SSRF protection https://github.com/spree/spree/commit/3c7fc53a14e647516a2dd9b5578d146a668dadfc

Admin

• Fix toggling clear filter button https://github.com/spree/spree/commit/98211d8854ea8b62e6cc4b9f27e354b6075c85d6
• handle custom model class in exports#new https://github.com/spree/spree/commit/4cf12b4855f3779f6c2de8e73f4df008820eabde

Update

Run in your project root:

bundle update

Full Changelog: https://github.com/spree/spree/compare/v5.3.4...v5.3.5

This patch release includes minor fixes to the core and admin packages, squashing some pesky bugs! :)

Changes

Core

• Fix Google feed excluding simple products without option variants (https://github.com/spree/spree/pull/13618)
• Fix deleting products w/o translations on non-default locale (https://github.com/spree/spree/pull/13613)

Admin

• Fix info banner in address form by @KacperMekarski in https://github.com/spree/spree/pull/13624
• Fix admin export to apply filters correctly https://github.com/spree/spree/pull/13616
• Fix price parsing for non-English locales (https://github.com/spree/spree/pull/13627)
• Fix reverse proxy support in admin Table API by using route helpers (https://github.com/spree/spree/pull/13646)
• Fix price localization for product edit screen (https://github.com/spree/spree/pull/13647)

Update

Run in your project root:

bundle update

Full Changelog: https://github.com/spree/spree/compare/v5.3.3...v5.3.4

This patch release includes minor fixes to the core and admin packages, squashing some pesky bugs! :)

Changes

Core

• Fix race condition between saving invitation and sending email https://github.com/spree/spree/commit/b7d053b233f2edcfe78337dc0439d9d36bfc2032
• Prevent NoMethodError in StoreProduct#refresh_metrics! when product is nil by @damianlegawiec in https://github.com/spree/spree/pull/13531

Admin

• Fixed validation error on admin address for not persisted address by @brozek95 in https://github.com/spree/spree/pull/13526
• Fixed edit policy path to use ID rather than slug https://github.com/spree/spree/commit/e1f69b53b3ce4a8d0f77a15815e1087f99e48f1f

Update

Run in your project root:

bundle update

Full Changelog: https://github.com/spree/spree/compare/v5.3.2...v5.3.3

This patch release includes Security fixes plus general improvements. All users are strongly encouraged to upgrade immediately.

Security Fixes

• https://github.com/spree/spree/security/advisories/GHSA-g268-72p7-9j6j (spree_api gem)
• https://github.com/spree/spree/security/advisories/GHSA-p6pv-q7rc-g4h9 (spree_storefront gem)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Other changes

Core

• Fixed incorrect total applied store credit by @resool in https://github.com/spree/spree/pull/13512
• Manually specify event_serializer_class for Reports/Exports/Imports by @damianlegawiec in https://github.com/spree/spree/pull/13523

Admin

• Replace partials with helper methods for rendering admin navigation by @damianlegawiec in https://github.com/spree/spree/pull/13519
• Fixed admin table search field losing focus after loading search res… by @damianlegawiec in https://github.com/spree/spree/pull/13522

Storefront

• fix mobile nav initial transform by @dimidev in https://github.com/spree/spree/pull/13515

Full Changelog: https://github.com/spree/spree/compare/v5.3.1...v5.3.2

This is a security patch release addressing two security vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

• https://github.com/spree/spree/security/advisories/GHSA-g268-72p7-9j6j (spree_api gem)
• https://github.com/spree/spree/security/advisories/GHSA-p6pv-q7rc-g4h9 (spree_storefront gem)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

This is a security patch release addressing two security vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

• https://github.com/spree/spree/security/advisories/GHSA-g268-72p7-9j6j (spree_api gem)
• https://github.com/spree/spree/security/advisories/GHSA-p6pv-q7rc-g4h9 (spree_storefront gem)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

This is a security patch release addressing two security vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

• https://github.com/spree/spree/security/advisories/GHSA-g268-72p7-9j6j (spree_api gem)
• https://github.com/spree/spree/security/advisories/GHSA-p6pv-q7rc-g4h9 (spree_storefront gem)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

This is a security patch release addressing https://github.com/spree/spree/security/advisories/GHSA-g268-72p7-9j6j

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Ruby 4.0 support

This patch release fixes Spree installation on Ruby 4.0, so you can now use Spree on the latest version of Ruby :)

Other changes

Core

• fix[v-3311]: gift cards - add user validation to Apply class by @resool in https://github.com/spree/spree/pull/13505
• Add Ruby 4.0 support by @damianlegawiec in https://github.com/spree/spree/pull/13511
• Add item_group_id to required_attributes for Google data feed by @mbajur in https://github.com/spree/spree/pull/13506

Storefront

• FIX clear token cookie by @brozek95 in https://github.com/spree/spree/pull/134993

Page Builder

• Fix Rails 8.1 ActiveRecord::EagerLoadPolymorphicError by @damianlegawiec in https://github.com/spree/spree/pull/13504

Documentation

• Fix link to Developer Guides in user documentation by @chrislaai in https://github.com/spree/spree/pull/13498

Full Changelog: https://github.com/spree/spree/compare/v5.3.0...v5.3.1

Spree 5.3 with new Pricing engine, Customer Groups and Events & Subscribers workflows

Spree 5.3 continues the momentum of the biggest Spree release ever — Spree 5 — delivering major architectural improvements, like a new powerful pricing engine and support for event-driven workflows, making framework customization easier and more future-proof.

This release builds on the foundations laid in 5.0, 5.1, and 5.2 by introducing flexible pricing engine, customer groups, a pub/sub event system, modernized admin UI, and enhanced developer tools — all while keeping Spree fully open source and community-driven.

Highlights

New Pricing Engine (Price Lists)

A flexible pricing system for managing pricing strategies — essential for B2B, multi-region, wholesale, and marketplace use cases.

• Customer Group pricing — Offer different prices to VIP, wholesale, or B2B customers.
• Volume pricing — Automatic discounts when item quantity falls within min–max ranges.
• Zone-based pricing — Regional pricing based on customer location.
• User-specific pricing — Individual pricing for key accounts.
• Time-based activation — Schedule price lists with start and end dates.
• Bulk Editor — use spreadsheet-like UI to manage prices for multiple products in multiple currencies with ease, also with keyboard shortcuts :)

Learn how to set up Price Lists in Spree Commerce.

Events & Subscribers Engine

A powerful new event system that allows you to react to various actions happening in your application. When something happens (an order is placed, a product is updated, or inventory changes), Spree publishes an event that your code can subscribe to and handle.

• Loose coupling — Connect and extend Spree without modifying core code.
• Multiple event types — Order, payment, shipment, product, customer, and more.
• Wildcard subscriptions — Subscribe to order.* to catch all order events.
• Sync or async — Run handlers immediately or via ActiveJob. Async default!
• Custom events — Publish your own events from anywhere in your application.

Perfect for sending notifications, syncing with external services, logging audit trails, triggering webhooks, and updating caches.

Learn how to work with Events in Spree Commerce.

Customer Groups

Segment your customers into defined groups for personalized experiences and targeted business rules.

• Flexible grouping — Create unlimited customer groups (VIP, Wholesale, B2B, Early Access, etc.).
• Price List integration — Apply custom pricing to specific customer groups.
• Promotion rules — Restrict promotion eligibility to certain customer segments.
• Easy management — Add and remove customers from groups directly in the admin.

Learn how to set up Customer Groups in Spree Commerce.

Webhooks 2.0 with Admin UI

A completely revamped webhook system with full admin panel management, built on top of the new Events engine.

• Admin panel management — Create and manage webhook endpoints directly from Settings > Developers > Webhooks.
• Event filtering — Subscribe to specific events or use wildcards (e.g., order.*).
• HMAC-SHA256 signatures — Secure payload verification for all deliveries.
• Automatic retries — Failed deliveries retry up to 5 times with exponential backoff.
• Full audit trail — Track every delivery attempt with response codes, timing, and error details.
• Multi-store support — Each store can have its own webhook endpoints.

Learn how to configure Webhooks in Spree Commerce.

Tailwind CSS Admin Dashboard

The admin dashboard has been completely rebuilt with Tailwind CSS, replacing Bootstrap entirely.

• Modern, clean, and consistent design language throughout the entire admin interface.
• Faster page loads and smaller CSS bundle size.
• Easier customization using Tailwind's utility-first approach.
• Improved responsive design for mobile and tablet admin access.

Admin Tables Component

A new flexible table system for displaying resource listings in the admin dashboard with a powerful DSL for customization.

• Declarative API — Define table configurations with customizable columns, sorting, filtering, and bulk actions.
• Multiple column types — String, number, money, status, boolean, datetime, link, image, association, and custom partials.
• Query builder filters — Advanced filtering with autocomplete, select, date ranges, and more.
• Bulk actions — Select multiple rows and perform batch operations.
• Extensible — Add columns to existing tables, insert at specific positions, or create entirely new tables.

Learn how to work with Admin Tables in Spree Commerce.

Order Adjustments & Order Promotions

A new admin experience for managing order promotions and order adjustments.

• Order promotions — Manually add promotions to the order in the admin panel
• Order adjustments — Manually add charges or credits to existing orders with streamlined payment/refund handling.

Learn how to create Promotions and manage Order Adjustments in Spree Commerce.

Admin Order & Customer Notes

Add internal notes to orders and customers for better team communication and order tracking.

• Staff notes — Add internal comments visible only to admin users.
• Order history — Keep a record of important order-related communications.
• Team collaboration — Share context about special handling, customer requests, or issues.

What's Next

Spree 5.4 will include another batch of impressive changes, such as:

• New REST API built around simplicity, ease of use, and performance (around 10x faster than API v2!)
• TypeScript SDK allowing developers leverage the new API with a great developer experience and type safety!
• Next.js storefront starter kit powered by the new API and TypeScript SDK
• Multi-channel support allowing developers to build and manage a truly omnichannel experience

Contributors

A huge thank-you to everyone who contributed ideas, code, testing, issue reports, documentation, and feedback.

New Contributors

• @malakada made their first contribution in https://github.com/spree/spree/pull/13421
• @carl-lee-lu made their first contribution in https://github.com/spree/spree/pull/13441
• @MuhammadIbtisam made their first contribution in https://github.com/spree/spree/pull/13463
• @FrederikKragh made their first contribution in https://github.com/spree/spree/pull/13484

Full Changelog: https://github.com/spree/spree/compare/v5.2.3...v5.3.0

Installation

Paste this into your terminal, and our guided installer will setup everything for you. You'll also be able to choose which Spree modules to install.

bash -c "$(curl -fsSL https://spreecommerce.org/install)"

Upgrading from earlier versions?

Please follow our Spree 5.3 upgrade guide.

Rails 8.1 support

This patch release adds full support for Rails 8.1! Spree still supports Rails 7.2 and 8.0, so you are not forced to upgrade.

Performance improvements

Storefront, Cart operations, Promotion engine, and API received a huge number of performance improvements in terms of better caching and eliminating pesky N+1s. Also, the default storefront theme was greatly improved in terms of accessibility and Page Speed Insights score.

Ransack Customization DSL

We're introducing a new, clean, and safe way to customize Search and filtering without the need to create model decorators.

Rather than using decorators, you can just use the new DSL in your Spree initializer file:

  # Add a custom searchable attribute to Products
  Spree.ransack.add_attribute(Spree::Product, :vendor_id)

  # Add a custom searchable scope to Products
  Spree.ransack.add_scope(Spree::Product, :by_vendor)

  # Add a custom searchable association to Products
  Spree.ransack.add_association(Spree::Product, :vendor)

Upgrade

bundle update

Spree 5.3 coming soon

The next big release is just around the corner and will bring notable new features such as:

• New Pricing engine, allowing you to create B2B/Wholesale/Regional pricing as well as custom pricing rules you can add
• Event Subscribers - a new pub/sub way of extending Spree, again reducing the need for model decorators!
• Webhooks 2.0 - much improved HTTP Webhooks, working on top of the new Events engine
• and many more

Other changes

Core

• Improve performance of Promotion Rules: Taxon, Product, User, and OptionValue https://github.com/spree/spree/commit/ff1ffb51ff4d3cd5a14e5ec77f9a6ea16d536cf2
• FIX void payment when no response_code https://github.com/spree/spree/commit/7ae4e026db9c6124ffb9f31a50c280df196971e2
• Fix handling Store mobility-powered associations during store creation https://github.com/spree/spree/commit/757646872007f6d1d420d8df0bd4c6ebaed62a73
• Fixed issue https://github.com/spree/spree/issues/13437 - Promotion rule caching issue when editing rules with associated users or products. https://github.com/spree/spree/commit/e06bc7ec53228b9f3e850ed0f7c19f37a4226f8c
• Simplify and reduce the footprint of Variant#options_text https://github.com/spree/spree/commit/33687ad942076299ff759f978225d18685c3c805
• Speed up quick checkout checks for Order https://github.com/spree/spree/commit/eec85d931b89bfdc91dde4d9301b26c42959242e
• Fix N+1s and improve the performance of RemoveOutOfStockItems service https://github.com/spree/spree/commit/d5f0803dce56923431bba1d52ccf5186e0ee01cf

API

• Fixed N+1 in Storefront API Products endpoint
  https://github.com/spree/spree/commit/d592667d8997a7224c0aee6a52694188cc0531ee

Admin

• Admin: Limit the number of Report line items in web view to 1000 (by default) https://github.com/spree/spree/commit/0249efbf3d9031316dfd2fd99e0be39028a9ffbe
• Implement allowed_file_types option for spree_file_field https://github.com/spree/spree/commit/af55a5b872b456dcb6bb2461762011b154b7cb51

Storefront

• Removed canonical-rails as a dependency https://github.com/spree/spree/commit/ebe791ce7c0d4b5bb60a8f7c797e4c0384ee46f9
• Fixed N+1s on Storefront cart
  https://github.com/spree/spree/commit/3b7181e54c53019f8f01700b9a7cdd50657eaca1
• Cache Countries/States JSON needed for address form https://github.com/spree/spree/commit/df23bbc6e50d446683488ffcbcec154a3ec9d997
• Fixed: don't update tracking params in checkout if they didn't change https://github.com/spree/spree/commit/ad004a6f1d6aba45bc51f222c0689f60ee35c0b4
• fix: Header overlay is misaligned in page builder https://github.com/spree/spree/commit/61fd05014c5701ce4b90ce224fcb279c22ab5689
• Pagespeed insights adjustments https://github.com/spree/spree/commit/f6c092f4daedbe34b40994881a5dd5a3854c4b5e
• Fixed: remove double caching of checkout line items
  https://github.com/spree/spree/commit/5c3bb302f92de9ab510b985aa31e3b41c33fbc7e
• Include translations when fetching product breadcrumb taxons for json-ld https://github.com/spree/spree/commit/e23f2ad9efc704f74d9b90ac5855efb18f59a533
• Added caching for storefront CheckoutHelper#quick_checkout_enabled? https://github.com/spree/spree/commit/051eedb00e567517563f56c33fab9e67928875c2

Full Changelog: https://github.com/spree/spree/compare/v5.2.5...v5.2.6

This is a security patch release addressing two IDOR (Insecure Direct Object Reference) vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

High: Unauthenticated IDOR - Guest Address Exposure (GHSA-3ghg-3787-w2xr)

Moderate: Authenticated IDOR via Order Modification (GHSA-g268-72p7-9j6j)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Acknowledgements

We want to thank XBOW researchers who responsibly disclosed these vulnerabilities.

This is a security patch release addressing two IDOR (Insecure Direct Object Reference) vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

High: Unauthenticated IDOR - Guest Address Exposure (GHSA-3ghg-3787-w2xr)

Moderate: Authenticated IDOR via Order Modification (GHSA-g268-72p7-9j6j)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Acknowledgements

We want to thank XBOW researchers who responsibly disclosed these vulnerabilities.

This is a security patch release addressing two IDOR (Insecure Direct Object Reference) vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

High: Unauthenticated IDOR - Guest Address Exposure (GHSA-3ghg-3787-w2xr)

Moderate: Authenticated IDOR via Order Modification (GHSA-g268-72p7-9j6j)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Acknowledgements

We want to thank XBOW researchers who responsibly disclosed these vulnerabilities.

This is a security patch release addressing two IDOR (Insecure Direct Object Reference) vulnerabilities. All users are strongly encouraged to upgrade immediately.

Security Fixes

High: Unauthenticated IDOR - Guest Address Exposure (GHSA-3ghg-3787-w2xr)

Moderate: Authenticated IDOR via Order Modification (GHSA-g268-72p7-9j6j)

Supported Versions

Security patches are available for all currently supported Spree versions:

| Version | Patched Release | EOL Date |
|---------|-----------------|----------|
| 5.0 | 5.0.7 | March 2028 |
| 4.10 | 4.10.2 | September 2027 |

If you're running an unsupported version, please upgrade as soon as possible. Unsupported versions will not receive security patches. Need help upgrading? Contact the Spree team.

Upgrade

bundle update

Acknowledgements

We would like to thank XBOW researchers who responsibly disclosed these vulnerabilities.

This patch release contains several bug fixes and performance improvements. To update run:

bundle update

In your project root directory.

Core

• Fixed Product best-selling scope https://github.com/spree/spree/pull/13381
• Fix Bundler 4.0 compatibility https://github.com/spree/spree/commit/6f00f1fb4a619ca978b5f253f799d10ce32648e1
• Add observer and ostruct gems for Ruby 3.4+ and Bundler 4.0 compatibility https://github.com/spree/spree/commit/e3eea78ed1b0f960794930fc90ae7f9fb7055781
• Include fixtures in the gem as we reference them in factories https://github.com/spree/spree/commit/46ff9c8bef085da59d02a2983aa576f5624cd7bc

Admin Dashboard

• Fixed Admin profile link active state https://github.com/spree/spree/commit/70f142b0bd00fd3091548b0e22dd73eb7e8258b0
• Fixed: Include tinymce in admin sprockets manifest https://github.com/spree/spree/commit/7dcc1278e6c05e04666c77eafda55293a935b597

Storefront

• Fix toggle menu https://github.com/spree/spree/pull/13377

Full Changelog: https://github.com/spree/spree/compare/v5.2.3...v5.2.4

This patch release contains several bug fixes and performance improvements. To update run:

bundle update

In your project root directory.

Core

• Add icons for SEPA and Bank Transfer payment methods by @mad-eel in https://github.com/spree/spree/pull/13356
• Fixed N+1s and overall performance of SalesTotal report for larger da… by @damianlegawiec in https://github.com/spree/spree/pull/13358
• Reports improvements by @mad-eel in https://github.com/spree/spree/pull/13321
• Fixed Docker builds permission issue https://github.com/spree/spree/issues/13379

Admin Dashboard

• Fixed dialogs and drawers in admin for Safari by @damianlegawiec in https://github.com/spree/spree/pull/13380

Storefront

• Fix indentation in product details template by @dimidev in https://github.com/spree/spree/pull/13366

Documentation

• Added PLP user documentation by @jaburghes in https://github.com/spree/spree/pull/13367

Full Changelog: https://github.com/spree/spree/compare/v5.2.2...v5.2.3

Image processing in background jobs

Now, when an image is uploaded, Spree automatically generates optimized versions in the background, so they’re ready to serve immediately without on-demand processing. You can still generate on-the-fly variants if you wish, but we recommend using the preprocessed named variants for optimal performance.

This greatly speeds up Product Listing Pages and reduces load on the web application. For products, we have a set of 5 predefined image variations, which, of course, you can customize.

To use named variants in your views, you need to change your code from:

<%= spree_image_tag(image, width: 64, height: 64) %>

to

<%= spree_image_tag(variant: :mini) %>

Old code, with width/height as parameters, will work as before, so these changes are optional if you want to improve the speed of your application.

Documentation

Dependencies 2.0

We've greatly improved developer experience working with Spree Dependencies. Now it's easier to set and access dependencies, eg.

Spree.cart_add_item_service = MyAddToCartService

When accessing, you don't need to call constantize anymore,

Spree.cart_add_item_service.call(order: order, variant: variant, quantity: quantity, options: options)

There are also 3 new helpful rake tasks:

bin/rake spree:dependencies:list # will list all available dependencies and their current values
bin/rake spree:dependencies:overrides # will list only dependencies that were overriden in your app and/or extensions
bin/rake spree:dependencies:validate # will validate if all dependencies are valid classes

We recommend checking the documentation for full picture.

Other changes

Core

• FIX csv importer index by @brozek95 in https://github.com/spree/spree/pull/13354

API

• Storefront API - Fix line items data in the response after removing a coupon code by @mad-eel in https://github.com/spree/spree/pull/13336

Admin

• Use Spree Form builder in product form more by @damianlegawiec in https://github.com/spree/spree/pull/13341

Storefront

• Add Greek country code mapping to svg_country_icon helper by @dimidev in https://github.com/spree/spree/pull/13353

Documentation

• Updated Posts user documentation by @jaburghes in https://github.com/spree/spree/pull/13339
• Updated 'Storefront Settings' user doc by @jaburghes in https://github.com/spree/spree/pull/13340

Full Changelog: https://github.com/spree/spree/compare/v5.2.1...v5.2.2

Permission sets - new way to manage role-based permissions

This patch release contains several fixes and a nice new feature Permission Sets a new way to customize role-based permissions in Spree. Permission Sets provide a clean, modular way to manage permissions. Each permission set is a reusable group of permissions that can be assigned to roles.

Old customizations will work as before. To switch to the new system you'll need to add below lines to your config/initializers/spree.rb file:

Rails.application.config.after_initialize do
  Spree.permissions.assign(:default, [Spree::PermissionSets::DefaultCustomer])
  Spree.permissions.assign(:admin, [Spree::PermissionSets::SuperUser])
end

To update your Spree version please run:

bundle update

in your project root directory. If you're on Spree 5.1 or older, please follow Spree 5.2 upgrade guide.

Other changes

Core

• fix: update state_machines by @seuros in https://github.com/spree/spree/pull/13331
• Fix re-using slugs from history on the same record by @mad-eel in https://github.com/spree/spree/pull/13329

Admin Dashboard

• Add portal: false to dropdowns inside turbo frames or referencing D… by @damianlegawiec in https://github.com/spree/spree/pull/13335
• Fix drawer overflow form scroll by @dimidev in https://github.com/spree/spree/pull/13334

Documentation

• New documentation website with Spree tutorial by @damianlegawiec in https://github.com/spree/spree/pull/13304
• Updated 'Pages' user documentation by @jaburghes in https://github.com/spree/spree/pull/13316
• Docs: fix typo (bellow → below) in developing Spree guide by @kunalchaudhari in https://github.com/spree/spree/pull/13317
• Fix broken Customization Overview link by updating to Customization Quickstart page by @kunalchaudhari in https://github.com/spree/spree/pull/13322
• [Skip CI] Document new permission sets by @damianlegawiec in https://github.com/spree/spree/pull/13325

New Contributors

• @kunalchaudhari made their first contribution in https://github.com/spree/spree/pull/13317

Full Changelog: https://github.com/spree/spree/compare/v5.2.0...v5.2.1

🎉 Spree 5.2 with New Features and Developer tools

Spree 5.2 continues the momentum of the biggest Spree release ever — Spree 5 — focusing heavily on developer experience, customization capabilities, and enterprise-level workflows.

This release builds on the foundations laid in 5.0 and 5.1 by delivering new tools that make Spree faster to develop, easier to extend, and more flexible for merchants across B2C, B2B, and various use cases.

Expect smoother setup, more powerful low-code customization, richer storefront editing, and new marketing-ready features — all while keeping Spree fully open source and community-driven.

✨ Highlights

🔧 Metafields

A powerful new way to extend any Spree model without writing code or altering your database schema.
Add structured, typed metadata fields to products, variants, orders, customers, and more.

• Manage metafields entirely through the Admin Dashboard or via API.
• Perfect for flexible content, integrations, PIM-style data, custom attributes, and storefront personalization.
• Greatly improves developer experience by allowing non-technical teams to manage additional data without migrations.
• Great for extension developers to save metadata, external IDs and so on

Learn how to define and use metafields in Spree Commerce.

🛠 Developer Tools

Spree 5.2 ships with a suite of improvements designed to make developers dramatically more productive:

• New Spree Installer CLI — spin up a project in seconds, with recommended defaults.
• Spree Generators — instantly scaffold models, admin dashboard components, and boilerplate.
• End-to-End Spree Tutorial — taking beginners from zero to production-ready Spree developers.
• Storefront on Tailwind 4 — build modern, responsive storefronts using the latest Tailwind CSS.
• Admin SDK Enhancements — improved Navigation system, Component library, and Form Builder for rapid admin UI development.
• Spree Dev Tools Gem — write automated tests faster with opinions, helpers, and best practices built in.
• AI Tool Integrations — import Spree-optimized Cursor/Claude rules to streamline agentic coding workflows.

📦 CSV Importer

A visual CSV product importer that is easier, clearer, and fully mappable.

• Upload CSV product files and map your custom columns to the Spree schema.
• Supports bulk product creation and updates.
• Ideal for catalog migrations, PIM exports, or vendor-provided product feeds.

Learn how to import product CSV files in the Spree Commerce dashboard.

📝 Store Policies

A new flexible system for managing terms & conditions, returns, and any additional store policies.

• Create and manage multiple policies directly from Admin.
• Display policies to customers throughout the storefront.
• In Spree Enterprise, multi-vendor stores allow each vendor to manage their own dedicated policies.
  Learn how to set up and manage store policies in Spree Commerce.

🛍 Product Details Page 2.0

A major update to how product pages are built and edited.

• Fully customizable Page Builder sections and blocks.
• Merchandisers can create richer product storytelling without developer involvement.
• Developers gain a more modular, maintainable product page layout system.

Learn how to customize the Product Details Page in Spree Commerce.

✉️ Newsletter Subscribers

Track newsletter signups across your storefront and sync them with Klaviyo for automated email marketing flows.

This helps merchants better understand audience growth and integrate seamlessly with marketing automation workflows in Klaviyo.

🔮 More Coming Soon…

Spree 5.2 lays the groundwork for several major upcoming improvements, including:

• New flexible Pricing engine, which can power subscriptions, B2B or regional pricing
• New Events engine allowing you to connect and extend Spree with Subscribers
• New Metafield Types allowing you to create relations between models, eg. related products
• Finally, a brand new, easy, and much faster API with SDKs

Stay tuned — Spree 5.3 and beyond will continue to push the platform forward.

👏 Contributors

A huge thank-you to everyone who contributed ideas, code, testing, issue reports, documentation, and feedback.

• @nerijunior made their first contribution in https://github.com/spree/spree/pull/12946
• @kyryloliinyk made their first contribution in https://github.com/spree/spree/pull/12953
• @jawaria-sparksol made their first contribution in https://github.com/spree/spree/pull/12954
• @Cichorek made their first contribution in https://github.com/spree/spree/pull/12986
• @umeshravani made their first contribution in https://github.com/spree/spree/pull/12998
• @rorimwema made their first contribution in https://github.com/spree/spree/pull/13042
• @karolina-bronowicka made their first contribution in https://github.com/spree/spree/pull/13140
• @ahmedelsherif-osama made their first contribution in https://github.com/spree/spree/pull/13176
• @coderliu made their first contribution in https://github.com/spree/spree/pull/13222

🙌 Thanks for your ongoing feedback, contributions, and passion for open-source eCommerce.
Let’s keep building the future of commerce — together.

Full Changelog: https://github.com/spree/spree/compare/v5.1.0...v5.2.0

Upgrading from earlier versions?

Please follow our Spree 5.2 upgrade guide.

Core

• Fixed expiring promotion cache when updating actions calculator https://github.com/spree/spree/commit/b0d172eb317da2563a68e13934a5286542e79a4e
• Fixed gift card transitions for multiple partial redemptions and final redemption https://github.com/spree/spree/commit/ee8ebbdfc2eca01c8159a3d8848016af854564cb
• Added confirmation_required? to payment methods and use it in Spree::Order#confirmation_required? https://github.com/spree/spree/commit/f5ab94f2f4e35da73e274a2df4e5f8bc2672620f
• Fixed create account service with existing users https://github.com/spree/spree/commit/a667973febd99fb29ab84c3fef793a265548e501
• Fixed Addresses::Update service when updating encrypted addresses - https://github.com/spree/spree/commit/0afe73f5d994c9fe3f77bb7742fe73f12f902838
• Move Addresses::PhoneValidator to app/validators directory https://github.com/spree/spree/commit/11997c9be00dee494002646ce8c80a97e5704942
• Fixed migrate_admin_users_to_role_users migration script when admin_user_class is the same as user_class https://github.com/spree/spree/commit/e4c30ee0c57aeba825a3e26f3431a047c25cff19

Admin

• Update Trix to 2.1.15 https://github.com/spree/spree/commit/1990c33caec7f39f5185eab1307c4d8f20d6e4f8
• Fixes https://github.com/spree/spree/issues/13168 undefined currency_options_for_select https://github.com/spree/spree/commit/b0a6cc47105c56a1176151b978ee039c7cd96c39
• Fixed: admin - creating line items for orders with non-default currency https://github.com/spree/spree/commit/648b5f7270f90d0a2bcec331c6a8c033da27a7c3
• Fixed admin email search to support underscores in orders and customers https://github.com/spree/spree/commit/09de6848e0136b9549a0b3bc2566ce4b57e275d7
• Fixed https://github.com/spree/spree/issues/13150 admin - normalize translation locale to handle compound locales https://github.com/spree/spree/commit/683c16bf8db4de62dfc051949dff1260730d390b
• Added ability to include custom JS/stimulus controllers in Admin https://github.com/spree/spree/commit/75b3f27185a4b8bacffa5b80c9a96976a43b8eef
• Fix refreshing the form after updating the payment method https://github.com/spree/spree/commit/d7a2cabb5b84357f475a5db028b7ff32265c0814
• Fix the Gift Card show view for guest orders https://github.com/spree/spree/commit/4a2e22e0fcd17c53619e41ad5900b5d8858d498e
• Fix displaying the order status when order with gift card is refunded/cancelled https://github.com/spree/spree/commit/51bccecd6a5b283e42c40d511c05ba69a769671a
• Fixed: Multi Store Admin - editing product in a different store removes taxons from another store https://github.com/spree/spree/commit/66588d3efd2564c02fc8f56afeeace12b58401c1

Storefront

• Fixed: don't crash order view when order doesn't have any addresses https://github.com/spree/spree/commit/74ee643a7ca74cd1eb757b51a6f3f2e2d6eb0bc4
• Fixed ability to override storefront Stimulus controllers https://github.com/spree/spree/commit/999b0e50b61275fa5a0682e345fc53b49c1db650
• Fix displaying the gift card payment on the checkout complete page https://github.com/spree/spree/commit/1f33e56fd2c64ddc7cc39bfb051a9a5e4c2902eb
• Added ability to handle phone on quick checkout and fixed duplicated cookies issue https://github.com/spree/spree/commit/c379544e048455f37e213c9eddcf448ee20e1c28
• Fixed default page title for some storefront pages https://github.com/spree/spree/commit/0d83d4119f4c6dfa25f04ad034f8b0f4c07fadca

Full Changelog: https://github.com/spree/spree/compare/v5.1.7...v5.1.8

[!IMPORTANT]
This release removed the currency_select dependency, if you're using this gem in your application outside of Spree you will need to manually add it to your Gemfile

Storefront

• Fix accessing the checkout complete page on user orders for guests https://github.com/spree/spree/commit/0eb54f17f688cd7a4efa7fe0eb91e1c8d7650568
• Fix JSON-LD array formatting for product offers to pass Schema.org validation https://github.com/spree/spree/commit/6360059a3d04700d7f2d28fd231d41fe7a0eda1a https://github.com/spree/spree/commit/09c2b487e97c38fc8b20da37bfd04540a6568dac

Admin

• Dropped currency_select gem dependency, which was broken on Rails 8.0.3 https://github.com/spree/spree/commit/983373400db1d4adba0b73da033cfdafa9a3d868
• Fixed return authorizations breadcrumbs https://github.com/spree/spree/commit/9df2b5cbe849300f3c5eb2a0e91591d5ddd43760
• Fixed pages edit link in dropdown https://github.com/spree/spree/commit/d6878407adbc6549702c8ee613e9515c530f4ee6

Core

• Fix Price#compare_at_amount type casting issue https://github.com/spree/spree/commit/e9a9feeff5604d53cc4e6bf3881f06af92c9abf6
• Fix order recalculations when applying coupon codes and gift cards https://github.com/spree/spree/commit/3e22e2068f4548ea46b0e9fc715e7eaf2d1c01b4 https://github.com/spree/spree/commit/83ff70d4d782e129ea9fed429efbefa8ac2c7731

Full Changelog: https://github.com/spree/spree/compare/v5.1.6...v5.1.7

Storefront

• Added support for legacy browsers such as Safari on iOS 15
• Fixed: don't cache product carousel in page builder mode
• Added more protocol to page builder links
• Fixed Homepage Navbar link
• Fixed sticky header
• Introduce fragment caching to Featured Taxon page section
• Lazy load hidden turbo frames (eg. cart pane)
• Fixed Cart panel N+1s when changing qty
• Fixed N+1s for cart pane
• Improve Checkout special instructions UX (adding autogrow stimulus
• Added Dom ID to checkout payment terms
• Move Checkout terms and conditions into partial
• Fixed handling of lazy loaded frames on Safari,

Admin Dashboard

• Product variants form fixes
• Fixed: use translation for Add Link button
• Fixed: admin - In the store dropdown show only stores current user has access to
• Fixed: Draft Order back button to redirect to Draft Orders list
• Fixed: stop prefetching page builder pages in page dropdown

API

• Fixed: making sure we return proper HTML action text response in API
• Added missing compare_at_amount keys to Line Items in Storefront API

Core

• Improve default background queue handling in extension generator
• Fixed checkout zone handling when zone is deleted
• Speed up TaxRate#adjust by operating on IDs rather than full objects
• Add memoization to Product#digital? and Shipment#digital?
• Improve Shipment#with_free_shipping_promotion?
• fixed shipment.digital? without shipping method
• Fixed OrderInventory handling for items without inventory tracking

New Features

• New Custom Domains / Internal URL UI https://github.com/spree/spree/commit/7eb491cfb2af07782b3f9c5e0c0fef5631fe30ba
• New Admin Tax Rate form https://github.com/spree/spree/commit/ee6676439484bbac74ae643ca8d1b43e6bac5ca6
• Ability to toggle off and disable transactional emails https://github.com/spree/spree/commit/a267f54b609556c4ee23293874d0b712b6605cdd
• Claude Code integration https://github.com/spree/spree/commit/dcc4380c264356d2b1ff9e4c4b8760f5c410c077
• Add ability for 3rd party payment gateways to store/read Credit Card wallet type, eg. Apple Pay https://github.com/spree/spree/commit/d4278841865d48648ddb78da007117f0c734708e
• Add more dashboard injection points for products https://github.com/spree/spree/commit/8b2ea0c2a2e231e4d52d8f770229bc1c3ef4ca86
• Use Spree::Api::Dependencies for easy customization/replacement of Platform API responses https://github.com/spree/spree/commit/b49c9df729e789d6a6a09a7d1a6f97fd75c9fd40

Fixes

• Fixed missing translation in invitation email https://github.com/spree/spree/commit/85a9f1a2380e02329a1679ebcb191674464fe965
• Added missing options hash in Storefront Variants API https://github.com/spree/spree/commit/554be77a428985bf8c39b21600c069ef9cb53890
• Fixed: do not destroy initialized tom select elements upon page exit https://github.com/spree/spree/commit/711ccbc7911872e1019d6f18f0a82072e8fa3c07
• Improve product form variants section CSS https://github.com/spree/spree/commit/bac3fff3173c69867bd59cf12831b311f07da5d0
• Fixed: Admin keybindings for save/exit https://github.com/spree/spree/commit/06192dce74eccf0c8fd032bc606d263770427f7e
• Fixed: taxonomies sorting / setting position in admin https://github.com/spree/spree/commit/99356db18792698e3c252329bc3fcea05b7e7060

Full Changelog: https://github.com/spree/spree/compare/v5.1.4...v5.1.5

Features

• Addedrails g spree:storefront:devise generator

FIxes

• product slug candidates and history https://github.com/spree/spree/commit/a875498a073dc53820b5b35508f674423711894d
• address state when not persisted and validation error https://github.com/spree/spree/commit/2dadcd88e0b66d5d3e19141a226232c54ef10147
• don't use hardcoded urls for variant edit links in variant matrix form https://github.com/spree/spree/commit/9d6589c126b66d35827ed27f3caec7926e6daa20
• Align promotion rule eligibility error message with currency of the order https://github.com/spree/spree/commit/55abbba9aff271efe7f5b848cc99658ef2bbae4b
• API: fixed Taxon's header_url to always use CDN when generating image URLs https://github.com/spree/spree/commit/ac325bab247fa6b9261a09eef128d9f151c312f0
• Pages can not be edit after theme was published https://github.com/spree/spree/commit/196cf1539cd17fd8d26a56362a2917b1442de2c7
• custom_domain to accept composed TLDs e.g: .com.br https://github.com/spree/spree/commit/86c616d035ab39f268ae9d5113fb8ddce148e6af
• Ensure slugs for Product Translations are unique https://github.com/spree/spree/commit/ef6d3b1ba9b9f6353a692c46f5e117a1f2b964cd
• add missing :uk svg country icon https://github.com/spree/spree/commit/bfe943d021220bde034a7c0d9fac6c293c0f97da
• do not destroy initialized tom select elements upon page exit https://github.com/spree/spree/commit/5d760cdbd4741c8fbbf64e8760ecf40eb8b3342a

Full Changelog: https://github.com/spree/spree/compare/v5.0.5...v5.0.6

What changed?

• Added missing admin save target for store/profile form so CMD/CTRL+S keybinding works
• Admin: Improve Role form
• Fix generating slugs for deleted products
• Add more Admin injection points for easy extending the UI
• add capturable scope and ability to temporary skip payment.source validatrion
• Fixed: Ensure slugs for Product Translations are unique
• Improve Admin navigation

Full Changelog: https://github.com/spree/spree/compare/v5.1.3...v5.1.4

What's Changed

• Small improvements to product form option values handling by @damianlegawiec in https://github.com/spree/spree/pull/12945
• Fix custom_domain to accept composed TLDs e.g: .com.br by @nerijunior in https://github.com/spree/spree/pull/12946
• Use Custom Domains in spree_emails when generating URLs to Storefront by @damianlegawiec in https://github.com/spree/spree/pull/12947
• Override emails host so it always matches the store which sent the email by @damianlegawiec in https://github.com/spree/spree/pull/12949
• Admin: Improve list pagination user experience by @damianlegawiec in https://github.com/spree/spree/pull/12951
• Improve bulk panel operations tab UI by @damianlegawiec in https://github.com/spree/spree/pull/12952
• Fix | add missing :uk svg country icon. by @kyryloliinyk in https://github.com/spree/spree/pull/12953
• Skip propshaft for sandbox app/dummy generator by @damianlegawiec in https://github.com/spree/spree/pull/12955

New Contributors

• @nerijunior made their first contribution in https://github.com/spree/spree/pull/12946
• @kyryloliinyk made their first contribution in https://github.com/spree/spree/pull/12953

Full Changelog: https://github.com/spree/spree/compare/v5.1.2...v5.1.3

What's Changed

• API: fixed Taxon's header_url to always use CDN when generating ima… by @damianlegawiec in https://github.com/spree/spree/pull/12930
• permit params for spotify and discord by @simlegate in https://github.com/spree/spree/pull/12922
• Admin: Fixed rendering and setting properties for product form by @damianlegawiec in https://github.com/spree/spree/pull/12931
• Clean up admin forms to center them for better UX by @damianlegawiec in https://github.com/spree/spree/pull/12934
• Fix datepicker handling by @brozek95 in https://github.com/spree/spree/pull/12933
• Include all Spree controller helpers in DeviseConcern by @damianlegawiec in https://github.com/spree/spree/pull/12942
• fix: Pages can not be edit after theme was published by @simlegate in https://github.com/spree/spree/pull/12943
• Improve admin updater notification by @damianlegawiec in https://github.com/spree/spree/pull/12932

Full Changelog: https://github.com/spree/spree/compare/v5.1.1...v5.1.2

What's Changed

• Added integration tests for checkout by @damianlegawiec in https://github.com/spree/spree/pull/12924
• Fixed: brought back track inventory checkbox in variant form, by @damianlegawiec in https://github.com/spree/spree/pull/12925
• CHG mail image to save as png by @brozek95 in https://github.com/spree/spree/pull/12923
• Translations fixes by @damianlegawiec in https://github.com/spree/spree/pull/12928
• Improve digital items checkout for signed in users by @damianlegawiec in https://github.com/spree/spree/pull/12929

Full Changelog: https://github.com/spree/spree/compare/v5.1.0...v5.1.1

🎉 Spree 5.1 with New Features and Integrations

We’re excited to introduce Spree 5.1 with new, exciting features and integrations. Whether you’re managing staff, rewarding loyalty with gift cards, or customizing your checkout — Spree 5.1 gives you the tools to move fast and grow with confidence.

This release builds on the momentum of Spree 5 — the biggest release in Spree’s history — by adding enterprise-grade features, deeper admin tooling, and powerful customer experience enhancements.

With 5.1, we’re expanding core functionality while continuing to simplify operations, improve performance, and empower teams to launch, scale, and optimize with full control.

🛍️ Gift Cards

Spree 5.1 introduces full native support for Gift Cards, enabling merchants to issue, manage, redeem, and track gift card codes — all from the Spree admin dashboard.

Admins can:

• 🎁 Create individual gift cards for specific customers or as rewards
• 🧾 Bulk generate gift card batches with custom prefixes, dollar values, expiration dates, and automatic code generation
• 🔁 Track gift card redemption history per customer and per order
• 🛒 Support gift card redemption during checkout, with remaining balances and full audit trail in the order view

Gift cards can be used alongside other promotions and discount codes. Redemption is clearly displayed during checkout for transparency. Whether you're running holiday campaigns, loyalty programs, or issuing store credit, Spree 5.1’s Gift Card system makes it seamless — and it’s built right into your dashboard.

👥 Admin Staff Management & Invitations UI

Managing your team just got easier. Spree 5.1 adds a dedicated UI for inviting and managing admin staff, streamlining how teams collaborate on store management.

• ➕ Invite new staff to your admin panel via email, directly from the dashboard
• 🧑‍💼 Assign roles and permissions to control access to specific features
• 🔒 Maintain admin security and auditability at scale
• ✅ Onboard faster without any developer involvement

This new experience brings clarity and control to multi-user admin workflows — essential for growing teams or agencies managing multiple Spree stores.

💳 Enhanced Checkout Experience

Spree 5.1 introduces meaningful improvements to the checkout customization flow — giving you greater flexibility over what your customers see and fill in.

Now you can:

• 🏢 Toggle the company field on or off depending on your audience (B2C vs B2B)
• ✍️ Enable or disable special instructions at checkout for custom delivery notes, gift messages, etc.
• 🎛️ Customize checkout UX to reduce friction or capture only the most relevant info

These options can be toggled directly in the admin dashboard without developer intervention, giving you more control over customer experience and data collection.

📊 Google Analytics 4 Integration — Now Built In!

Want smarter data, right out of the box? Spree 5.1 now supports Google Analytics 4 (GA4) natively!

This integration makes it easy to track user behavior, product performance, and marketing attribution — all directly within your Spree-powered store.

✨ What you get:

• 🧠 Deep insights into how users interact with your site
• 💰 Clear visibility into sales funnels and conversion performance
• 📈 Marketing attribution data to inform campaign strategy

Setup is simple, and the insights will help guide smarter business decisions — from UX improvements to merchandising.

💌 Klaviyo Integration for Smart Marketing Automation

Spree 5.1 now ships with an official Klaviyo integration, helping you level up your email marketing and customer engagement — no extra work required.

🎯 What’s included:

• ✅ Newsletter signup connected out-of-the-box
• 🔁 Dynamic marketing flows triggered by user activity
• 🛍️ Real-time tracking of store events, including:
  • 👀 Product views and searches
  • ➕ Items added or removed from cart
  • 🧾 Checkout progress and coupon usage
  • 📧 Email entry, newsletter opt-ins, and unsubscribes

With Spree + Klaviyo, you can easily set up:

• Abandoned cart flows
• Personalized product recommendations
• Post-purchase follow-ups
• Win-back campaigns

All with precision and automation — right from your Spree storefront.

🚀 Spree Starter Template — Now Updated for Spree 5.1 + Rails 8

Getting started with Spree has never been easier. The Spree Starter Template has been upgraded to support Spree 5.1 and Rails 8 — giving you the fastest way to launch a production-ready eCommerce store with all essentials preconfigured.

🔧 What’s included:

• 🛒 Spree Commerce 5.1
• 💳 Stripe integration (via the official Stripe gem)
• 📊 Google Analytics 4 (official GA4 gem)
• 📬 Klaviyo email marketing (official Klaviyo gem)
• 🔐 Devise for authentication
• ⚙️ Sidekiq for background jobs
• 🐘 PostgreSQL database
• 🧠 Redis caching
• 🕵️ (Optional) Sentry for error & performance monitoring
• 📩 (Optional) SendGrid for transactional email

🧑‍💻 No extra setup needed. Just clone, bundle, and build.

🔮 More Coming Soon…

The Spree team is just getting started.

🧾 Up next:

• Native PayPal integration
• Native Adyen integration
• Advanced multi-tenant features for enterprise setups

We’re continuously expanding Spree’s core capabilities to serve merchants at every stage — from solo founders to multi-brand empires.

🙌 Thanks for your ongoing feedback, contributions, and passion for open-source eCommerce. Let’s keep building the future of commerce — together.

We would especially want to thank community contributors:

• @Raileanv made their first contribution in https://github.com/spree/spree/pull/12725
• @moonlight-rays made their first contribution in https://github.com/spree/spree/pull/12740
• @GigiSan made their first contribution in https://github.com/spree/spree/pull/12760
• @simlegate made their first contribution in https://github.com/spree/spree/pull/12806
• @lovison made their first contribution in https://github.com/spree/spree/pull/12822
• @resool made their first contribution in https://github.com/spree/spree/pull/12846
• @seuros made their first contribution in https://github.com/spree/spree/pull/12855
• @babyfire made their first contribution in https://github.com/spree/spree/pull/12883
• @jhovad made their first contribution in https://github.com/spree/spree/pull/12762

Full Changelog: https://github.com/spree/spree/compare/v5.0.5...v5.1.0

This patch release includes numerous bug fixes, enhancements, performance optimizations, internationalization improvements, and UI tweaks across the Admin, Storefront, Emails, and API layers.

✨ Enhancements

• Brought back Tax Category dropdown in the product form (#12779)
• Improved Admin per-page config handling for Products & Orders
• Added more memoization to speed up product listings and cart item counts (#12811, #12834)
• Allow third-party payment methods to define custom payment behavior
• Enhanced variant option saving in product forms (#12804)
• Extension Generator 2.0 (#12851)
• Included theme generator preferences/sections to simplify customization
• Enhanced product properties display in Storefront (#12828)
• Improved meta tags, JSON-LD product URLs, and SEO (#12827)
• Featured blog posts section added (#12882)

🐛 Bug Fixes

• Fixed broken link when product for a variant is deleted (#12793)
• Fixed missing in order summary layout (#12802)
• Fixed undefined method 'last' for nil edge case (#12806)
• Fixed line item errors on update/destroy in Cart (#12809)
• Fixed storefront address form, Mastercard icon, image editor, blob partials, and more
• Fixed return authorization cache bug (#12864)
• Corrected Japan flag icon typo (#12844)

🌍 Internationalization

• Checkout messages, labels, button texts
• Price filters, pinch-to-zoom help text
• Devise views, store credit, and error notices
• Localized policy pages and improved date formatting

🧪 Developer Experience

• payment_method_icon_tag is now available in Storefront
• Spree::PaymentSource enhancements for gateway customer profiles

🖼️ UI/UX

• Improved alignment of filter inputs
• Square-shaped taxon images fixed
• “Delete” button for uploaded images in Admin is now visible
• Applied Tom Select name as id to prevent UI bugs

Thanks to all the contributors for this release, including:
@lovison, @Vegann, @resool, @mad-eel, @simlegate, @brozek95, @caiodsc