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 ff1ffb5
• FIX void payment when no response_code 7ae4e02
• Fix handling Store mobility-powered associations during store creation 7576468
• Fixed issue #13437 - Promotion rule caching issue when editing rules with associated users or products. e06bc7e
• Simplify and reduce the footprint of Variant#options_text 33687ad
• Speed up quick checkout checks for Order eec85d9
• Fix N+1s and improve the performance of RemoveOutOfStockItems service d5f0803

API

• Fixed N+1 in Storefront API Products endpoint
  d592667

Admin

• Admin: Limit the number of Report line items in web view to 1000 (by default) 0249efb
• Implement allowed_file_types option for spree_file_field af55a5b

Storefront

• Removed canonical-rails as a dependency ebe791c
• Fixed N+1s on Storefront cart
  3b7181e
• Cache Countries/States JSON needed for address form df23bbc
• Fixed: don't update tracking params in checkout if they didn't change ad004a6
• fix: Header overlay is misaligned in page builder 61fd050
• Pagespeed insights adjustments f6c092f
• Fixed: remove double caching of checkout line items
  5c3bb30
• Include translations when fetching product breadcrumb taxons for json-ld e23f2ad
• Added caching for storefront CheckoutHelper#quick_checkout_enabled? 051eedb

Full Changelog: 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:

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:

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:

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:

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 #13381
• Fix Bundler 4.0 compatibility 6f00f1f
• Add observer and ostruct gems for Ruby 3.4+ and Bundler 4.0 compatibility e3eea78
• Include fixtures in the gem as we reference them in factories 46ff9c8

Admin Dashboard

• Fixed Admin profile link active state 70f142b
• Fixed: Include tinymce in admin sprockets manifest 7dcc127

Storefront

• Fix toggle menu #13377

Full Changelog: 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 #13356
• Fixed N+1s and overall performance of SalesTotal report for larger da… by @damianlegawiec in #13358
• Reports improvements by @mad-eel in #13321
• Fixed Docker builds permission issue #13379

Admin Dashboard

• Fixed dialogs and drawers in admin for Safari by @damianlegawiec in #13380

Storefront

• Fix indentation in product details template by @dimidev in #13366

Documentation

• Added PLP user documentation by @jaburghes in #13367

Full Changelog: 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 #13354

API

• Storefront API - Fix line items data in the response after removing a coupon code by @mad-eel in #13336

Admin

• Use Spree Form builder in product form more by @damianlegawiec in #13341

Storefront

• Add Greek country code mapping to svg_country_icon helper by @dimidev in #13353

Documentation

• Updated Posts user documentation by @jaburghes in #13339
• Updated 'Storefront Settings' user doc by @jaburghes in #13340

Full Changelog: 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 #13331
• Fix re-using slugs from history on the same record by @mad-eel in #13329

Admin Dashboard

• Add portal: false to dropdowns inside turbo frames or referencing D… by @damianlegawiec in #13335
• Fix drawer overflow form scroll by @dimidev in #13334

Documentation

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

New Contributors

• @kunalchaudhari made their first contribution in #13317

Full Changelog: 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 #12946
• @kyryloliinyk made their first contribution in #12953
• @jawaria-sparksol made their first contribution in #12954
• @Cichorek made their first contribution in #12986
• @umeshravani made their first contribution in #12998
• @rorimwema made their first contribution in #13042
• @karolina-bronowicka made their first contribution in #13140
• @ahmedelsherif-osama made their first contribution in #13176
• @coderliu made their first contribution in #13222

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

Full Changelog: v5.1.0...v5.2.0

Upgrading from earlier versions?

Please follow our Spree 5.2 upgrade guide.