We're excited to announce Spree Commerce 5.5, a release built around two themes: a faster, smoother developer experience for both human engineers and AI agents, and new commerce primitives for multi-channel, multi-warehouse sellers.

This release includes 500+ commits on top of Spree 5.4. On the developer side, it introduces:

• a new Admin API with a fully-typed TypeScript SDK for back office operations and integrations, and a CLI for humans and agents
• a greatly improved CLI with code generators,
• an automatic upgrade tool
• and 25+ agentic coding skills that turn your coding agent into a Spree expert.

Together, they make building on Spree faster, cheaper in tokens, and harder to get wrong, for people and agents alike.

On the commerce side, 5.5 adds Sales Channels, Stock Reservations, and advanced Order Routing: the primitives multi-channel, multi-warehouse sellers need to model their operations through configuration and clean extension points instead of platform hacks.

Highlights

Admin API v3

Built with the same tech stack as Store API released in Spree 5.4, Admin API v3 brings a modern, fast, and secure API for all back office operations like managing Product Catalog, Orders, Customers, and Store settings.

Supports both JWT authentication and Secret keys for application-to-application integrations such as WMS, OMSes, and other crucial systems required by any medium- to large-sized commerce business.

Every endpoint requires an explicit scope: when creating a secret key you choose read or write access per resource, so each integration touches only the data it needs.

Admin SDK

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

import { createAdminClient } from '@spree/admin-sdk'

const client \= createAdminClient({  
  baseUrl: 'https://your-store.com',  
  secretKey: process.env.SPREE\_SECRET\_KEY, // sk\_xxx — server-side only  
})

// List recent completed orders  
const { data: orders, meta } \= await client.orders.list({  
  status\_eq: 'complete',  
  sort: '-completed\_at',  
  limit: 25,  
})

// Create a purchasable product — pricing lives on variants  
const product \= await client.products.create({  
  name: 'Aero Hoodie',  
  status: 'active',  
  tags: \['new-arrivals'\],  
  variants: \[  
    {  
      sku: 'AERO-HOODIE',  
      prices: \[{ currency: 'USD', amount: '59.00' }\],  
    },  
  \],  
})

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

The developer experience matches the storefront SDK: autocomplete for every endpoint and payload shape, instead of handwritten API calls. The new React admin dashboard is built entirely with this SDK, so the toolchain you integrate with is the one we build ourselves.

Admin CLI: Agentic store management

The way merchants run their stores is shifting from clicking through dashboards to delegating the work to AI agents - assistants that pull up yesterday's orders, restock a sold-out variant, launch a promotion, or chase down a refund on your behalf. With 5.5, the Spree CLI becomes a first-class Admin API client: your entire back office: products, orders, customers, inventory, pricing, promotions, is now reachable from the terminal through one clean, permissioned interface. The same surface your team uses to manage the business is the surface an agent uses to manage it for you.

spree api get /products -q status_eq=active --sort -created_at --limit 10
spree api get /orders/ord_x8k2J9aQ --expand items,payments
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
spree api patch /orders/ord_x8k2J9aQ/cancel
spree api endpoints --resource orders
spree api schema "POST /orders/{id}/refunds"
spree api status

That means tools like Claude Code, Codex, and Cursor can operate your store out of the box - scoped to exactly what you allow, with no custom integration layer to build first. Hand an agent a key, and it can browse your catalog, fulfill orders, and run campaigns autonomously, while you stay in control of the permissions. It's the foundation for a store that increasingly runs itself: as agentic commerce moves from novelty to expectation, your Spree store is already ready to be run by one.

Agentic coding skills and plugins

Agent skills that work with Claude Code, Codex, Cursor, Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ other agentic CLIs.

Over 25 skills to help your agents know Spree architecture, how to work with Spree APIs, upgrade Spree to the latest version, customize core models and workflows, build new features on top of Spree, connect payment gateways or shipping providers, and all in a secure and performant way, enforcing best coding and security practices.

The result: your agent (and your team) write convention-correct, secure, performant Spree code from day one, with less tech debt and faster delivery.

npx skills add spree/agent-skills

