Overview
Every render receives three layers of data:- Globals, available on every page.
- Page data, specific to the template being rendered.
- Scope variables, injected by the layout, component, and snippet mechanisms.
Scope variables
Globals
Available on every page.
Most pages also get:
shop
The fields themes actually use:shop also carries the merchant’s own third-party IDs (gtag_id, gtm_id, meta_pixel_id, crisp_website_id, tawkto_id) so themes can drop in the corresponding script tags. These belong to the merchant, not to SellAuth.
shop.settings is a filtered view intended for the storefront, not the shop’s full settings. Do not assume an arbitrary setting is present.shop.legal_pages to list every published legal page after the merchant’s own links, gated on the footer’s legal_links_auto property (on when absent):
components/footer.njk
path you already link by hand, so a merchant’s manual links are not repeated.
Render social links from shop.socials rather than naming each platform, so platforms added later show up without a theme update:
components/footer.njk
Meta tags
The official themes build the<head> tags in snippets/meta-tags.njk, included from the layout with {% render_snippet "meta-tags.njk" %}. A theme that writes its own should follow the same rules, so the merchant’s SEO settings apply:
- The title is
page_seo.titlewhen set, otherwise the page’s own title. Addshop.settings.seo.title_separatorandshop.nameafter it, unlessshop.settings.seo.append_shop_nameisfalseor the title already contains the shop name. The home page usesshop.meta_titleon its own. og:titleandtwitter:titletake the title without the shop name, since link previews show the shop name separately.- Prefer
page_seo.descriptionandpage_seo.image_urlover the page’s defaults, and output<meta name="robots" content="noindex">whenpage_seo.noindexistrue. - Search engine verification tags and the merchant’s own head and footer code are inserted by SellAuth after your theme renders, on every theme. Do not output them yourself.
Page data
Everything below is in addition to the globals.Storefront
Notes:
filterson the products page holds the active filter state:keyword,in_stock, andprice(currency,from,to).liveStatson the product page only contains the counters the merchant enabled, so check before rendering.products_soldon a product is the lifetime number of units sold, and every entry in itsvariantshassales, the same count for that variant. Refunded and charged back orders are not counted.- The policy pages give you raw HTML. Output with
| safe. legal_pageon thelegal-pagetemplate is{ type, slug, path, url, title, default_title, metadata, meta_title, meta_description, content }.typeis one ofterms,privacy_policy,refund_policy,shipping_policy,cookie_policy,impressum,withdrawal;titleis the merchant’s own title ornull, so fall back todefault_title;meta_titleis the merchant’s meta title, or their title, ornull;meta_descriptionisnullunless set, so fall back to your own text;contentis raw HTML, output with| safe. A theme copy without thelegal-pagetemplate still renders theterms,privacy-policyandrefund-policytemplates, which receive the same object withoutcontent, since their content arrives in the older variable.prev_postandnext_poston the blog post page are the neighbouring posts in publish order (prev_postis older,next_postis newer) and arenullat the ends. They carry the same fields as an entry inrelated_posts.metadatais free-form data the merchant fills in the dashboard, on products, groups, categories, blog posts and legal pages. Valid JSON arrives decoded, soblogPost.metadata.heroorlegal_page.metadata.footer_iconworks; anything else arrives as the raw string. It isnullwhen the merchant left it empty, so guard before reading a key.- Every feedback in
feedbacksandlatest_feedbackshas ausername: the buyer’s username, ornullwhen the review stays anonymous. It isnullwhen the buyer set no username or chose to hide it on reviews, and on automatic reviews. Show nothing extra fornull. The official themes display it with an@in front (the value itself has none). Output the username andmessageescaped like any other buyer text, never with| safeorrenderString. custom_page.accessispublic,customerorreseller: who the merchant lets open the page. Apublicpage is served at/<path>, the other two at/customer/<path>, andcustom_page.urlis that path already assembled.requires_loginandcustomer_shellare bothtruefor a gated page, so{% if custom_page.customer_shell %}is the switch for rendering the page inside your customer account layout. The gate itself is enforced on the server: a visitor without a session never reaches the template.featured_productson the blog post page holds the products the merchant picked for that post, in their chosen order. Each entry has the same shape as a product initems, so it renders with your product card snippet. Empty when nothing was picked.
Customer area
customer_nav_pages is on every page and lists the merchant’s own gated custom pages for the account sidebar, in theme-settings order: key, name, label (the sidebar label, falling back to the name), path and access. It only holds pages the merchant ticked for the sidebar, and a reseller-only page is left out for a visitor who is not an approved reseller, so it can be rendered as-is. It is an empty array when there are none. Mark the active entry by comparing templateName with the entry’s key.
shop_customer carries username, anonymous_feedback and username_locked on every customer page, for a username form. Save it with POST /v1/customer-dashboard/profile, sending username (or null to remove it) and anonymous_feedback. When username_locked is true the shop has stopped this customer changing their name, so offer only the anonymous toggle. The endpoint is the customer’s profile, so more fields may join it later.
Paginators
Any variable ending in_paginator is a paginator object with these fields:
The official themes render all of this with a shared snippet:
Legacy variables
These still work but should not be used in new themes:sortedItems contains every public product and group, and it is loaded on every page. It exists because older themes depend on it. Reach for the page’s own data first.