v5.4.1

What's Changed

Core

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

API

• Add store resolution to webhook payments controller by @damianlegawiec in #13910
• Consolidate customer creation params and support current_password by @damianlegawiec in #13912
• Added missing totals for DeliveryRate and Fulfillment by @damianlegawiec in #13916

Admin

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

Documentation

• Added user docs for translations and multi-currency imports by @jaburghes in #13896
• SDK docs fixes: use media instead of images and custom_fields i… by @damianlegawiec in #13906

New Contributors

• @55728 made their first contribution in #13889

Full Changelog: v5.4.0...v5.4.1

@spree/sdk@1.0.1

What's Changed

• Added ability to extend SDK, plus improved documentation and tutorial by @damianlegawiec in #13913
• Added missing totals for DeliveryRate and Fulfillment by @damianlegawiec in #13916

Full Changelog: https://github.com/spree/spree/compare/@spree/sdk@1.0.0...@spree/sdk@1.0.1

@spree/sdk@1.0.0

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

v5.4.0

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 #13718

Full Changelog: v5.3.5...v5.4.0

v5.4.0.rc3

🇪🇺 EU omnibus directive support added

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 persisted in the database automatically.

#13817

Other changes

Core

• Gift Card fixes by @damianlegawiec in #13819
• Bring back add_search_scope for Product to ease migration path by @damianlegawiec in #13816

API

• Split discount codes and gift cards into separate cart endpoints. Rename couponCodes to discountCodes and add dedicated giftCards resource be59a63
• Add cart warnings system for out-of-stock/discontinued items 332592d
• Add Store Policies API endpoint f031b80
• Move password resets to top-level Store API route b52e666

Install

npx create-spree-app@latest my-store

Updating

npx spree update

Full Changelog: v5.4.0.rc2...v5.4.0.rc3

v5.4.0.rc2

Agents-native development from the start!

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!

Other changes

Core

• Improve extensibility of Meilisearch search provider by @damianlegawiec in #13810

API

• Add description_html field to Product type. The description field… by @damianlegawiec in #13811
• Store API final fixes by @damianlegawiec in #13813
• Add support for Store Credits and Gift Cards on cart/checkout by @damianlegawiec in #13814

Admin

• FIX preserve search, filters, and sort across admin table forms by @damianlegawiec in #13805
• Fix banktransfer.svg dimensions to match other payment icons by @damianlegawiec in #13807
• FIX admin mobile sidebar menu not opening (Tailwind v4 conflict) by @damianlegawiec in #13809
• FIX zones form and builder by @brozek95 in #13815

Full Changelog: v5.4.0.rc1...v5.4.0.rc2

v5.4.0.rc1

We're excited to announce the first Release Candidate of 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 500+ commits on top of Spree 5.3 and introduces a new API layer, TypeScript SDK, Next.js storefront, 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.

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

Additional Improvements

• @spree/next package — Next.js integration library with server actions, automatic cookie management, and full TypeScript support
• Publishable & Secret API keys — clean separation between client-safe storefront keys (pk_live_) and server-only admin keys (sk_live_)

Feedback

This is a Release Candidate — we'd love your feedback before the stable release. Please report any issues on GitHub Issues and join the discussion on Slack

---

New Contributors

• @samuel-sarmah made their first contribution in #13718

Full Changelog: v5.3.5...v5.4.0.rc1

v5.3.5

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 638e31d
• FIX gift card overspend race condition potential vulnerability 1ab03d5
• Fix: Replace deprecated Image#plp_url with cdn_image_url variant(:xlarge) b3e259c
• Fix Order#order_refunded? method when store credits are used d2b9257

API

• Improved webhooks SSRF protection 3c7fc53

Admin

• Fix toggling clear filter button 98211d8
• handle custom model class in exports#new 4cf12b4

Update

Run in your project root:

bundle update

Full Changelog: v5.3.4...v5.3.5

v5.3.4

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 (#13618)
• Fix deleting products w/o translations on non-default locale (#13613)

Admin

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

Update

Run in your project root:

bundle update

Full Changelog: v5.3.3...v5.3.4

v5.3.3

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 b7d053b
• Prevent NoMethodError in StoreProduct#refresh_metrics! when product is nil by @damianlegawiec in #13531

Admin

• Fixed validation error on admin address for not persisted address by @brozek95 in #13526
• Fixed edit policy path to use ID rather than slug e1f69b5

Update

Run in your project root:

bundle update

Full Changelog: v5.3.2...v5.3.3