Channels

A channel represents an individual storefront — its hostname, theme, allowed locales and currencies, default locale, base currency, and SEO defaults. Most stores have one channel; multi-channel installations expose every channel through the same endpoints.

Endpoints

Method	Path	Purpose
GET	/api/shop/channels	Paginated list of channels
GET	/api/shop/channels/{id}	Single channel by ID

Use the example switcher above the curl block to flip between the two.

Request Headers

Header	Required	Description
Accept	Yes	application/json
X-STOREFRONT-KEY	Yes	Storefront API key (pk_storefront_…)

Query Parameters (collection only)

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
per_page	integer	10	Items per page. Max 50.

The collection response carries pagination headers (X-Total-Count, X-Page, X-Per-Page, X-Total-Pages). See Pagination.

Channel Object Fields

Both endpoints return the same shape — the collection wraps an array of these objects, the single endpoint returns one.

Field	Type	Description
id	integer	Channel primary key
code	string	Unique channel code — pass it as the X-Channel header to scope a request
hostname	string	Public hostname for this channel
theme	string	Theme assigned to the channel
timezone	string | null	Timezone code (e.g. America/New_York)
homeSeo	object	SEO metadata: { meta_title, meta_keywords, meta_description }
isMaintenanceOn	boolean (0/1)	Maintenance mode flag
allowedIps	string | null	Comma-separated IP allowlist (used when maintenance mode is on)
logo, favicon	string | null	Storage paths
logoUrl, faviconUrl	string | null	Fully-qualified asset URLs
createdAt, updatedAt	string (ISO-8601) | null	Timestamps
locales	array of IRI strings	Locales enabled for this channel — GET <iri> to dereference
currencies	array of IRI strings	Currencies enabled for this channel
defaultLocale	string (IRI) | null	Default locale for the channel
baseCurrency	string (IRI) | null	Base currency for prices
translation	string (IRI) | null	Channel translation for the request locale (single IRI, not inline)
translations	array of IRI strings	All locale translations

Unlike attributes and categories, a channel's translation is a path reference, not an inline object — fetch it to read name, description, and maintenanceModeText. The channel object itself therefore carries no human-readable name. See IRIs & HATEOAS for how to dereference these paths.

Use Cases

• Discover the channel code to send as X-Channel on subsequent requests.
• Read locales / currencies / defaultLocale / baseCurrency IRIs to render channel-aware switchers.
• Read homeSeo for the home-page <title> and meta tags before any product is loaded.
• Check isMaintenanceOn before showing the storefront; if 1, fetch the translation IRI for the localized maintenance text.

Best Practices

• Read code first — it is the value every other endpoint expects in X-Channel; the numeric id is not accepted there.
• Fetch the translation path for display text — the channel object itself carries no name or description.
• Do not assume timestamps are set — seeded channels return null for createdAt and updatedAt.
• Check isMaintenanceOn before rendering the storefront — when it is 1, the localised maintenance message lives in the channel translation.

Related Resources

• Channel Translations — a channel's localised name and content
• Introduction → IRIs & HATEOAS — how to dereference the path references in these payloads