Skip to main content

Overview

Every render receives three layers of data:
  1. Globals, available on every page.
  2. Page data, specific to the template being rendered.
  3. Scope variables, injected by the layout, component, and snippet mechanisms.
Page data wins if a name appears in more than one layer.
While developing, {{ someVariable | dump }} prints the JSON representation of anything, which is the fastest way to see the real shape of a value.

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.
The official footers use 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
Skip pages whose 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.title when set, otherwise the page’s own title. Add shop.settings.seo.title_separator and shop.name after it, unless shop.settings.seo.append_shop_name is false or the title already contains the shop name. The home page uses shop.meta_title on its own.
  • og:title and twitter:title take the title without the shop name, since link previews show the shop name separately.
  • Prefer page_seo.description and page_seo.image_url over the page’s defaults, and output <meta name="robots" content="noindex"> when page_seo.noindex is true.
  • 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:
  • filters on the products page holds the active filter state: keyword, in_stock, and price (currency, from, to).
  • liveStats on the product page only contains the counters the merchant enabled, so check before rendering.
  • products_sold on a product is the lifetime number of units sold, and every entry in its variants has sales, 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_page on the legal-page template is { type, slug, path, url, title, default_title, metadata, meta_title, meta_description, content }. type is one of terms, privacy_policy, refund_policy, shipping_policy, cookie_policy, impressum, withdrawal; title is the merchant’s own title or null, so fall back to default_title; meta_title is the merchant’s meta title, or their title, or null; meta_description is null unless set, so fall back to your own text; content is raw HTML, output with | safe. A theme copy without the legal-page template still renders the terms, privacy-policy and refund-policy templates, which receive the same object without content, since their content arrives in the older variable.
  • prev_post and next_post on the blog post page are the neighbouring posts in publish order (prev_post is older, next_post is newer) and are null at the ends. They carry the same fields as an entry in related_posts.
  • metadata is free-form data the merchant fills in the dashboard, on products, groups, categories, blog posts and legal pages. Valid JSON arrives decoded, so blogPost.metadata.hero or legal_page.metadata.footer_icon works; anything else arrives as the raw string. It is null when the merchant left it empty, so guard before reading a key.
  • Every feedback in feedbacks and latest_feedbacks has a username: the buyer’s username, or null when the review stays anonymous. It is null when the buyer set no username or chose to hide it on reviews, and on automatic reviews. Show nothing extra for null. The official themes display it with an @ in front (the value itself has none). Output the username and message escaped like any other buyer text, never with | safe or renderString.
  • custom_page.access is public, customer or reseller: who the merchant lets open the page. A public page is served at /<path>, the other two at /customer/<path>, and custom_page.url is that path already assembled. requires_login and customer_shell are both true for 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_products on 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 in items, 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.
The reseller page includes credential-shaped values so the built-in themes can show a reseller their own integration details. Render them only inside the reseller’s own dashboard view, never in shared markup, and never log them.

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.