Skip to content

armgit / spree

Public Imported from GitHub
0

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.

7.6 KB
Raw Blame
---
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