Spree Commerce API v3 & the Next.js Storefront Starter for Amazing Shopping Experiences
Your commerce backend should accelerate what you build — not dictate how you build it. With the new Storefront API v3 and an official Next.js starter, Spree 5 gives product teams and agencies the fastest path from idea to production-grade storefront using a free open-source eCommerce stack.
The Stack That Changes the Game
For years, the promise of headless commerce has been simple: separate the frontend from the backend so each can evolve on its own terms.
In practice, most platforms — proprietary and open-source eCommerce alike — delivered a mediocre API bolted onto a monolith, leaving teams to paper over the gaps with custom middleware, fragile workarounds, and months of integration effort.
Spree 5 takes a different approach. The new Storefront API v3 was designed from the ground up — not patched onto an aging codebase — and the Next.js Storefront Starter is a production-ready reference implementation that puts it all to work.
Together, they give engineering teams a complete, modern open-source eCommerce foundation for building commerce experiences that unlock developer productivity, security, and scalable growth.
Storefront API v3: A Modern API for Modern Frontends
A great open-source eCommerce API should feel like a product, not an afterthought. The previous generation of Spree’s API (v2) served the community well, but it carried the complexity of the JSON:API specification and struggled with performance at scale. API v3 is a clean break.
Simple, flat JSON responses. No more navigating nested JSON:API relationship graphs. The new response format is a straightforward JSON structure with an optional include parameter for expanding related resources — an approach inspired by Stripe’s API. If you have ever integrated with Stripe, you already know the pattern.
Dramatically faster. The v3 endpoints are engineered for performance from the start. Large product catalogs, complex variant trees, and high-traffic storefronts all benefit from a response pipeline that was benchmarked against real-world datasets, delivering major performance improvements over v2.
Security by design. Every API call is scoped to a publishable API key, giving operators granular control over which storefronts and applications can access their data. Authentication uses JWT tokens with OpenID Connect support, and the prefixed-ID format (e.g., prod_M4ytmZ7snPvnvkVE1dmQpbGn) means raw database identifiers are never exposed to the outside world. Native integrations with the Stripe payment gateway and Adyen payment platform bring the same security-first philosophy to payments.
Developer-first tooling. API documentation is generated automatically from request specs with verified responses — so the docs are always in sync with the actual behavior. TypeScript types are auto-generated from the Rails serializers, and the official @spree/sdk typed TypeScript client gives JavaScript and TypeScript developers an idiomatic interface for every endpoint. Filtering, sorting, and searching are powered by Ransack, and pagination uses the Pagy library for optimized performance. For a deeper look at the developer experience, see developer tools for eCommerce engineering productivity.
For teams that have existing v2 integrations, the transition is smooth: API v2 continues to receive security patches through the spree_legacy_api_v2 gem, so you can migrate at your own pace.
The Next.js Storefront Starter: From Zero to Storefront
The official Next.js Storefront Starter is not a proof-of-concept or a weekend hackathon demo. It is a production-grade, fully featured open-source eCommerce storefront built on Next.js 16, React 19, Tailwind CSS 4, and TypeScript 5 — the cutting edge of the React ecosystem.
What you get out of the box
- Complete product catalog with variant selection, faceted filtering, and search
- Shopping cart with server-side state management
- Full account management — profile, order history, saved addresses, and payment methods
- Multi-region support with country and currency switching
- Responsive, mobile-first design built with Tailwind CSS 4
- Sentry integration for error tracking and performance monitoring from day one
A server-first architecture
The starter follows a strict server-first pattern that reflects Next.js best practices. Every API call runs server-side through Next.js Server Actions. JWT authentication tokens live in httpOnly cookies — never accessible to client-side JavaScript. Your Spree API credentials never touch the browser. And Next.js cache tags handle intelligent data revalidation so pages stay fast without serving stale content.
This architecture means your storefront delivers Next.js eCommerce performance and security, and gives search engines fully rendered pages to index.
Two packages, one clean integration
The starter is built on two official TypeScript packages:
@spree/sdk— The core SDK for the Spree Storefront API, with full TypeScript types auto-generated from the backend serializers@spree/next— Next.js-specific integration including server actions, caching strategies, and cookie-based authentication helpers
Getting started requires just three things: Node.js 20+, a running Spree backend, and two environment variables (SPREE_API_URL and SPREE_PUBLISHABLE_KEY). From there, you are up and running.
How the Pieces Fit Together
The architecture is deliberately simple — and it is one of the key advantages of building on an open-source eCommerce platform. Your Next.js storefront — whether deployed on Vercel, Netlify, or self-hosted — talks to the Spree backend exclusively through the Storefront API v3.
The backend handles all the commerce logic: catalog management, inventory, pricing, promotions, taxes, shipping, and checkout. The frontend handles the experience: layout, interaction design, performance optimization, and brand expression.
For a detailed look at Spree’s modular architecture, the backend is distributed as a set of composable packages — use only what you need.
This separation means your frontend team can ship design changes, A/B tests, and new features without touching the commerce backend. Your backend team can update business logic, add integrations, and scale infrastructure without breaking the storefront.
And if you decide next year that you want a React Native mobile app, a Vue.js microsite, or a ChatGPT Instant Checkout shopping assistant, they all connect to the same API. Read more about why pairing an open-source eCommerce backend with Next.js delivers a future-proof platform.
Spree Natively Supports the Complex Commerce Scenarios
One of Spree’s defining strengths as an open-source eCommerce platform is that the hard problems of commerce are solved at the platform level, not punted to third-party plugins or custom code.
Out of the box, Spree handles:
Multi-store eCommerce. Run multiple storefronts from a single backend — each with its own domain, branding, catalog, and configuration — while sharing infrastructure and a unified admin dashboard. This is ideal for businesses managing regional storefronts, sub-brands, or distinct customer segments.
Multi-currency and multi-language eCommerce. Sell globally with localized pricing, translated content, and region-specific tax and shipping rules. Spree’s multi-region operations support is built into the data model, not layered on as an afterthought.
B2B and wholesale commerce. Support customer-specific pricing, volume discounts, purchase orders, and approval workflows alongside your B2C storefront — or as a standalone operation.
Customer-specific price lists and customer group segmentation. Spree 5 introduced a native price list engine that lets you define different pricing strategies based on customer zone, specific users, or order quantity — with priority-based resolution and scheduling. Combine price lists with customer groups to target segments like wholesale accounts, VIP buyers, or regional customers with personalized pricing and exclusive promotions, all configurable from the admin dashboard without custom code.
Promotions and pricing rules. A powerful, rule-based promotions engine supports percentage discounts, free shipping, buy-one-get-one, tiered pricing, and custom promotion types — all manageable from the admin dashboard. Promotions can be scoped to customer groups for segment-specific campaigns.
These are not features you configure through a marketplace of third-party apps with uncertain maintenance windows. They are part of the core platform, maintained by the same team that builds everything else.
Enterprise Edition: Purpose-Built Modules for Complex Commerce
For businesses whose requirements go beyond what any open-source eCommerce community edition can cover, Spree Enterprise Edition adds purpose-built modules that would otherwise require months of custom development:
Multi-vendor marketplace. Full vendor management with automated vendor onboarding, marketplace vendor dashboards, automated integrations with Shopify and WooCommerce for catalog sync, and per-vendor reporting. Build your own marketplace where third-party sellers list and fulfill their own products. See the full list of marketplace capabilities.
Multi-tenant eCommerce.True data isolation between tenants, centralized infrastructure management, and configurable autonomy levels — from tightly controlled platform-owner models to fully autonomous tenant operations. This is the foundation for building your own SaaS commerce platform or managing a network of franchise and reseller stores. Explore the full multi-tenant eCommerce capabilities.
Multi-brand enterprise. Run several independent storefronts representing distinct brands, regions, or divisions on shared infrastructure. Each brand gets full autonomy while the parent organization maintains operational efficiency and consistency.
Advanced security and governance. Configurable user roles, comprehensive audit logging, and enhanced access controls give enterprises the compliance and governance tooling they need. See the full security-hardened architecture overview.
Each of these modules is maintained by the core Spree team — the same engineers who build the platform itself.
Enterprise Support from the Team That Builds the Platform
When you choose Spree Enterprise, your support comes directly from the people who write the code. Not a reseller. Not a partner channel. Not a contractor who learned the platform last month.
This matters when you hit an edge case in multi-currency tax calculation at 2 AM before Black Friday. It matters when you need a custom integration with a logistics provider that no one else uses. It matters when you are planning a migration and need an honest assessment of the effort involved.
The team that builds the platform understands it at the deepest level, and that understanding translates directly into faster resolution times, better architectural guidance, and a support experience that actually moves your business forward.
No SaaS Will Ever Match What an Empowered Team Can Build
There is a reason the most ambitious commerce brands — from Goop to Blue Bottle Coffee, from GoDaddy to Huckberry, from Craftsman and Kenmore to DieHard — run on open-source eCommerce foundations rather than SaaS platforms. The reason is control.
A SaaS platform gives you a checkbox feature set that works the same way for everyone. When your business needs something the platform was not designed for — a unique checkout flow, a custom pricing model, a proprietary logistics integration — you hit a wall. You can request a feature, join a waitlist, or build a workaround that breaks with the next platform update.
An empowered in-house team or agency working with Spree and Next.js has no walls. Every line of code is yours to read, modify, and extend. Every architectural decision is yours to make. Every deployment happens on your timeline, in your infrastructure, under your control.
This is not a philosophical argument — it is a practical one. The businesses that win in commerce are the ones that can move fastest when the market shifts, that can deliver experiences their competitors literally cannot replicate, and that own their technology stack rather than renting it.
With Spree 5’s API v3 and the Next.js Storefront Starter, the barrier to entry for this approach has never been lower. You get a production-ready starting point, a modern API, typed SDKs, and the full power of the React and Next.js ecosystem.
AI Changes the Economics of Custom Development
There is a new variable in the build-vs-buy equation that did not exist two years ago: AI-assisted development. Tools like Claude, Cursor, and GitHub Copilot have fundamentally changed how fast a small team can move.
Boilerplate that used to take days now takes minutes. Integration code that required deep framework expertise can be scaffolded by an AI pair programmer that already knows the SDK.
This shift disproportionately favors teams building on open, well-documented platforms. A SaaS platform with a proprietary API and closed documentation gives AI tools very little to work with.
An open-source eCommerce platform like Spree — with public open source code, auto-generated TypeScript types, OpenAPI specs, and comprehensive eCommerce API documentation — is exactly the kind of codebase that AI development tools excel at navigating.
The practical implication: the team size and budget required to build and maintain a custom storefront on an open-source eCommerce backend like Spree 5, paired with Next.js, has dropped dramatically.
The practical implication: the team size and budget required to build and maintain a custom storefront on an open-source eCommerce backend like Spree 5, paired with Next.js, has dropped dramatically. What once required a large agency engagement can now be accomplished by a lean team augmented with AI tooling.
The Storefront API v3’s Stripe-inspired design patterns, the typed SDK, and the Next.js Starter all compound this advantage — they give AI assistants clean, predictable structures to reason about and extend.
And for backend-heavy teams that lack dedicated frontend designers, Vercel’s v0.app closes the gap entirely: describe the storefront you want in plain English, get production-ready Next.js components back, and wire them to the Storefront API. The design-to-implementation cycle that used to require a frontend agency can now happen in an afternoon.
This is why the timing matters. The combination of a modern API, a production-ready starter, AI coding assistants, and AI-powered storefront design with v0 means that AI-aided development of shopping experiences is no longer a future promise — it is the current workflow. Teams who previously dismissed open-source eCommerce as too expensive or too complex should reconsider the math.
Already on Spree? Here Is Your Path Forward
One of the advantages of choosing an established open-source eCommerce platform is that upgrade paths are well-documented and community-tested. If you are already running a Spree-powered store, the path to API v3 and a Next.js frontend is designed to minimize disruption.
Upgrading your Spree backend to v5 can be done incrementally. The Spree 5 migration guides walk you through each step, and because API v2 remains supported through a compatibility gem, your existing frontend continues to work throughout the transition. You can adopt v3 endpoints one at a time, validating each integration before moving on. For a detailed walkthrough, see how to migrate your eCommerce backend to Spree 5 while keeping your decoupled frontend.
Migrating your frontend to Next.js does not require a big-bang rewrite. The Storefront Starter gives you a complete reference implementation, so you can lift proven patterns — authentication flows, cart management, product display logic — and adapt them to your existing design system. Teams that already run a decoupled frontend can point it at the new v3 endpoints with minimal changes; teams moving from a monolithic Rails frontend can use the starter as their new foundation. For a step-by-step guide, read how to lift and shift your Next.js storefront to a headless eCommerce backend.
Either way, you end up with a modern, maintainable open-source eCommerce stack that is ready for whatever comes next.
Get Started
Spree is open-source eCommerce built for developers, and the documentation is comprehensive. Here is where to begin:
- Next.js Storefront Starter — Clone it, configure two environment variables, and you have a running storefront
- Storefront API v3 Documentation — Full endpoint reference with auto-generated, verified examples
- Open-source eCommerce platform on GitHub — The platform itself, with over 13 years of active development
- Enterprise Edition for complex commerce scenarios — For multi-vendor, multi-tenant, and multi-brand requirements
- Build a Next.js eCommerce storefront tutorial — End-to-end tutorial for building your first storefront
- eCommerce API for a Next.js headless storefront — Deep dive into the headless architecture
Your open-source eCommerce platform should be the foundation that makes everything else possible — not the constraint that holds you back. With Spree 5, that foundation is ready.
