Spree Commerce developer docs for AI agents

Website · Next.js Storefront · Documentation · Free Sandbox · API · Roadmap · Discord

Build commerce the way you want it. Spree is an open-source commerce platform with a complete REST API, TypeScript SDKs, a React admin dashboard, and a production-ready Next.js storefront. BSD 3-Clause licensed — keep full ownership of your code, data, and infrastructure.

Teams use Spree to build multi-vendor marketplaces and B2B and wholesale channels, as well as headless DTC, cross-border and omnichannel selling — all from one set of commerce primitives, and all alongside the ERP, PIM, and payment systems you already run.

Use AI agents to build your ecommerce business. Spree ships with a collection of agent skills for coding agents and a local MCP server that allows your to manage your store via chat.

Use Cases

Spree ships commerce primitives, so the same core serves very different businesses.

Multi-vendor Marketplace

Seller onboarding with configurable requirement checklists, orders split per seller at completion, a flexible commission engine, a payout ledger with Stripe Connect, and a dedicated Seller Panel. All in the open-source core.

B2B & Wholesale

Price lists with volume tiers, customer groups, companies with locations, contacts and tax exemptions, catalogs for per-segment assortments, and storefronts gated to approved buyers.

Headless & Omnichannel

Run web storefronts, mobile apps, points of sale, B2B panels and marketplaces off one backend. Channels give each surface its own catalog, pricing, payment methods and order attribution.

The Next.js storefront is one such surface — production-ready, open source, built with Next.js 16, React 19 and TypeScript. Fork it, customize it, deploy it. Try the live demo

Cross-border Commerce

Markets bundle currency, language, payment methods and shipping per region, so each customer sees a localized storefront from a single platform. Translations for product content, EU Omnibus price history and customs duties are built in.

Multi-tenant SaaS Enterprise

Run a SaaS platform where each tenant gets its own isolated store — catalog, orders, customers, payment methods and branding — with staff able to manage several tenants. Requires the Enterprise Edition.

Getting Started

Try it in a sandbox

The fastest way to see Spree is a free sandbox: a hosted store with the admin dashboard and APIs, ready in your browser. Nothing to install — sign in, click Create store, and explore.

Install locally

Copy and paste the following command to your terminal to set up Spree locally in 5 minutes:

npx create-spree-app@latest my-store

This sets up the Spree backend, the React Admin Dashboard, and optionally the Next.js storefront in a monorepo. The storefront is built with Next.js 16, React 19, Tailwind CSS 4, and TypeScript. Admin dashboard uses Vite and TanStack.

You need Node.js 24+ installed and Docker running. Learn more in the installation docs.

Agentic Development

Spree comes with agent skills, which teach Claude Code, Codex, Cursor, Copilot and 60+ other tools Spree's conventions, customization patterns and upgrade flows. It also connects Claude Code, Cursor and VS Code to the documentation MCP server, so your agent can search the latest docs. This is automatically setup for you when you run npx create-spree-app and can be added to existing projects with spree add ai. See the Agentic Development docs for more details.

Features

Everything below ships in this repository under the BSD 3-Clause license.

