# Spree Commerce documentation: v6.x Documentation

## Documentation

### Develop

#### Getting Started

- [Installing Spree](https://spreecommerce.org/docs/developer/getting-started/quickstart.md): Install Spree Commerce locally, run your first store, and deploy it to production with the official starter template.
- [Architecture](https://spreecommerce.org/docs/developer/core-concepts/architecture.md): How Spree fits together — the catalog, the cart, the order, and fulfillment — and the two APIs you build against.

#### Core Concepts

##### Platform

- [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.
- [Data Privacy](https://spreecommerce.org/docs/developer/core-concepts/data-privacy.md): How Spree supports GDPR subject requests, consent records, the EU Omnibus price history, and the right of withdrawal.
- [Companies](https://spreecommerce.org/docs/developer/core-concepts/companies.md): B2B buyers as organizations — a company tree with members, shared addresses, and purchases made on the company's behalf.
- [Sellers](https://spreecommerce.org/docs/developer/core-concepts/sellers.md): Running a marketplace — vendors with their own catalog and panel, orders split per seller, and commission on every sale.
- [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.
- [Catalogs](https://spreecommerce.org/docs/developer/core-concepts/catalogs.md): Showing different products and prices to different audiences — a wholesale range, a channel-specific selection, or one company's negotiated pricing.
- [Inventory](https://spreecommerce.org/docs/developer/core-concepts/inventory.md): How Spree tracks stock across locations — what's on hand, what's spoken for, and what a shopper is allowed to buy.
- [Media](https://spreecommerce.org/docs/developer/core-concepts/media.md): The store-wide media library — uploading once and reusing everywhere, images and video, focal points, and how files are resized and served.
- [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

- [Carts](https://spreecommerce.org/docs/developer/core-concepts/carts.md): How Spree models the shopping and checkout phase — a cart collects items and customer details, then completing it creates an order.
- [Orders](https://spreecommerce.org/docs/developer/core-concepts/orders.md): How Spree models orders — a permanent record created by completing a cart, with separate payment and delivery statuses.
- [Order Totals](https://spreecommerce.org/docs/developer/core-concepts/order-totals.md): How an order total is built up from items, tax, discounts, delivery and fees — and how to render a summary that adds up.
- [Payments](https://spreecommerce.org/docs/developer/core-concepts/payments.md): Taking money — payment methods, payment sessions, saved cards, refunds, and how a payment finishes reliably even when a customer closes the tab.
- [Taxes](https://spreecommerce.org/docs/developer/core-concepts/taxes.md): How Spree works out tax — tax categories and rates, inclusive versus added-on pricing, and connecting an external tax service.
- [Discounts](https://spreecommerce.org/docs/developer/core-concepts/discounts.md): The record of money taken off one order — where a discount comes from, and why it is spread across the items it applied to.
- [Fees](https://spreecommerce.org/docs/developer/core-concepts/fees.md): Surcharges added to an order — handling, gift wrap, cash on delivery — and customs duties on cross-border sales.
- [Commissions](https://spreecommerce.org/docs/developer/core-concepts/commissions.md): What a marketplace charges its sellers — rates and the rules that target them, how a fee is calculated, and the settlement record left behind.
- [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

- [Fulfillments](https://spreecommerce.org/docs/developer/core-concepts/fulfillments.md): How Spree models getting items to the customer — fulfillments, delivery methods and zones, and delivery types covering shipping, digital and pickup.
- [Delivery setup](https://spreecommerce.org/docs/developer/core-concepts/delivery-setup.md): How delivery is configured in Spree — profiles that decide how a product ships, zones that decide where, methods the customer picks, and where rates come from.
- [Freight](https://spreecommerce.org/docs/developer/core-concepts/freight.md): How wholesale orders ship — the carton and pallet chain a product declares, the logistics rollup a forwarder quotes against, and rates that carry no price yet.
- [Returns, Exchanges & Claims](https://spreecommerce.org/docs/developer/core-concepts/returns-exchanges-claims.md): How Spree models what happens after a customer receives an order — three separate records for money back, different items, and something gone wrong.
- [Addresses](https://spreecommerce.org/docs/developer/core-concepts/addresses.md): How Spree handles addresses, country and state data, and building address forms that adapt to the country a customer picks.
- [Calculators](https://spreecommerce.org/docs/developer/core-concepts/calculators.md): The small pieces of arithmetic behind delivery charges and promotion discounts — what each one does and how to choose between them.

##### Extensibility

- [Events](https://spreecommerce.org/docs/developer/core-concepts/events.md): Reacting to things that happen in Spree — an order placed, a payment taken, stock running out — without modifying core code.
- [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): Selling in more than one language — translating content
- [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.
- [Custom Fields](https://spreecommerce.org/docs/developer/core-concepts/metafields.md): Add your own structured, typed data to products, orders and other records — searchable, filterable, and editable in the dashboard.
- [External References](https://spreecommerce.org/docs/developer/core-concepts/external-references.md): Record the keys your ERP, PIM, DAM or CRM knows each record by, and address Spree records with those keys instead of Spree IDs.
- [Imports & Exports](https://spreecommerce.org/docs/developer/core-concepts/imports-exports.md): Moving data in and out of Spree as CSV — bulk catalog updates, customer lists, and order extracts.
- [Reporting](https://spreecommerce.org/docs/developer/core-concepts/reporting.md): The semantic layer behind the dashboard home screen, the Reports page and saved reports — a registry of metrics and dimensions compiled into one query contract.

#### AI-Assisted 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 — 38 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.
- [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.

#### Tutorial

- [Tutorial: Build a Custom Feature](https://spreecommerce.org/docs/developer/tutorial/introduction.md): Build a complete Brands feature in Spree — model and API from one generator, a dashboard plugin, storefront rendering, events, and tests.
- [Models & API](https://spreecommerce.org/docs/developer/tutorial/model-and-api.md): Generate the Brand model, migration, Store and Admin API controllers, serializers and routes with a single spree:api_resource command.
- [Dashboard](https://spreecommerce.org/docs/developer/tutorial/dashboard.md): Add Brands management to the dashboard of a create-spree-app project — a list page, navigation, a typed Admin API client and a card on the product page.
- [Storefront](https://spreecommerce.org/docs/developer/tutorial/storefront.md): Render brands on the Next.js storefront in apps/storefront — call the Store API through @spree/sdk and build the product and brand pages.
- [Events](https://spreecommerce.org/docs/developer/tutorial/events.md): Publish lifecycle events for Brands and react to them — subscribers inside your Spree app, outbound webhooks for systems you do not deploy code into.
- [Testing](https://spreecommerce.org/docs/developer/tutorial/testing.md): Test the Brands feature — running the generated backend specs, unit-testing the dashboard logic you wrote, and one Playwright pass through the browser.

#### Admin Dashboard

- [React Dashboard Overview](https://spreecommerce.org/docs/developer/dashboard/overview.md): Learn about the Spree React Dashboard architecture and how to customize it and extend it
- [Concepts](https://spreecommerce.org/docs/developer/dashboard/concepts.md): The mental model — what the dashboard is built on, how the pieces fit together, and what you need to know about each layer before you start customizing.

##### Customization

- [Quickstart](https://spreecommerce.org/docs/developer/dashboard/customization/quickstart.md): Add your first customization to the Spree dashboard in under 5 minutes — no npm publishing, no build configuration, just one file in your dashboard app.
- [Navigation](https://spreecommerce.org/docs/developer/dashboard/customization/navigation.md): Add, modify, and remove items from the dashboard's main sidebar and settings sub-nav.
- [Routes](https://spreecommerce.org/docs/developer/dashboard/customization/routes.md): Mount custom pages under your dashboard's `/$storeId/...` path, or outside a store at the root — onboarding, sign-up and account pages. Supports path params, permission gating, and works alongside the dashboard's built-in routes.
- [Slots](https://spreecommerce.org/docs/developer/dashboard/customization/slots.md): Inject your own widgets into existing dashboard pages without forking them. Slots are named injection points the dashboard exposes on built-in pages.
- [Tables](https://spreecommerce.org/docs/developer/dashboard/customization/tables.md): Add, change, or remove columns on built-in list tables (products, orders, customers, …), or define a table for your own resource.
- [Translations](https://spreecommerce.org/docs/developer/dashboard/customization/translations.md): Add your own i18n strings to the dashboard so labels, validation messages, and notifications respect the admin's chosen locale.
- [Theming](https://spreecommerce.org/docs/developer/dashboard/customization/theming.md): Restyle the dashboard by overriding its design tokens — colours, radius, fonts and the type scale — without forking a single component.
- [Permissions](https://spreecommerce.org/docs/developer/dashboard/customization/permissions.md): How to hide UI behind the current admin's permissions in your customisations — and why hiding is never the same as authorising.
- [Backend integration](https://spreecommerce.org/docs/developer/dashboard/customization/backend.md): Talk to your own (or Spree's) Admin API from the dashboard — typed SDK calls, custom endpoints, prefixed IDs, error handling, and React-Query hooks.

##### Recipes

- [A product attribute, end to end: form, table, filters, sort](https://spreecommerce.org/docs/developer/dashboard/recipes/attribute-end-to-end.md): Take one custom product attribute all the way — editable on the product form, visible as a table column, filterable and sortable in the products list.
- [Add a custom field to the product form](https://spreecommerce.org/docs/developer/dashboard/recipes/custom-form-field.md): Add a field to the built-in product form that hydrates from the API and saves with the form's own Save button — no save logic of your own.
- [Add a page action button](https://spreecommerce.org/docs/developer/dashboard/recipes/page-action-button.md): Add a primary action (e.g., "Send invoice", "Sync to ERP") to a built-in detail page's header — both as a top-right button and as a dropdown item.
- [Add a sidebar widget](https://spreecommerce.org/docs/developer/dashboard/recipes/sidebar-widget.md): Add an info card to a built-in detail page's sidebar — pulling its own data, gated by permissions, with loading and empty states.

##### Plugins

- [Plugin overview](https://spreecommerce.org/docs/developer/dashboard/plugins/overview.md): Package dashboard customizations as a redistributable npm plugin. Read this if you're shipping a feature for *other* people's Spree projects — not your own.
- [Scaffolding](https://spreecommerce.org/docs/developer/dashboard/plugins/scaffolding.md): Generate a new dashboard plugin monorepo with `@spree/cli` in one command. Includes TypeScript, biome, a working example entry-point, and translations.
- [Publishing](https://spreecommerce.org/docs/developer/dashboard/plugins/publishing.md): Get a dashboard plugin onto npm — package metadata, peer dependencies, TypeScript builds, versioning with Changesets.
- [Distributing](https://spreecommerce.org/docs/developer/dashboard/plugins/distributing.md): What consumers do to install your plugin — the wiring on the host side, what to document, and how to keep upgrades painless.

##### 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

##### Reference

- [Public API](https://spreecommerce.org/docs/developer/dashboard/public-api.md): Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.
- [Slots catalog](https://spreecommerce.org/docs/developer/dashboard/slots-catalog.md): Every named slot the dashboard renders today. Each entry lists the host page, the slot name, and the context the slot's components receive.
- [Deploying the dashboard](https://spreecommerce.org/docs/developer/dashboard/deployment.md): Ship the React Dashboard to production — served by the Spree server itself (the default), or as a static build on a CDN.

#### Building a Storefront

##### Store SDK

- [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.

##### Working with the 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 wishlist items with the Spree SDK

##### 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

#### Providers & Integrations

- [Spree Fits Your Architecture](https://spreecommerce.org/docs/developer/providers/overview.md): Spree is the commerce layer in the middle of the systems you already run — ERP, PIM, DAM, WMS, PSP, tax engines, search and identity connect through provider contracts, not forks.
- [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.

##### Connect Your Systems

- [Connect Your ERP](https://spreecommerce.org/docs/developer/providers/erp.md): Keep your ERP as the source of truth for stock. Spree syncs inventory in, answers availability from its own snapshot, and asks your ERP live only at the moments that matter.
- [Connect Your PIM](https://spreecommerce.org/docs/developer/providers/pim.md): Keep product data and pricing in your PIM. Spree syncs content in, renders from its own copy, and can price live from an external source at cart decision moments.
- [Product Media & DAM](https://spreecommerce.org/docs/developer/providers/dam.md): Media hosted in your DAM stays in your DAM — Spree stores the address, not a copy of the bytes, and renders it through the same pipeline as uploaded media.

##### Shipping & WMS

- [Shipping & WMS](https://spreecommerce.org/docs/developer/providers/fulfillment.md): Connect your warehouse, 3PL or carrier stack through fulfillment providers — label purchase, tracking, and delivery confirmation flow through one contract.
- [EasyPost](https://spreecommerce.org/docs/integrations/shipping/easypost.md): Set up EasyPost in Spree for live carrier rates at checkout, label purchase and refunds, customs declarations, and carrier tracking updates by webhook.
- [Build a Custom Delivery Rate Provider](https://spreecommerce.org/docs/developer/how-to/custom-delivery-rate-provider.md): Connect a carrier or rate aggregator to Spree so checkout quotes live delivery rates instead of calculator-based prices.

##### 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.
- [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, and pay marketplace sellers through Stripe Connect.
- [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.

##### Marketplace

- [Seller Payouts](https://spreecommerce.org/docs/developer/providers/payouts.md): Pay marketplace sellers through your own rails — a bank transfer API, a wallet, another PSP's platform product — by implementing the payout provider contract.
- [Stripe Connect for Marketplaces](https://spreecommerce.org/docs/integrations/payments/stripe-connect.md): Pay your sellers through Stripe Connect — hosted Express onboarding, a transfer to each seller as their goods ship, and settlements confirmed by webhook.

##### 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

- [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.
- [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.

##### Identity & SSO

- [Identity & SSO](https://spreecommerce.org/docs/developer/providers/sso.md): Single sign-on with OpenID Connect is built into Spree — connect your existing identity provider for staff and customer authentication without custom code.
- [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.

##### Observability

- [Observability](https://spreecommerce.org/docs/developer/providers/observability.md): Distributed tracing with OpenTelemetry — one gem, standard OTEL_* environment variables, and every checkout becomes a trace from HTTP request to gateway call to webhook delivery.

##### Marketing & 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.
- [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.

##### Emails

- [Emails](https://spreecommerce.org/docs/developer/providers/emails.md): Spree sends transactional email over plain SMTP, configured entirely by environment variable — any provider works, and none of them needs anything installed.
- [Resend](https://spreecommerce.org/docs/integrations/email/resend.md): Send Spree's transactional emails through Resend over SMTP — one hostname, the literal username `resend`, and your API key as the password.
- [Postmark](https://spreecommerce.org/docs/integrations/email/postmark.md): Send Spree's transactional emails through Postmark over SMTP — the Server API Token is both username and password, and transactional mail has its own stream.
- [SendGrid](https://spreecommerce.org/docs/integrations/email/sendgrid.md): Send Spree's transactional emails through Twilio SendGrid over SMTP — the username is always the literal string `apikey`, with your API key as the password.
- [Mailgun](https://spreecommerce.org/docs/integrations/email/mailgun.md): Send Spree's transactional emails through Mailgun over SMTP — per-domain credentials, separate US and EU regions, and a sandbox that only emails people you name.
- [Amazon SES](https://spreecommerce.org/docs/integrations/email/amazon-ses.md): Send Spree's transactional emails through Amazon SES over SMTP — regional endpoints, credentials that are not your IAM keys, and the sandbox to leave before launch.

#### Extending the Backend

- [Quickstart](https://spreecommerce.org/docs/developer/customization/quickstart.md): Recommended ways to customize the Spree backend — configuration, workflow hooks, events, checkout steps, providers, dependencies, and decorators as a last resort.
- [Configuration](https://spreecommerce.org/docs/developer/customization/configuration.md): Every Spree setting, the environment variable that sets it, and what it changes.
- [Services & Workflows](https://spreecommerce.org/docs/developer/customization/workflows.md)
- [Validations](https://spreecommerce.org/docs/developer/customization/validations.md)
- [Customizing Checkout](https://spreecommerce.org/docs/developer/customization/checkout.md): Add your own checkout step or requirement, and reorder or remove the built-in ones.
- [Dependencies](https://spreecommerce.org/docs/developer/customization/dependencies.md)
- [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.
- [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)
- [Permissions](https://spreecommerce.org/docs/developer/customization/permissions.md): The permission catalog, staff roles, and how extensions register their own permissions.
- [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.
- [Email Templates](https://spreecommerce.org/docs/developer/customization/emails.md): Change what Spree's transactional emails say and look like, with Liquid templates written in MJML.
- [Email Template Variables](https://spreecommerce.org/docs/developer/customization/email-variables.md): Every variable the Liquid templates of customer emails receive, email by email.

#### Guides

- [Build a Multi-Vendor Marketplace](https://spreecommerce.org/docs/developer/how-to/build-a-marketplace.md): Learn how to extremely fast launch a marketplace on Spree
- [Build a B2B Store](https://spreecommerce.org/docs/developer/how-to/build-a-b2b-store.md): Launch a wholesale or trade channel on Spree — companies, negotiated pricing, order terms, gated access, purchase orders and freight, all configured rather than built.
- [Sell Digital Products](https://spreecommerce.org/docs/developer/how-to/sell-digital-products.md): Digital goods in Spree — a digital delivery profile, instant fulfillment without a shipping address, and delivering files or entitlements after payment.
- [Build a Custom Digital Asset Provider](https://spreecommerce.org/docs/developer/how-to/custom-digital-asset-provider.md): Resolve a digital product's deliverable from your own systems — a license server, an entitlement API, an external file host — instead of an uploaded file.
- [Build Custom Promotion Rules & Actions](https://spreecommerce.org/docs/developer/how-to/custom-promotion.md): Step-by-step guide to creating custom promotion rules, discount actions, and adjusters for business-specific eligibility logic and charges.
- [Extend Reporting](https://spreecommerce.org/docs/developer/how-to/extend-reporting.md): Register your own metrics and dimensions so merchants can compose them in the Reports builder, saved reports and CSV exports.
- [Customize Document Numbers](https://spreecommerce.org/docs/developer/how-to/custom-document-numbers.md): Change the shape of order, return and other document numbers — from the dashboard for order numbers, or in code for full control.
- [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.
- [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 fulfillments along your own axis (refrigeration, gift wrap, bin size, hazmat, anything you need to physically separate).

##### Multi-Tenant Platform

- [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.

#### 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, secrets and encryption keys, 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.
- [Update Checks and Usage Data](https://spreecommerce.org/docs/developer/deployment/usage-data.md): How Spree tells you a newer release exists, the usage data the same daily check reports, and how to turn either off.

##### 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.

#### Operations

- [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.
- [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.

##### Upgrading

- [Quickstart](https://spreecommerce.org/docs/developer/upgrades/quickstart.md): Learn how to upgrade your Spree application
- [Upgrading to Spree 6.0](https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0.md): Guide to upgrading a Spree 5.6 application to Spree 6.0
- [Upgrading to Spree 5.6](https://spreecommerce.org/docs/v5/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/v5/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/v5/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/v5/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/v5/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/v5/developer/upgrades/5.0-to-5.1.md): This guide covers upgrading a Spree 5.0 application to Spree 5.1.

##### 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): Build a Spree extension gem — models, API endpoints, permissions, workflow hooks and event subscribers — and pair it with a dashboard plugin for the admin UI.

##### 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)