# Spree Commerce documentation

## Guides

### Getting Started

#### Getting started

- [Installing Spree](https://spreecommerce.org/docs/developer/getting-started/quickstart.md): Install Spree Commerce locally with Docker or Ruby on Rails, run your first store, and deploy it to production with the official starter template.

#### Platform

- [Architecture](https://spreecommerce.org/docs/developer/core-concepts/architecture.md): Explore how Spree's core models, APIs, and gems fit together — catalog, shopping, checkout, fulfillment, and pricing — for headless or embedded commerce.
- [Stores](https://spreecommerce.org/docs/developer/core-concepts/stores.md): Understand Spree Stores — the top-level tenant boundary that scopes products, orders, channels, markets, and branding, with the Admin API for store config.
- [Channels](https://spreecommerce.org/docs/developer/core-concepts/channels.md): Per-store distribution surfaces — online storefront, POS, marketplace, wholesale — each with its own product catalog and order attribution.
- [Markets](https://spreecommerce.org/docs/developer/core-concepts/markets.md): Configure Spree Markets to bundle geography, currency, and locale into distinct selling regions and run multi-region commerce from a single store.
- [Customers](https://spreecommerce.org/docs/developer/core-concepts/customers.md): How Spree models customer accounts — registration, authentication, addresses, order history, store credits, and guest checkout behavior.
- [Staff & Roles](https://spreecommerce.org/docs/developer/core-concepts/staff-roles.md): Manage Spree admin users, roles, invitations, and permissions — create admins via the CLI, scope access per store, and customize role-based permissions.

#### Catalog

- [Products](https://spreecommerce.org/docs/developer/core-concepts/products.md): How Spree models products, variants, option types, images, prices, and categories — the building blocks of every catalog and storefront.
- [Pricing](https://spreecommerce.org/docs/developer/core-concepts/pricing.md): Prices, Price Lists, Price Rules, and the Pricing Context — Spree's flexible pricing engine for regional, wholesale, volume, and market-based pricing.
- [Inventory](https://spreecommerce.org/docs/developer/core-concepts/inventory.md): Stock locations, stock items, stock movements, and inventory tracking
- [Media](https://spreecommerce.org/docs/developer/core-concepts/media.md): Manage product media in Spree — images, videos, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
- [Search & Filtering](https://spreecommerce.org/docs/developer/core-concepts/search-filtering.md): Use Ransack-style query parameters to search, filter, sort, and paginate products, taxons, and other resources through the Spree Store API.

#### Cart & Checkout

- [Orders](https://spreecommerce.org/docs/developer/core-concepts/orders.md): How Spree models orders — the cart-to-completion lifecycle, checkout state machine, line items, payments, shipments, and order totals.
- [Payments](https://spreecommerce.org/docs/developer/core-concepts/payments.md)
- [Taxes](https://spreecommerce.org/docs/developer/core-concepts/taxes.md): Tax categories, tax rates, zones, and how Spree calculates taxes at checkout
- [Promotions](https://spreecommerce.org/docs/developer/core-concepts/promotions.md): Build percentage and fixed-amount discounts, free shipping, BOGO offers, and coupon codes with Spree's rule and action-based promotion system.
- [Store Credits & Gift Cards](https://spreecommerce.org/docs/developer/core-concepts/store-credits-gift-cards.md): How Spree models store credits and gift cards — stored value balances, redeemable codes, and checkout usage for refunds, loyalty, and gifting.

#### Fulfillment

- [Shipments](https://spreecommerce.org/docs/developer/core-concepts/shipments.md): How Spree models shipments, shipping methods, calculators, stock locations, split shipments, and the fulfillment workflow from order to delivery.
- [Addresses](https://spreecommerce.org/docs/developer/core-concepts/addresses.md): How Spree models addresses, countries, states, and zones, and how geographic data drives checkout, tax calculation, and shipping rates.
- [Adjustments](https://spreecommerce.org/docs/developer/core-concepts/adjustments.md): How Spree adjustments apply taxes, promotions, and other price modifications to orders, line items, and shipments, and how totals are recalculated.
- [Calculators](https://spreecommerce.org/docs/developer/core-concepts/calculators.md)

#### Extensibility

- [Events](https://spreecommerce.org/docs/developer/core-concepts/events.md): Spree's event system — publish and subscribe to lifecycle events from orders, products, and users to trigger background jobs and integrations.
- [Webhooks](https://spreecommerce.org/docs/developer/core-concepts/webhooks.md): Send real-time HTTP notifications to external services when events occur in your store.
- [Translations](https://spreecommerce.org/docs/developer/core-concepts/translations.md): Translate Spree products, taxons, and other store content into multiple languages using Mobility-backed translations and locale-aware APIs.
- [Slugs](https://spreecommerce.org/docs/developer/core-concepts/slugs.md): How Spree generates SEO-friendly URL slugs for products, categories, and stores, and how to look up resources by slug or ID via the API.
- [Metafields](https://spreecommerce.org/docs/developer/core-concepts/metafields.md): Add custom structured data to products, orders, and other resources with type-safe metafields
- [Reports](https://spreecommerce.org/docs/developer/core-concepts/reports.md)
- [Imports & Exports](https://spreecommerce.org/docs/developer/core-concepts/imports-exports.md)

### Building a Storefront

#### Next.js Storefront

- [Quickstart](https://spreecommerce.org/docs/developer/storefront/nextjs/quickstart.md): Get started with the Spree Next.js Storefront
- [Architecture](https://spreecommerce.org/docs/developer/storefront/nextjs/architecture.md): Server-first architecture, project structure, and auth flow
- [Multi-Region](https://spreecommerce.org/docs/developer/storefront/nextjs/multi-region.md): How the Spree Next.js Storefront serves multiple countries, currencies, and languages from a single deployment via URL segments and edge middleware
- [Customization](https://spreecommerce.org/docs/developer/storefront/nextjs/customization.md): Customize and extend the Spree Next.js Storefront
- [Transactional Emails](https://spreecommerce.org/docs/developer/storefront/nextjs/emails.md): Render and send order, shipment, and account emails from the Spree Next.js Storefront with react-email, Resend, and Spree webhooks
- [Wholesale Portal](https://spreecommerce.org/docs/developer/storefront/nextjs/wholesale.md): The opt-in B2B wholesale surface and how channel-backed surfaces work
- [Wallet Payments in Development](https://spreecommerce.org/docs/developer/storefront/nextjs/wallet-payments.md): Test Apple Pay and Google Pay against a local Spree Next.js Storefront using a public HTTPS URL
- [Testing](https://spreecommerce.org/docs/developer/storefront/nextjs/testing.md): Run the Spree Next.js Storefront's unit tests with Vitest and its end-to-end suite with Playwright against a real Spree backend
- [Environment Variables](https://spreecommerce.org/docs/developer/storefront/nextjs/environment-variables.md): Every environment variable the Spree Next.js Storefront reads, with defaults and when to set it
- [Deployment](https://spreecommerce.org/docs/developer/storefront/nextjs/deployment.md): Deploy the Spree Next.js Storefront to Vercel, Docker, or any Node.js host

### Use Cases

#### Multi-Tenant / Multi-Store

- [Create a multi-tenant / SaaS platform on top of Spree](https://spreecommerce.org/docs/developer/multi-tenant/quickstart.md): Set up Spree as a multi-tenant SaaS ecommerce platform — install the Enterprise gem, apply license keys, configure subdomains, and provision tenants.
- [Multi-Tenant Core Concepts](https://spreecommerce.org/docs/developer/multi-tenant/core-concepts.md): Understand the Spree multi-tenant architecture, including the Tenant class, row-level tenant isolation, tenanted models, and automatic seeding for new tenants.
- [Spree Multi Tenant Configuration](https://spreecommerce.org/docs/developer/multi-tenant/configuration.md): Configure Spree multi-tenant SaaS deployments — set the app subdomain, reserved subdomains, tenant signup flow, and other initializer options.

#### Multi-Vendor Marketplace

- [Building a Multi-Vendor Marketplace with Spree](https://spreecommerce.org/docs/developer/multi-vendor/quickstart.md)
- [Spree Multi Vendor Installation](https://spreecommerce.org/docs/developer/multi-vendor/installation.md): Install and configure Spree Multi-Vendor to launch a marketplace with multiple vendors, including prerequisites, gem setup, license keys, and vendor onboarding.

## Framework

### Extending

#### Tutorial

- [Tutorial](https://spreecommerce.org/docs/developer/tutorial/introduction.md): Build a complete custom Brands feature in Spree — model, admin UI, Store and Admin APIs, events, and TypeScript storefront integration — end to end.
- [Model](https://spreecommerce.org/docs/developer/tutorial/model.md): Create a custom Brand model in Spree with database columns, a rich text description, and an Active Storage logo upload using a single generator command.
- [Admin Dashboard](https://spreecommerce.org/docs/developer/tutorial/admin.md): Scaffold the Spree admin UI for the Brands resource and add a rich text description editor, an Active Storage logo upload, and a custom table column.
- [Extending Core Models](https://spreecommerce.org/docs/developer/tutorial/extending-models.md): Tutorial — extend Spree's core models with a custom Brand resource, generate a migration, and associate it with Products via a decorator.
- [Expose a custom model through the Store and Admin APIs](https://spreecommerce.org/docs/developer/tutorial/api.md): Expose your custom Brand model through the Spree Store and Admin REST APIs with serializers, controllers, routes, and the spree:api_resource generator.
- [Events & Webhooks](https://spreecommerce.org/docs/developer/tutorial/events.md): React to Spree store activity and connect to external systems like an OMS, warehouse, or ERP using event subscribers, the subscriber generator, and webhooks.
- [SDK](https://spreecommerce.org/docs/developer/tutorial/sdk.md): Use the Spree TypeScript SDK to consume your custom Brand endpoints, fetch extended Product data, and surface the new resource in your headless storefront.
- [Testing](https://spreecommerce.org/docs/developer/tutorial/testing.md): Write automated tests for the Brands tutorial feature using RSpec, Factory Bot, and Capybara, plus helpers from the spree_dev_tools gem.

#### Admin Panel

- [Admin Dashboard](https://spreecommerce.org/docs/developer/admin/admin.md): Customize and extend the Spree Admin Dashboard to manage products, orders, customers, promotions, and store settings for your ecommerce platform.
- [Extending Admin Dashboard UI](https://spreecommerce.org/docs/developer/admin/extending-ui.md): Inject custom partials into Spree Admin Dashboard pages using injection points to add fields, buttons, and sections without modifying core code.
- [Extending Admin Navigation](https://spreecommerce.org/docs/developer/admin/navigation.md)
- [Admin Tables](https://spreecommerce.org/docs/developer/admin/tables.md): Use the Spree Admin Tables DSL to define columns, sorting, filtering, and bulk actions for resource listings, and extend existing admin tables.
- [Admin Form Builder API](https://spreecommerce.org/docs/developer/admin/form-builder.md)
- [Admin Components](https://spreecommerce.org/docs/developer/admin/components.md)
- [Admin Dashboard Helper Methods](https://spreecommerce.org/docs/developer/admin/helper-methods.md)
- [Admin Panel Authentication](https://spreecommerce.org/docs/developer/admin/authentication.md): How to customize the Spree admin panel authentication
- [Custom JavaScript for Admin Dashboard](https://spreecommerce.org/docs/developer/admin/custom-javascript.md): Learn how to add custom JavaScript to your Spree Admin Dashboard
- [Admin Dashboard Custom CSS](https://spreecommerce.org/docs/developer/admin/custom-css.md): Customize the Spree Admin Dashboard with your own CSS by overriding Tailwind variables, adding custom styles, and extending admin views and helpers.

#### Customization Reference

- [Quickstart](https://spreecommerce.org/docs/developer/customization/quickstart.md): Recommended ways to customize Spree — store settings, configuration, events, webhooks, dependencies, admin extensions, and decorators as a last resort.
- [Configuration](https://spreecommerce.org/docs/developer/customization/configuration.md)
- [Authentication](https://spreecommerce.org/docs/developer/customization/authentication.md): Integrate Spree with a custom authentication setup, including Devise, an existing user model, OmniAuth providers, and JWT or OAuth API tokens.
- [Checkout Flow](https://spreecommerce.org/docs/developer/customization/checkout.md): Customize the Spree checkout flow with the checkout DSL — add, remove, or conditionally skip address, delivery, payment, and confirmation steps.
- [Permissions](https://spreecommerce.org/docs/developer/customization/permissions.md)
- [Dependencies](https://spreecommerce.org/docs/developer/customization/dependencies.md)
- [Decorators](https://spreecommerce.org/docs/developer/customization/decorators.md): Use Spree decorators to add or modify behavior on core models, controllers, and helpers without forking the gem — patterns, file layout, and pitfalls.
- [Model Preferences](https://spreecommerce.org/docs/developer/customization/model-preferences.md): Add typed configuration options to Spree models using model preferences, including supported types, default values, and reading or writing stored values.
- [Metadata](https://spreecommerce.org/docs/developer/customization/metadata.md)
- [Routes](https://spreecommerce.org/docs/developer/customization/routes.md): Learn how to customize the routes in Spree
- [Customizing the Spree API](https://spreecommerce.org/docs/developer/customization/api.md): Add new Store API endpoints, customize existing JSON responses with serializer decorators, and extend Spree's REST API to fit your storefront needs.

### How-to Guides

#### Order Routing

- [Build Custom Order Routing](https://spreecommerce.org/docs/developer/how-to/custom-order-routing.md): Step-by-step guide to extending Spree's order routing — write custom rules to add new signals, or a custom strategy to replace the algorithm entirely.

#### Stock Splitters

- [Build a Custom Stock Splitter](https://spreecommerce.org/docs/developer/how-to/custom-stock-splitter.md): Step-by-step guide to extending Spree's stock splitter chain — break a location's allocation into multiple shipments along your own axis (refrigeration, gift wrap, bin size, hazmat, anything you need to physically separate).

#### Payments

- [Build a Custom Payment Method](https://spreecommerce.org/docs/developer/how-to/custom-payment-method.md): Step-by-step guide to creating a custom payment gateway integration with Payment Sessions, 3D Secure, and PCI compliance.

#### Promotions

- [Build Custom Promotion Rules & Actions](https://spreecommerce.org/docs/developer/how-to/custom-promotion.md): Step-by-step guide to creating custom promotion rules and actions for business-specific eligibility logic and discount behaviors.

#### Reports

- [Build a Custom Report](https://spreecommerce.org/docs/developer/how-to/custom-report.md): Step-by-step guide to creating custom reports with data queries, line item formatters, and CSV export.

#### Search

- [Build a Custom Search Provider](https://spreecommerce.org/docs/developer/how-to/custom-search-provider.md): Step-by-step guide to building a custom search provider for Spree, integrating external search engines like Typesense, Algolia, or Elasticsearch.

#### Authentication

- [Integrate a Third-Party Identity Provider](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication.md): Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store and Admin APIs.

### Operations

#### Deployment

- [Deployment Overview](https://spreecommerce.org/docs/developer/deployment/quickstart.md): Run Spree anywhere — any cloud, any database, from a single container to a globally distributed stack.
- [Docker](https://spreecommerce.org/docs/developer/deployment/docker.md): Build a production Docker image of your Spree project, or run the official prebuilt image.
- [Environment Variables](https://spreecommerce.org/docs/developer/deployment/environment_variables.md): Reference for Spree deployment environment variables — database, web server, background jobs, SMTP, file storage, and application settings.
- [Render](https://spreecommerce.org/docs/developer/deployment/render.md): Deploy your Spree project to Render — one Docker service, one Postgres.
- [Assets](https://spreecommerce.org/docs/developer/deployment/assets.md)
- [Sending out Emails](https://spreecommerce.org/docs/developer/deployment/emails.md): Learn how to send transactional emails from your Spree application.
- [CDN](https://spreecommerce.org/docs/developer/deployment/cdn.md): Learn how to improve performance of your Spree application by using a CDN (Content Delivery Network).
- [Background Jobs](https://spreecommerce.org/docs/developer/deployment/background_jobs.md): Spree's background jobs live in your database by default (Solid Queue) — nothing extra to run, with a Sidekiq/Redis swap for very high volume.
- [Caching](https://spreecommerce.org/docs/developer/deployment/caching.md): Spree's cache lives in Postgres by default (Solid Cache) — nothing extra to run, with a one-line Redis/Valkey swap for high-traffic installs.
- [Database Configuration](https://spreecommerce.org/docs/developer/deployment/database.md): Learn how to configure Spree to work with PostgreSQL, MySQL, or SQLite.

##### AWS

- [AWS — EC2 + RDS](https://spreecommerce.org/docs/developer/deployment/aws.md): The simplest production Spree on AWS — one EC2 instance and a managed database.
- [AWS — ECS Fargate](https://spreecommerce.org/docs/developer/deployment/aws_ecs.md): Production-grade Spree on AWS — ECS Fargate, RDS, CI/CD, and auto-scaling.

#### Upgrading

- [Quickstart](https://spreecommerce.org/docs/developer/upgrades/quickstart.md): Learn how to upgrade your Spree application

##### Upgrade Guides

- [Upgrading to Spree 5.6](https://spreecommerce.org/docs/developer/upgrades/5.5-to-5.6.md): Step-by-step guide to upgrading a Spree 5.5 application to Spree 5.6, including gem updates, migrations, data backfills, and breaking changes to review.
- [Upgrading to Spree 5.5](https://spreecommerce.org/docs/developer/upgrades/5.4-to-5.5.md): Step-by-step guide to upgrading a Spree 5.4 application to Spree 5.5, including gem updates, migrations, and breaking changes to review.
- [Upgrading to Spree 5.4](https://spreecommerce.org/docs/developer/upgrades/5.3-to-5.4.md): Upgrade a Spree 5.3 application to Spree 5.4 — remove spree_sample, update gems, run migrations, switch to AdminUserMethods, and backfill image thumbnail IDs.
- [Upgrading to Spree 5.3](https://spreecommerce.org/docs/developer/upgrades/5.2-to-5.3.md): This guide covers upgrading a Spree 5.2 application to Spree 5.3.
- [Upgrading to Spree 5.2](https://spreecommerce.org/docs/developer/upgrades/5.1-to-5.2.md): This guide covers upgrading a Spree 5.1 application to Spree 5.2.
- [Upgrading to Spree 5.1](https://spreecommerce.org/docs/developer/upgrades/5.0-to-5.1.md): This guide covers upgrading a Spree 5.0 application to Spree 5.1.
- [Upgrading to Spree 5.0](https://spreecommerce.org/docs/developer/upgrades/4.10-to-5.0.md): This guide covers upgrading a Spree 4.10 application to Spree 5.0.
- [Upgrading to Spree 4.10](https://spreecommerce.org/docs/developer/upgrades/4.9-to-4.10.md): This guide covers upgrading a Spree 4.9 application to Spree 4.10.
- [Upgrading to Spree 4.9](https://spreecommerce.org/docs/developer/upgrades/4.8-to-4.9.md): This guide covers upgrading a Spree 4.8 application to Spree 4.9.
- [Upgrading to Spree 4.8](https://spreecommerce.org/docs/developer/upgrades/4.x-to-4.8.md): This guide covers upgrading a Spree 4 application to Spree 4.8.
- [4.6 to 4.7](https://spreecommerce.org/docs/developer/upgrades/4.6-to-4.7.md): This guide covers upgrading a 4.6 Spree application to Spree 4.7.
- [4.5 to 4.6](https://spreecommerce.org/docs/developer/upgrades/4.5-to-4.6.md): This guide covers upgrading a 4.5 Spree application to Spree 4.6.
- [4.4 to 4.5](https://spreecommerce.org/docs/developer/upgrades/4.4-to-4.5.md): This guide covers upgrading a 4.4 Spree application to Spree 4.5
- [4.3 to 4.4](https://spreecommerce.org/docs/developer/upgrades/4.3-to-4.4.md): This guide covers upgrading a 4.3 Spree application to Spree 4.4.
- [4.1 to 4.2](https://spreecommerce.org/docs/developer/upgrades/4.1-to-4.2.md): This guide covers upgrading a 4.1 Spree application to Spree 4.2.
- [4.0 to 4.1](https://spreecommerce.org/docs/developer/upgrades/4.0-to-4.1.md): This guide covers upgrading a 4.0 Spree application to Spree 4.1.
- [3.7 to 4.0](https://spreecommerce.org/docs/developer/upgrades/3.7-to-4.0.md): This guide covers upgrading a 3.7 Spree application to Spree 4.0.
- [3.6 to 3.7](https://spreecommerce.org/docs/developer/upgrades/3.6-to-3.7.md): This guide covers upgrading a 3.6 Spree application, to version 3.7.
- [3.5 to 3.6](https://spreecommerce.org/docs/developer/upgrades/3.5-to-3.6.md): This guide covers upgrading a 3.5 Spree application, to a 3.6 application.
- [3.4 to 3.5](https://spreecommerce.org/docs/developer/upgrades/3.4-to-3.5.md): This guide covers upgrading a 3.4 Spree store, to a 3.5 store.
- [3.3 to 3.4](https://spreecommerce.org/docs/developer/upgrades/3.3-to-3.4.md): This guide covers upgrading a 3.3 Spree store, to a 3.4 store.
- [3.2 to 3.3](https://spreecommerce.org/docs/developer/upgrades/3.2-to-3.3.md): This guide covers upgrading a 3.2 Spree store, to a 3.3 store.
- [3.1 to 3.2](https://spreecommerce.org/docs/developer/upgrades/3.1-to-3.2.md): This guide covers upgrading a 3.1 Spree store, to a 3.2 store.
- [3.0 to 3.1](https://spreecommerce.org/docs/developer/upgrades/3.0-to-3.1.md): This guide covers upgrading a 3.0 Spree store, to a 3.1 store
- [2.3 to 2.4](https://spreecommerce.org/docs/developer/upgrades/2.3-to-2.4.md): This guide covers upgrading a 2.3 Spree store, to a 2.4 store.
- [2.2 to 2.3](https://spreecommerce.org/docs/developer/upgrades/2.2-to-2.3.md): This guide covers upgrading a 2.2 Spree store, to a 2.3 store.
- [2.1 to 2.2](https://spreecommerce.org/docs/developer/upgrades/2.1-to-2.2.md): This guide covers upgrading a 2.1 Spree store, to a 2.2 store.
- [2.0 to 2.1](https://spreecommerce.org/docs/developer/upgrades/2.0-to-2.1.md): This guide covers upgrading a 2.0 Spree store, to a 2.1 store.

#### Contributing

- [Contributing quickstart](https://spreecommerce.org/docs/developer/contributing/quickstart.md): Get started contributing to Spree — fix bugs, add features, build extensions, upgrade old extensions, report issues, and help the community on Discord.
- [Developing Spree](https://spreecommerce.org/docs/developer/contributing/developing-spree.md): Set up a Spree Commerce development environment with Docker, run the RSpec test suite, follow coding conventions, and submit pull requests upstream.
- [Creating a Spree extension](https://spreecommerce.org/docs/developer/contributing/creating-an-extension.md): Step-by-step guide to building a Spree extension gem — scaffolding, decorators, migrations, assets, and packaging for distribution on GitHub.

#### Security

- [Security Policy](https://spreecommerce.org/docs/developer/security/security_policy.md): How to report vulnerabilities, supported versions, and Spree's security practices.
- [PCI Compliance](https://spreecommerce.org/docs/developer/security/pci_compliance.md)

## SDK & Tools

### Store SDK

#### Getting Started

- [Spree TypeScript SDK quickstart for the Store API](https://spreecommerce.org/docs/developer/sdk/quickstart.md): Install @spree/sdk, configure the Store API client, and make your first calls to products, carts, checkout, and customer account endpoints from TypeScript.
- [Authentication](https://spreecommerce.org/docs/developer/sdk/authentication.md): Authentication modes and guest checkout with the Spree SDK
- [Configuration](https://spreecommerce.org/docs/developer/sdk/configuration.md): Configure the Spree JavaScript SDK — localization, currency headers, error handling, TypeScript types, and a custom fetch implementation.
- [Custom Endpoints](https://spreecommerce.org/docs/developer/sdk/extending.md): Call your own custom Store API endpoints from the Spree TypeScript SDK using the built-in request method, with typed responses and shared auth handling.

#### Store API

- [Products & Categories](https://spreecommerce.org/docs/developer/sdk/store/products.md): Browse products and categories with the Spree SDK
- [Cart, Checkout & Orders](https://spreecommerce.org/docs/developer/sdk/store/cart-checkout.md): Manage carts, line items, coupons, checkout flow, and completed orders with the Spree SDK
- [Payments & Delivery](https://spreecommerce.org/docs/developer/sdk/store/payments.md): Handle payments, payment sessions, and delivery with the Spree SDK
- [Markets](https://spreecommerce.org/docs/developer/sdk/store/markets.md): Use the Spree Storefront SDK to list markets, resolve a market by country, and fetch the countries available within each market for checkout.
- [Customer Account](https://spreecommerce.org/docs/developer/sdk/store/account.md): Manage customer profiles, addresses, and credit cards with the Spree SDK
- [Wishlists](https://spreecommerce.org/docs/developer/sdk/store/wishlists.md): Manage wishlists and wished items with the Spree SDK

### Admin SDK

#### Admin SDK

- [Admin SDK quickstart for @spree/admin-sdk](https://spreecommerce.org/docs/developer/sdk/admin/quickstart.md): Install and configure @spree/admin-sdk, the official TypeScript client for the Spree Admin API v3, to manage products, orders, customers, and stock.
- [Admin SDK authentication with API keys and JWT cookies](https://spreecommerce.org/docs/developer/sdk/admin/authentication.md): Authenticate @spree/admin-sdk with a secret API key for server-to-server, scope-based access or JWT cookie auth for role-based browser admin apps.
- [Admin SDK resources and CRUD client methods](https://spreecommerce.org/docs/developer/sdk/admin/resources.md): Reference for every @spree/admin-sdk resource — products, orders, customers, inventory, pricing, promotions, store configuration, and platform clients.
- [Filtering, pagination, and error handling in the Admin SDK](https://spreecommerce.org/docs/developer/sdk/admin/querying-and-errors.md): Filter, sort, paginate, and expand Admin API collections with flat Ransack parameters and handle structured SpreeError responses from @spree/admin-sdk.
- [Custom Admin Endpoints](https://spreecommerce.org/docs/developer/sdk/admin/extending.md): Call custom Admin API endpoints using the SDK's built-in request method

### CLI

#### CLI

- [Spree CLI](https://spreecommerce.org/docs/developer/cli/quickstart.md): Install and use the @spree/cli to scaffold, run, build, and migrate Spree projects — and call the Admin API directly from the command line.
- [Call the Admin API from the CLI](https://spreecommerce.org/docs/developer/cli/admin-api.md): Use spree api for generic get/post/patch/delete calls, schema introspection, and zero-config credentials — built for scripts and AI agents.

### create-spree-app

#### create-spree-app

- [create-spree-app](https://spreecommerce.org/docs/developer/create-spree-app/quickstart.md): Scaffold a new Spree Commerce project with a single command — bootstraps a full Rails backend, Docker dev stack, and the @spree/cli for customization.

### Agentic Development

#### Agentic Development

- [Agentic Development](https://spreecommerce.org/docs/developer/agentic/overview.md): Build, customize, and upgrade Spree stores with AI coding agents using installable agent skills, a documentation MCP server, and LLM-ready docs.
- [Agent Skills](https://spreecommerce.org/docs/developer/agentic/agent-skills.md): Teach your AI coding agent Spree's conventions — 25 installable skills, a Spree expert subagent, slash commands, and safety hooks.
- [Docs MCP Server](https://spreecommerce.org/docs/developer/agentic/mcp.md): Connect Claude, Cursor, or any MCP-compatible AI agent to the Spree docs MCP server to search and read the latest documentation while building.
- [LLM-Ready Documentation](https://spreecommerce.org/docs/developer/agentic/llm-docs.md): Every page of the Spree docs is consumable by LLMs — llms.txt indexes, per-page Markdown, and a local npm package for offline agent reads.

- [API Reference (634 pages)](https://spreecommerce.org/docs/_llms/api-reference.md): Documentation for API Reference.

## Integrations

### Integrations

- [3rd party integrations](https://spreecommerce.org/docs/integrations/integrations.md): Browse Spree's third-party integrations for payments, shipping, tax, search, analytics, marketing, and AI to extend your storefront.

### Payments

- [Connect Stripe payments to Spree Commerce](https://spreecommerce.org/docs/integrations/payments/stripe.md): Set up Spree's native Stripe integration to accept cards and alternative payment methods, automate payouts, and power marketplace split payments on Enterprise.
- [Connect Adyen payments to Spree Commerce](https://spreecommerce.org/docs/integrations/payments/adyen.md): Set up Spree's native Adyen integration to accept global payments across multiple methods, with built-in fraud protection and a seamless checkout experience.
- [Connect PayPal payments to Spree Commerce](https://spreecommerce.org/docs/integrations/payments/paypal.md): Enable Spree's native PayPal integration to accept PayPal, Pay Later (BNPL), Venmo, and guest checkout payments without forcing shoppers to create an account.
- [Connect Razorpay payments to Spree Commerce](https://spreecommerce.org/docs/integrations/payments/razorpay.md): Configure the Razorpay payment gateway in Spree to accept cards, UPI, net banking, and wallets, plus international transactions across multiple currencies.

### Tax

- [Connect Avalara AvaTax to Spree Commerce](https://spreecommerce.org/docs/integrations/tax/avalara.md): Set up Spree's native Avalara AvaTax integration to automate sales tax, VAT, exemptions, and address validation on every checkout.

### Search

- [Meilisearch](https://spreecommerce.org/docs/integrations/search/meilisearch.md): Set up Meilisearch in Spree for fast, typo-tolerant product search with faceted filtering, relevance ranking, and sub-50ms responses across large catalogs.

### Analytics

- [Connect Google Analytics 4 to Spree Commerce](https://spreecommerce.org/docs/integrations/analytics/google-analytics.md): Set up Spree's native Google Analytics 4 integration to track ecommerce events, user behavior, and sales performance across your store with no custom code.
- [Connect Google Tag Manager to Spree Commerce](https://spreecommerce.org/docs/integrations/analytics/google-tag-manager.md): Connect Spree's native Google Tag Manager integration to push ecommerce dataLayer events for GA4, Google Ads, Meta Pixel, and other marketing tags.

### Marketing

- [Connect Klaviyo email marketing platform to Spree Commerce](https://spreecommerce.org/docs/integrations/marketing/klaviyo.md): Connect Spree to Klaviyo to sync customer profiles, track ecommerce events, and power email and SMS marketing automations, segmentation, and newsletter signups.

## User Guide

### Introduction

- [What is Spree Commerce](https://spreecommerce.org/docs/user/what-is-spree-commerce.md): What is Spree Commerce? What can I build with Spree?
- [Using Spree Commerce](https://spreecommerce.org/docs/user/using-spree.md): How do I start using Spree for my project? Should I pick the free open-source Community Edition? What is the pricing for the Enterprise Edition?
- [User Quickstart](https://spreecommerce.org/docs/user/user-quickstart-guide.md): Launch a Spree Commerce store fast: configure payments and taxes, add products, set a support email, and complete the Getting Started onboarding checklist.

### Migration

- [Migrate from Shopify](https://spreecommerce.org/docs/user/migration/migrate-from-shopify.md): Step-by-step guide to migrating your products and customers from Shopify to Spree Commerce using CSV imports

### How-to Guides

- [Set Up Multi-Currency Pricing](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing.md): Learn how to configure your store to display and sell in multiple currencies.
- [Set Up Multiple Languages](https://spreecommerce.org/docs/user/how-to/multiple-languages.md): Learn how to sell in multiple languages by configuring locales, translating products, categories, and policies in Spree Commerce.
- [Set Up Multi-Region Pricing](https://spreecommerce.org/docs/user/how-to/multi-region-pricing.md): Learn how to charge different prices within the same currency across multiple regional markets.
- [Set Up Wholesale Pricing](https://spreecommerce.org/docs/user/how-to/wholesale-pricing.md): Learn how to offer wholesale pricing to specific customer groups using Price Lists in Spree Commerce.
- [Set Up Volume Pricing](https://spreecommerce.org/docs/user/how-to/volume-pricing.md): Learn how to offer tiered discounts based on order quantity using Price Lists in Spree Commerce.
- [Set Up Regional Wholesale Pricing](https://spreecommerce.org/docs/user/how-to/regional-wholesale.md): Learn how to offer market-specific wholesale pricing to trade customers across multiple regions.
- [Set Up Regional Volume Pricing](https://spreecommerce.org/docs/user/how-to/regional-volume.md): Learn how to offer market-specific volume discounts across multiple regions using Price Lists in Spree Commerce.
- [Schedule a Sale](https://spreecommerce.org/docs/user/how-to/schedule-sale-pricing.md): Learn how to use Price Lists to schedule time-limited sale pricing across your catalog, including market-specific discounts.

### Products

#### Create & Edit Products

- [Create a Product](https://spreecommerce.org/docs/user/products/creating-products.md): Step-by-step guide to creating a product in the Spree admin, including media, pricing, variants, inventory, shipping, and digital downloads.
- [Delete a Product](https://spreecommerce.org/docs/user/products/deleting-products.md): Learn how to delete a product in Spree Commerce.
- [Edit a Product](https://spreecommerce.org/docs/user/products/editing-products.md): Learn how to edit a product in Spree Commerce.
- [Edit a Multi-Variant Product](https://spreecommerce.org/docs/user/products/editing-multi-variant-products.md): Learn how to edit a multi-variant product in Spree Commerce.
- [Clone a Product](https://spreecommerce.org/docs/user/products/cloning-products.md): Learn how to clone a product in Spree Commerce.

#### Manage Products

- [Searching Products](https://spreecommerce.org/docs/user/manage-products/search-products.md): Learn how to search for products in the Spree Commerce dashboard.
- [Bulk Product Operations](https://spreecommerce.org/docs/user/manage-products/bulk-product-operations.md): Learn how to perform bulk product operations in Spree Commerce.
- [Price Lists](https://spreecommerce.org/docs/user/manage-products/price-lists.md): Learn how to set up volume pricing, user-specific pricing, and more in Spree Commerce.
- [Export Products](https://spreecommerce.org/docs/user/manage-products/export-products.md): Learn how to export your product catalog in Spree Commerce.
- [Import Products](https://spreecommerce.org/docs/user/manage-products/import-products.md): How to import products files in the Spree Commerce dashboard.
- [Multi-Currency Import/Export](https://spreecommerce.org/docs/user/manage-products/multi-currency-import-export.md): Learn how to import and export product prices across multiple currencies in Spree Commerce.
- [Import File Template](https://spreecommerce.org/docs/user/manage-products/product-import-file-template.md): Download a product import file template for Spree Commerce open-source
- [Translations](https://spreecommerce.org/docs/user/manage-products/translations.md): Learn how to manage and track product translations across all your store's locales in Spree Commerce.
- [Stock Levels](https://spreecommerce.org/docs/user/manage-products/stock-levels.md): Learn how to manage stock levels in Spree Commerce.
- [Stock Transfers](https://spreecommerce.org/docs/user/manage-products/stock-transfers.md): Learn how to create stock transfers in the Spree Commerce.
- [Taxonomies](https://spreecommerce.org/docs/user/manage-products/product-taxonomies.md): Learn how to create and manage product taxonomies in the Spree Commerce dashboard.
- [Product Options](https://spreecommerce.org/docs/user/manage-products/product-options.md): How to manage product options in the Spree Commerce open-source dashboard
- [Product Metafields](https://spreecommerce.org/docs/user/manage-products/product-metafields.md): Learn how to use product metafields in Spree Commerce to enrich your product data.

### Orders

- [Order States](https://spreecommerce.org/docs/user/orders/order-states.md): Learn how to use order states to track and manage orders in Spree Commerce.
- [Processing Orders](https://spreecommerce.org/docs/user/orders/processing-orders.md): Learn how to process orders in the Spree Commerce admin dashboard,
- [Creating Orders](https://spreecommerce.org/docs/user/orders/creating-orders.md): Learn how to manually create orders as an admin in Spree Commerce.
- [Editing Orders](https://spreecommerce.org/docs/user/orders/editing-orders.md): Learn how to edit existing orders in Spree Commerce.
- [Order Adjustments](https://spreecommerce.org/docs/user/orders/order-adjustments.md): Learn how to create and settle order adjustments in Spree Commerce.
- [Export Orders](https://spreecommerce.org/docs/user/orders/exporting-orders.md): Learn how to export orders to CSV in Spree Commerce.
- [Cancelling Orders](https://spreecommerce.org/docs/user/orders/cancelling-orders.md): Learn how to cancel orders in Spree Commerce.
- [Refunding Orders](https://spreecommerce.org/docs/user/orders/refunding-orders.md): Learn how to refund orders in Spree Commerce.
- [Searching Orders](https://spreecommerce.org/docs/user/orders/searching-orders.md): Learn how to search and filter orders in Spree Commerce.

### Returns

- [Returns Configuration](https://spreecommerce.org/docs/user/settings/returns-configuration.md): Learn how to define return authorization reasons, refund reasons, and reimbursement types.
- [Returns Processing](https://spreecommerce.org/docs/user/returns/returns-processing.md): Learn how to process returns in Spree Commerce.

### Customers

- [Create a Customer](https://spreecommerce.org/docs/user/customers/create-customer.md): Learn how to create new customers in Spree Commerce as an admin.
- [Customer Profiles](https://spreecommerce.org/docs/user/customers/customer-profile.md): Learn how to access and interpret the Customer Profile in the Spree admin dashboard.
- [Editing Customers](https://spreecommerce.org/docs/user/customers/edit-customer.md): Learn how to edit customer profiles in the Spree Commerce admin dashboard.
- [Issue a Gift Card](https://spreecommerce.org/docs/user/customers/issue-gift-card.md): Learn how to issue gift cards to customers in the Spree admin dashboard.
- [Issue Store Credits](https://spreecommerce.org/docs/user/customers/assign-store-credits.md): Learn how to issue store credits to customers in the Spree admin dashboard.
- [Searching Customers](https://spreecommerce.org/docs/user/customers/searching-customers.md): Learn how to search for customers in the Spree admin dashboard.
- [Export Customers](https://spreecommerce.org/docs/user/customers/exporting-customers.md): Learn how to export customers records to CSV in Spree Commerce.
- [Segment shoppers with Customer Groups](https://spreecommerce.org/docs/user/customers/customer-groups.md): Create Customer Groups in Spree to segment shoppers and tailor pricing, promotions, tax rules, and access for B2B accounts, VIPs, or wholesale buyers.

### Promotions

- [Create a Promotion](https://spreecommerce.org/docs/user/promotions/create-a-promotion.md): Learn to how to create and configure promotions in Spree Commerce.
- [Promotion Rules](https://spreecommerce.org/docs/user/promotions/promotion-rules.md): Learn how to use promotion rules in Spree Commerce.
- [Promotion Actions](https://spreecommerce.org/docs/user/promotions/promotion-actions.md): Learn how to use promotion actions in Spree Commerce.
- [Gift Cards](https://spreecommerce.org/docs/user/promotions/gift-cards.md): Learn how to create individual or bulk gift cards in Spree Commerce.

### Vendors

- [Marketplace Configuration](https://spreecommerce.org/docs/user/settings/marketplace.md): Learn how to configure marketplace-wide settings for your multi-vendor marketplace in Spree Commerce.
- [Shopify Vendor Onboarding](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-shopify.md): Learn how to invite and onboard a Shopify-based vendor to your multi-vendor marketplace in Spree Commerce.
- [WooCommerce Vendor Onboarding](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-woocommerce.md): Learn how to invite and onboard a WooCommerce-based vendor to your multi-vendor marketplace in Spree Commerce.
- [Manual/CSV Vendor Onboarding](https://spreecommerce.org/docs/user/vendors/vendor-onboarding-manual.md): Learn how to invite and onboard a vendor who'll upload products manually or via CSV to your multi-vendor marketplace in Spree Commerce.
- [Vendor Management](https://spreecommerce.org/docs/user/vendors/vendor-management.md): Learn how to view, manage, and configure vendors from the admin dashboard in Spree Commerce.
- [Commission Rates](https://spreecommerce.org/docs/user/vendors/commission-rates.md): Learn how to set and override commission rates across your multi-vendor marketplace in Spree Commerce.
- [Vendor Payouts](https://spreecommerce.org/docs/user/vendors/vendor-payouts.md): Learn how to set and override vendor payout schedules across your multi-vendor marketplace in Spree Commerce.
- [Multi-Vendor Checkout](https://spreecommerce.org/docs/user/vendors/multi-vendor-checkout.md): Learn how multi-vendor checkout works in Spree Commerce — customers shop across multiple vendors in a single cart and complete one unified checkout.

### Settings

- [Store Details](https://spreecommerce.org/docs/user/settings/store-details.md): Learn how to configure your store's core settings in Spree Commerce.
- [Sales Channels](https://spreecommerce.org/docs/user/settings/sales-channels.md): Create and manage sales channels in Spree to run multiple storefronts, B2B portals, POS, and mobile apps with per-channel catalogs and order attribution.
- [Users](https://spreecommerce.org/docs/user/settings/users.md): Invite, edit, and manage admin users in the Spree dashboard — send invitations, assign roles, track pending invites, and control backend access for your team.
- [Emails](https://spreecommerce.org/docs/user/settings/emails.md): Configure how your store communicates with customers via email.
- [Policies](https://spreecommerce.org/docs/user/settings/policies.md): Learn how to set up and manage store policies in Spree Commerce.
- [Payments](https://spreecommerce.org/docs/user/settings/payments.md): Learn how to view, add, edit, and remove payment methods in Spree.
- [Markets](https://spreecommerce.org/docs/user/settings/markets.md): Learn how to create and manage markets in Spree Commerce.
- [Zones](https://spreecommerce.org/docs/user/settings/zones.md): In this Spree user doc, you’ll learn how to create, edit and delete zones.
- [Shipping Methods](https://spreecommerce.org/docs/user/settings/shipping-methods.md): Learn how to set up shipping methods in Spree Commerce.
- [Tax](https://spreecommerce.org/docs/user/settings/tax.md): Learn how to configure tax rates and categories for your Spree store.
- [Stock Locations](https://spreecommerce.org/docs/user/settings/locations.md): Learn how to create and manage stock locations in Spree Commerce.
- [Metafield Definitions](https://spreecommerce.org/docs/user/settings/metafields.md): Define and manage custom metafields in Spree to attach extra structured data to products, orders, and other store objects without code changes.

### Security

- [Enterprise Edition Security Overview](https://spreecommerce.org/docs/user/security.md): Learn how Spree Enterprise is built to meet the highest standards of data protection and risk management.

## Solutions

### Overview

- [Spree Commerce Use Cases](https://spreecommerce.org/docs/use-case/overview.md): Explore Spree Commerce use cases: multi-vendor marketplaces, multi-tenant SaaS, B2B ecommerce, digital products, and Agentic Commerce integration.

### B2B Commerce

- [B2B Commerce Model](https://spreecommerce.org/docs/use-case/b2b/b2b-commerce-model.md): Learn about the B2B commerce model and how Spree Commerce supports it.
- [B2B Capabilities](https://spreecommerce.org/docs/use-case/b2b/b2b-capabilities.md): Learn how Spree Commerce supports B2B commerce operations, from open-source features to enterprise-grade workflows.
- [B2B Admin Capabilities](https://spreecommerce.org/docs/use-case/b2b/b2b-admin-capabilities.md): Learn how Spree empowers merchants to manage B2B buyers, pricing, and workflows.
- [B2B Buyer Experience](https://spreecommerce.org/docs/use-case/b2b/b2b-buyer-capabilities.md): Learn how Spree delivers a purchasing experience tailored to B2B buyers.

### Digital Products

- [Digital Products Model](https://spreecommerce.org/docs/use-case/digital-products/model.md): Learn about the digital product ecommerce model with Spree Commerce.
- [Digital Products Capabilities](https://spreecommerce.org/docs/use-case/digital-products/capabilities.md): Sell digital products in Spree with download access limits, expiring links, digital-only checkout, multiple delivery channels, and metafield support.
- [Digital Products Admin Capabilities](https://spreecommerce.org/docs/use-case/digital-products/admin-capabilities.md): Learn about the digital product features available in the Spree admin dashboard.

### Multi-Tenant Platform

- [Multi-Tenant Model](https://spreecommerce.org/docs/use-case/multi-tenant/multi-tenant-model.md): How the Spree Enterprise multi-tenant model works: isolated tenant stores, shared infrastructure, and centralized management for SaaS and franchise platforms.
- [Multi-Tenant Capabilities](https://spreecommerce.org/docs/use-case/multi-tenant/multi-tenant-capabilities.md): Build multi-tenant ecommerce platforms with Spree Enterprise: tenant provisioning, master catalogs, billing models, centralized payments, and white-labeling.
- [Super Admin Capabilities](https://spreecommerce.org/docs/use-case/multi-tenant/super-admin-capabilities.md): Super admin controls for Spree multi-tenant platforms: tenant onboarding, master catalogs, payments, fulfillment, billing, and white-label storefront tools.
- [Tenant Capabilities](https://spreecommerce.org/docs/use-case/multi-tenant/tenant-capabilities.md): Learn how tenants can manage their stores in Spree Enterprise Edition.
- [Franchises & Reseller Networks](https://spreecommerce.org/docs/use-case/multi-tenant/franchises-and-reseller-networks.md): Run franchise and reseller networks on Spree Enterprise with a shared product catalog, centralized fulfillment, and consistent branding across stores.
- [Multi-Brand Enterprises](https://spreecommerce.org/docs/use-case/multi-tenant/multi-brand-enterprise-model.md): Learn how multi-brand enterprises can leverage a multi-tenant architecture.
- [White-Label SaaS Platforms](https://spreecommerce.org/docs/use-case/multi-tenant/white-label-saas.md): Learn how to build white-label SaaS platforms with Spree Enterprise Edition.

### Multi-Vendor Marketplace

- [Marketplace Model](https://spreecommerce.org/docs/use-case/marketplace/model.md): Learn about the multi-vendor marketplace ecommerce model.
- [Marketplace Capabilities](https://spreecommerce.org/docs/use-case/marketplace/capabilities.md): Build a multi-vendor marketplace with Spree Enterprise: vendor onboarding, Shopify and WooCommerce integrations, Stripe Connect payouts, and order splitting.
- [Marketplace Admin Panel](https://spreecommerce.org/docs/use-case/marketplace/admin-dashboard.md): Learn about the Spree multi-vendor marketplace admin UX.
- [Marketplace Vendor Panel](https://spreecommerce.org/docs/use-case/marketplace/vendor-dashboard.md): Learn about the Spree multi-vendor marketplace vendor UX.
- [Marketplace Customer Experience](https://spreecommerce.org/docs/use-case/marketplace/customer-ux.md): Learn about the Spree multi-vendor marketplace customer UX.

## OpenAPI Specs

- [store](/docs/api-reference/store.yaml)
- [admin](/docs/api-reference/admin.yaml)
- [storefront](/docs/api-reference/storefront.yaml)
- [platform](/docs/api-reference/platform.yaml)
- [oauth](/docs/api-reference/oauth.yml)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [API Reference (634 pages)](https://spreecommerce.org/docs/_llms/api-reference.md): Documentation for API Reference.
- [API Reference / Admin API (232 pages)](https://spreecommerce.org/docs/_llms/api-reference/admin-api.md): REST API for pragmatically managing stores
- [API Reference / Legacy API v2 (313 pages)](https://spreecommerce.org/docs/_llms/api-reference/legacy-api-v2.md): Previous-generation Storefront and Platform APIs