Skip to main content

​
Overview

The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its channels (online, POS, wholesale, …), its markets (region/currency/locale), and its product catalog.

​
Store Attributes

​
Fetching Store Information

Store configuration is exposed through the Admin API. Use the store endpoint to read the current store’s settings — name, URL, branding, and email addresses:
This is an admin endpoint, so it requires a secret API key (sk_xxx) or a Bearer JWT — a publishable key cannot reach it.

​
Channels vs. Markets

Two different ways to split a store, often confused:
  • Sales Channels segment selling surfaces — Online Store, POS, Wholesale, marketplace integrations. They control product visibility, order attribution, and per-channel routing rules.
  • Markets segment geography and currency — North America (USD/en), Europe (EUR/de), UK (GBP/en). They control which currency, locale, and tax rules apply to a given customer.
A single Online Store channel can serve multiple markets (one storefront → many regions). Conversely, POS and Online channels can share the same market (same currency/locale, different selling surfaces).

​
Storefront access defaults

The store sets the fallback for storefront access gating — whether anonymous visitors may browse, see prices, or must sign in first — via storefront_access (public, prices_hidden, login_required) and the companion guest_checkout control. Each channel inherits these unless it sets its own value, so you can gate a whole store or just one channel (e.g. a login_required wholesale channel on an otherwise public store). The full behavior of each mode and how the Store API enforces it lives in Channels → Storefront Access Gating.

​
Store Resources

Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.

​
Running Multiple Storefronts

If you need one Spree backend to serve multiple distinct merchant brands — different domains, different catalogs — there are two patterns:
  • Multiple channels under one store (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree 5.5+.
  • Multiple isolated stores (tenants) in one app — full data isolation, only recommended if you’re building a SaaS platform or a multi-tenant application. Each store can have different staff members, payment methods, shipping methods, and branding. This is supported by the Spree Multi Tenant extension, which is a separate gem from core Spree.
  • Channels — Selling surfaces (Online, POS, Wholesale, …)
  • Markets — Multi-region commerce within a store
  • Products — Product catalog
  • Orders — Order management and checkout
  • Wholesale Portal — A gated B2B storefront surface built on channel access gating
  • Admin SDK — TypeScript client for the Admin API used to read and update store configuration