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']
});