Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Stores
description: Understand Spree Stores — the top-level tenant boundary that scopes products, orders, channels, markets, and branding, with the Admin API for store config.
---
## Overview
The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, categories — belongs to exactly one store. A store owns its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its [product catalog](/developer/core-concepts/products).
```mermaid
erDiagram
Store ||--o{ Channel : "sells through"
Store ||--o{ Market : "trades in"
Store ||--o{ Product : "catalogs"
Store ||--o{ Order : "records"
Store ||--o{ PaymentMethod : "accepts"
Store ||--o{ StockLocation : "ships from"
Store ||--o{ Policy : "publishes"
Store ||--o{ Seller : "hosts"
Store {
string name
string code
string url
string default_currency
string default_locale
boolean default
}
```
## Store Attributes
| Attribute | Description |
|-----------|-------------|
| `name` | Store name, displayed in the browser title and throughout the site |
| `code` | Unique identifier for the store |
| `url` | Primary URL of the store |
| `meta_description` | SEO description |
| `meta_keywords` | SEO keywords |
| `seo_title` | Custom SEO title |
| `customer_support_email` | Email for customer support inquiries |
| `mail_from_address` | Sender address for transactional emails |
| `logo_url` | URL to the store's logo |
| `facebook`, `twitter`, `instagram` | Social media links |
| `storefront_access` | Store-wide default for anonymous [storefront access gating](/developer/core-concepts/channels#storefront-access-gating) (`public`, `prices_hidden`, `login_required`). Each channel can override it |
| `guest_checkout` | Store-wide default for whether orders can be placed without an account. Each channel can override it |
## 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:
<CodeGroup>
```typescript Admin SDK
const store = await adminClient.store.get()
// {
// name: "My Store",
// url: "https://mystore.com",
// logo_url: "https://cdn.mystore.com/logo.png",
// mailer_logo_url: "https://cdn.mystore.com/mailer-logo.png",
// customer_support_email: "[email protected]",
// ...
// }
```
```bash cURL
curl 'https://api.mystore.com/api/v3/admin/store' \
-H 'X-Spree-API-Key: sk_xxx'
```
</CodeGroup>
This is an admin endpoint, so it requires a secret API key (`sk_xxx`) or a Bearer JWT — a publishable key cannot reach it.
### Storefront SEO
A storefront reads the store's public name and default SEO metadata — `seo_title` and `meta_description` — from the Store API, in the shopper's language. Use them for the home page title and description. A field with no translation for the requested locale returns the default-language value.
<Tabs>
<Tab title="Store SDK">
```typescript
const store = await client.store.get({ locale: 'de' })
// { id: "store_k5nR8xLq", name: "My Store", seo_title: "Frischer Kaffee", meta_description: "…" }
```
</Tab>
<Tab title="cURL">
```bash
curl 'https://api.mystore.com/api/v3/store/store' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Locale: de'
```
</Tab>
</Tabs>
Merchants edit the default-language values on **Settings → Store** in the dashboard and translate them with **Manage translations** on the same page. See [Translations](/developer/core-concepts/translations).
## Channels vs. Markets
Two different ways to split a store, often confused:
- **[Sales Channels](/developer/core-concepts/channels)** segment **selling surfaces** — Online Store, POS, Wholesale, marketplace integrations. They control product visibility, order attribution, and per-channel routing rules.
- **[Markets](/developer/core-concepts/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](/developer/core-concepts/channels#storefront-access-gating).
## Store Resources
Each store owns its own resources. Products, orders, channels, markets, and categories in one store are independent from another.
| Resource | Relationship |
|----------|-------------|
| [**Channels**](/developer/core-concepts/channels) | A store has many channels (Online Store, POS, Wholesale, …). One is the default. |
| [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |
| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store and one channel |
| [**Products**](/developer/core-concepts/products) | A product belongs to one store. Its visibility across channels is controlled by [publications](/developer/core-concepts/channels#publishing-products-on-channels). |
| [**Categories**](/developer/core-concepts/products#categories) | A category belongs to one store |
| [**Payment Methods**](/developer/core-concepts/payments) | A payment method belongs to one store |
| [**Shipping Methods**](/developer/core-concepts/fulfillments) | A shipping method belongs to one store |
| [**Promotions**](/developer/core-concepts/promotions) | A promotion belongs to one store |
## 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.
- **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](/developer/multi-tenant/quickstart) extension, which is a separate gem from core Spree.
## Related Documentation
- [Channels](/developer/core-concepts/channels) — Selling surfaces (Online, POS, Wholesale, …)
- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store
- [Products](/developer/core-concepts/products) — Product catalog
- [Orders](/developer/core-concepts/orders) — Order management and checkout
- [Wholesale Portal](/developer/storefront/nextjs/wholesale) — A gated B2B storefront surface built on channel access gating
- [Admin SDK](/developer/sdk/admin/quickstart) — TypeScript client for the Admin API used to read and update store configuration