With the optional Claude Code plugin bringing Spree expert subagent, safety hooks, and /spree commands!

/plugin marketplace add spree/agent-skills
/plugin install spree@spree

Also, you can now connect the Spree documentation website as an MCP source for your agent.

CLI code generators

Spree CLI now supports even more operations, making development on top of Spree easier than ever. When combined with new code generators, it speeds up development and greatly reduces token consumption for agents. Now with just one command, you can generate a new database model or entire API with Admin UI or an event subscriber to connect Spree quickly with 3rd parties.

Generators also change the economics of agentic development: instead of an agent writing boilerplate token by token, it runs one command, and the generator produces convention-correct code instantly.

spree generate model Brand name:string slug:string:uniq          # runs spree:model  
spree generate api\_resource Brand name:string slug:string:uniq  # runs spree:api_resource — model + Store/Admin API  
spree generate subscriber OmsOrderSync order.completed           # runs spree:subscriber — event subscriber + registration

Sales Channels

Sales channels let you run multiple distinct storefronts or selling contexts from a single Spree instance — each with its own product catalog, order attribution, and routing behavior. A channel might represent a public-facing online store, a wholesale portal, a mobile app, a point-of-sale terminal, or a seasonal microsite.

Sales channels have been one of the most requested features for years. Combined with Markets (introduced in Spree 5.4), they deliver what most teams actually want from multi-store: per-audience catalogs, scheduled publication windows, and per-channel order attribution and routing, all from one backend and one admin.

When an order comes in through a given channel, Spree tags it automatically so you can filter, report, and route fulfillment by channel.

Products can be assigned to one or more channels, giving you precise control over what each audience sees. Each channel assignment carries its own optional publication window, so a product can go live on the point of sale today and in the online store next month.

Common use cases include:

• Online store + POS — keep retail and in-person orders separate for reporting and fulfillment
• B2C + B2B wholesale portal — show different catalogs and pricing to different audiences from one backend
• Marketplace or affiliate channel — attribute orders to the source channel for commission tracking
• Mobile app — route mobile orders separately and track conversion independently
• Seasonal microsite — run a limited-time catalog without affecting your main storefront

Stock Reservations

Stock Reservations are a time-limited soft hold on stock during checkout. When a customer enters checkout, Spree holds the items in their cart for a limited time so other shoppers see reduced availability immediately.

Two customers can no longer both pass the availability check on the same last unit only to have one of them fail at order completion. This is super handy during peak season sales or limited-time drops, and it was one of the most requested features from high-volume sellers.

The reservation window is configurable and releases automatically if the customer doesn't complete the purchase.

Order routing

When an order moves from cart to checkout, Spree decides which Stock Location fulfills it. Order Routing is the system that makes that decision - driven by configurable rules so merchants can express preferences like “fulfill from the customer’s preferred warehouse first,” “minimize the number of split shipments,” or “always pick the closest location.”

Each channel carries its own ordered list of routing rules, so your wholesale channel can fulfill completely differently than your online store. Previously, expressing custom fulfillment logic meant overriding core models and re-testing on every upgrade.

Now you write a custom rule, or replace the whole strategy (for example, delegating routing to an external OMS), through clean extension points. See the custom order routing guide.

Upgrade tool

New CLI also comes with an automatic update command spree upgrade that walks a Spree version upgrade end-to-end inside the dev stack. Runs bundle update, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest, making updating Spree to the latest stack a breeze.

Installation

npx create-spree-app@latest my-store

Updating

npx spree upgrade

For details, please see our Spree 5.4 to 5.5 guide

What's next?

Spree 6 is already in motion: a new React admin dashboard powered by the Admin API, open source multi-vendor support, and a long list of structural cleanups. Follow along on the public 6.0 milestone

If you like what you see, consider giving Spree a GitHub star ⭐

Thank you for supporting Spree open-source ❤️

Discuss

Join our new Discord server to discuss, share feedback, and learn more about this and future versions!

New Contributors

• @caspianlwoods made their first contribution in #14089
• @laaichiu made their first contribution in #14168

Full Changelog: v5.4.2...v5.5.0