Theme Customizations

Theme customizations are the configurable content blocks that drive the storefront home page and footer — image carousels, category carousels, product carousels, static-content slots, the footer-links columns, and the "services" / "USP" strip. Each block is scoped to a themeCode + channelId pair, with locale-specific options JSON inside its translations.

Endpoints

Method	Path	Purpose
GET	/api/shop/theme-customizations	Paginated list — supports ?type= filter
GET	/api/shop/theme-customizations/{id}	Single customization by ID

Use the example switcher above to flip between the unfiltered list, the ?type=footer_links filter, and a single fetch.

Request Headers

Header	Required	Description
Accept	Yes	application/json
X-STOREFRONT-KEY	Yes	Storefront API key (pk_storefront_…)
X-Locale	No	Override request locale — affects which row populates translation. Default: channel locale.
X-Channel	No	Override channel scope

Query Parameters (collection only)

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
per_page	integer	10	Items per page. Max 100 for this endpoint.
type	string	—	Exact-match filter on the type field (see Supported types)

Pagination headers (X-Total-Count, X-Page, X-Per-Page, X-Total-Pages) are emitted on the collection. See Pagination.

Supported types

The type filter accepts any of these exact strings:

Type	Purpose
image_carousel	Hero / banner image carousel on the home page
category_carousel	Horizontally-scrolling list of categories
product_carousel	Horizontally-scrolling list of products
static_content	Free-form HTML / Markdown block
footer_links	Footer link columns (privacy, terms, about, customer service, …)
services_content	"Services" / USP strip (free shipping, 24×7 support, refund policy, …)

An unsupported value is accepted by the filter and returns an empty array rather than an error — the filter is not validated against the type list.

Customization 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	Customization primary key
themeCode	string	Theme this block belongs to (e.g. default)
channelId	integer	Channel that owns this block — pair with themeCode
type	string	One of the supported types
name	string	Admin-facing name
sortOrder	integer	Display order within the home page / footer
status	boolean (0/1)	Whether the block is published — only published rows are returned
createdAt, updatedAt	string (ISO-8601)	Timestamps
translation	object | null	Inline translation for the request locale: { id, themeCustomizationId, locale, options }
translations	array of objects	All locale translations as inline objects (not IRI strings)

Both translation and translations[] are inlined — there are no IRIs to follow on this resource. The options field inside each translation is a JSON string, not a parsed object — you have to JSON.parse(translation.options) on the client.

Content is locale-specific, so pass X-Locale. The translation field returns the block's content for the requested locale, selected by the X-Locale request header (e.g. X-Locale: ar); omit it and you get the store default locale. The translations[] array always carries every locale, so you can also read them all and pick client-side.

Shape of the options payload (per type)

The options JSON string varies by type. Common shapes:

type	Parsed options shape
image_carousel	{ "images": [{ "image": "storage/theme/.../*.webp", "link": "...", "title": "..." }, …] }
product_carousel	{ "title": "...", "filters": { "new": 1, "featured": 1, "limit": 10, "sort": "asc" } } — filters is forwarded as query params to the Products listing
category_carousel	{ "title": "...", "filters": { "parent_id": "1", "limit": "10", "sort": "asc" } } — parent_id selects the parent whose children are shown (same value you'd pass to treeCategories(parentId:))
static_content	{ "html": "<div>…</div>", "css": ".foo{…}" }
footer_links	{ "column_1": [{ "url": "...", "title": "...", "sort_order": "3" }, …], "column_2": […], … }
services_content	{ "services": [{ "service_icon": "storage/…", "title": "...", "description": "..." }, …] }

The client must parse that JSON string before using it — the value is stored and returned verbatim as text.

Images inside static_content need care: the stored html is authored for the storefront web theme, where <img> tags carry the real source in a data-src attribute (lazy-loading) and a placeholder in src. If you render this HTML in your own frontend, read data-src, not src, or images won't load.

Use Cases

• Render the storefront home page in a single round trip: fetch the unfiltered collection, group by type, sort by sortOrder per group.
• Render the footer in a focused request: ?type=footer_links returns just one row whose options carries the column data.
• Build an admin preview of every locale: read all translations[] entries side-by-side.
• Auto-detect new home-page blocks added by store admins by polling the collection — anything with status=1 will appear.

Best Practices

• Parse options before use — it is a JSON string, not an object, on every translation.
• Branch on type — four block types render straight from options, while product_carousel and category_carousel only carry filters you must then send to the product or category endpoints.
• Send X-Locale — translation follows the request locale, and the default locale is what you get otherwise.
• Read data-src, not src, inside static_content HTML — the markup is authored for lazy loading, so src holds a placeholder.

Related Resources

• Channels — channelId on each customization points at one of these
• Categories — referenced by category_carousel and product_carousel filters
• Introduction → IRIs & HATEOAS — how to dereference the path references in these payloads