• REST API & TypeScript SDKs — a REST API for storefronts, admins and sellers, with publishable keys, scoped secret keys, rate limiting and an OpenAPI 3.0 spec. Each provide their own TypeScript SDK.
• React Admin Dashboard — a Vite + React application built on TanStack Router and Query, shadcn/ui and Tailwind. Own it and customize without forking: change navignation, add/remove routes, modify table columns and insert your own UI widgets. Ships with a matching Seller Panel for marketplace vendors.
• Next.js Storefront — open-source storefront built with Next.js 16, React 19, Tailwind CSS 4, and TypeScript. Full shopping experience, multi-region URL routing, Stripe payments (Apple Pay, Google Pay, Klarna, Affirm), customer accounts, and SEO built in. Try the demo
• Spree CLI — manage projects from the terminal (boot, generate, migrate, upgrade) and call the Admin API directly with spree api get/post/... — zero-config in local dev, built for scripts and AI agents.
• MCP Server — a local server that you can connect to Claude, ChatGPT, or any LLM to fully manage your store via natural language.
• Marketplace & Payouts — seller onboarding with a configurable requirements checklist, per-seller order splitting, a commission engine with EU commission taxation, and a payout ledger with Stripe Connect payouts.
• B2B & Wholesale — price lists with volume tiers and negotiated rates, customer groups for segmentation, companies with locations, contacts and validated tax exemptions, and catalogs for per-segment assortments.
• Payments — provider-agnostic payment sessions that finish reliably even when a tab closes. Ships with Stripe, Adyen and PayPal. Add your own with the Payment Provider SDK.
• Promotions & Gift Cards — a rules-based promotions engine for percentage and fixed discounts, free shipping, BOGO offers and coupon codes, plus native store credits and gift cards.
• Fulfillment — shipping, digital delivery and in-store pickup, delivery profiles and zones, multi-location inventory, and returns, exchanges and claims.
• Taxes & Compliance — inclusive or added-on tax, automatic calculation via Avalara and Stripe Tax, cross-border customs fees & duties, and data privacy tooling for GDPR subject requests and EU Omnibus price history.
• Products & Catalog — custom fields on any record, CSV imports and exports, digital products, product tags, a shared media library and bulk operations.
• Provider Contracts — plug your existing stack in rather than replacing it: ERP, PIM, WMS and carriers, DAM, SSO and payouts.
• Security & Identity — OpenID Connect single sign-on for staff and customers, custom auth adapters for any JWT issuer, role-based permissions scoped per store, and a PCI-compliant payment architecture where card data never touches your server.
• MeiliSearch Integration — typo-tolerant product search and faceted filtering, or bring your own search provider.
• Integrations & Extensibility — Event Bus, Webhooks, OpenTelemetry instrumentation, and native integrations (GA4, GTM, Klaviyo).
• Agentic Development — agent skills teaching AI coding agents Spree's conventions and a docs MCP server, both set up with one command (spree add ai), plus LLM-ready documentation (llms.txt, per-page Markdown, offline npm package), and a generated AGENTS.md/CLAUDE.md in every scaffolded project.

Deployment

The Spree backend can be deployed anywhere — cloud, on-prem or VPS. We provide official Docker images and Dockerfiles, so you can use AWS, Azure, GCP, Render, Railway, Fly.io, Heroku, or any other Docker-compatible host. The Next.js storefront can be deployed to Vercel, Netlify, or any Node.js host. See the Deployment Documentation for more details.

Community & Contributing

Spree is an open-source project, and we love contributions in any form — pull requests, issues, feature ideas.

• Follow our Contributing Guide
• Join our Discord to meet other community members
• Browse the Roadmap and open Issues

Spree Enterprise Edition

Spree is built and maintained by a funded team behind the open-source project. Beyond the open-source core, we offer a paid Enterprise Edition for organizations that need additional modules and SLA-backed support.

Enterprise adds B2B approval workflows with role-based approval chains and ERP connectors, marketplace automations such as Shopify and WooCommerce seller sync and advanced reporting, multi-tenant SaaS — running many isolated tenant stores from one deployment, with a super-admin, tenant provisioning and white-label billing — audit logging and encryption at-rest, and SLA support with a dedicated success manager, LTS releases and 24/7 monitoring.

Everything else — the APIs, the SDKs, the dashboard, marketplace, B2B and cross-border — is in this repository. Enterprise Edition builds on the same BSD 3-Clause core, so your team keeps full ownership of the code, the data, and the infrastructure. Zero platform fees. Zero transaction fees.

Contact our Sales team for an Enterprise Edition demo, or join Discord to use the open-source edition with the community.

License

Spree Commerce core code in the spree/spree repository is released under the free, open-source BSD-3-Clause license (LICENSE).

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

Thank you for supporting Spree open-source ❤️