spree 5.4.0 on Ruby Gems

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.

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