Skip to content

Liquid theme reference

The files, objects, filters and tags a Paysum storefront theme can use.

Paysum storefronts are Liquid themes. Paysum renders them on its storefront servers with your store's products and settings. A theme is a folder of plain files: no build step and no package install.

Folder layout

my-theme/
├── config/theme.json      Manifest: name, accent, font, sections, text defaults
├── layout/theme.liquid    The page frame around every page
├── templates/             index, product, page, account
├── sections/              Blocks of the home page and of other pages
├── snippets/              Small reusable parts
└── assets/                CSS, fonts, images

Only files in these six folders belong to the theme. Text files can be .liquid, .css, .json, .js, .svg or .html.

The manifest

config/theme.json describes the theme:

{
  "slug": "prism",
  "name": "Prism",
  "accent": "#ff4fd8",
  "font": "Geist",
  "sections": ["hero", "featured", "products", "how-it-works", "faq"],
  "homeClass": "pr-home",
  "stylesheets": ["theme.css"],
  "preload": ["fonts/Geist.woff2"],
  "defaults": {
    "heroTitle": "Unleash Your Potential",
    "ctaText": "Browse products!",
    "purchaseLabel": "Purchase"
  }
}
KeyMeaning
slugThe theme ID. It must match the folder name.
nameThe name in the theme gallery.
accent, fontDefaults until the merchant sets their own colors and font.
sectionsThe home page sections, in order. Each one needs a file in sections/. Merchants reorder and hide them in the visual builder.
homeClassA CSS class for the home page wrapper, available as page.home_class.
stylesheetsCSS files in assets/ to load on every page.
preloadAssets in assets/ to preload, such as fonts.
defaultsText the theme shows. Merchants can edit each value in the visual builder. Read them through copy.

Templates

Paysum picks a template from the page address:

AddressTemplatepage.view
/indexhome
/products/<slug>productproduct
/products, /features, /faq, /reviewspageproducts, features, faq, reviews
/categories/<slug>pagecategory
/page/<slug>pagecustom-page
/terms, /privacy, /refundpageterms, privacy, refund
/accountaccountaccount
Anything elsepagenot-found

Checkout, the order page and the status page are Paysum pages. Themes do not render them.

layout/theme.liquid wraps every template. Print the template's output with content_for_layout:

{%- if settings.header_enabled -%}{%- section 'header' -%}{%- endif -%}
<main>{{ content_for_layout }}</main>
{%- if settings.footer_enabled -%}{%- section 'footer' -%}{%- endif -%}
{{ platform.attribution }}

A typical templates/index.liquid renders the sections in the merchant's order:

<div class="{{ page.home_class }}">
  {%- for id in page.sections -%}
    {%- section id -%}
  {%- endfor -%}
</div>

Tags

Paysum supports the standard Liquid tags (if, unless, case, for, assign, capture, comment, raw) and these:

TagWhat it does
{% section 'name' %}Renders sections/name.liquid. The name can be a variable.
{% render 'name', key: value %}Renders snippets/name.liquid with the given variables.
{% schema %}…{% endschema %}Documents a section's editor settings. It never renders.

include is not available. Use render.

Global objects

These objects are available in every file.

shop

FieldValue
shop.id, shop.slug, shop.name, shop.descriptionThe store
shop.logo, shop.favicon, shop.bannerImage URLs
shop.currencyThe currency code, for example USD
shop.announcement, shop.announcement_icon, shop.announcement_color, shop.announcement_sizeThe announcement bar
shop.discord_urlThe Discord invite
shop.socialsSocial links
shop.policiesPolicy texts
shop.pages, shop.nav_pages, shop.footer_pagesCustom pages. Each has title, slug, href and show_in_navbar.
shop.categoriesProduct categories
shop.stats.total_sold, shop.stats.average_rating, shop.stats.total_reviewsStore statistics

products

products is the catalog in order. Sold-out products are left out when the merchant turned on Hide sold out. On a category page, products holds that category's products.

featured_products holds the featured products. spotlight_products holds the featured products, or the first product when none are featured, up to six. Use it for carousels.

product

FieldValue
product.id, product.title, product.slugThe product
product.hrefThe product page address. Always link with this.
product.imageThe main image URL, or generated art when there is none
product.price, product.price_formattedThe lowest price, and the same price with currency, for example $49.00
product.from_pricetrue when variants have different prices. Show "From" or "Starting at".
product.sold_outtrue when nothing can be bought
product.stock_countStock left. Only set when stock is limited.
product.category_nameThe category
product.descriptionThe description as HTML
product.excerptThe description as plain text, up to 160 characters
product.is_featuredFeatured by the merchant
product.status.text, product.status.colorThe product's status from the status page, when set
product.variantsVariants. Each has id, name, description, price, price_formatted, sold_out, and stock when limited.
product.hide_variant_stock, product.show_default_variantProduct display options

settings

The merchant's design settings:

FieldValue
settings.accent, settings.accent_secondary, settings.accent_inkBrand colors. accent_ink is a readable text color on the accent.
settings.custom_font, settings.custom_font_href, settings.font_scaleThe font and text size
settings.background_image, settings.background_tint, settings.background_tint_opacity, settings.particlesBackground options
settings.header_enabled, settings.footer_enabledHeader and footer switches
settings.hero_title, settings.hero_subtitle, settings.cta_text, settings.bannerHero content
settings.status_messageThe store status message
settings.currencyThe currency code
settings.hide_sold_out, settings.hide_stock, settings.show_products_sold, settings.show_purchase_statsStorefront switches from Customization

content and copy

  • content holds what merchants edit in the visual builder, for example content.products_title, content.features_title, content.faq_title, the content.features list and the content.faqs list.
  • copy holds the text from your manifest's defaults, with the merchant's edits applied, for example copy.purchaseLabel.

Other objects

ObjectValue
pageData for the current page. Always has page.view and page.title.
theme.slug, theme.name, theme.asset_base, theme.sectionsThe theme
request.pathThe current path
request.previewtrue in a theme preview
platform.attributionPaysum's attribution. Print it in the layout.

The product page

On /products/<slug>, page also has:

FieldValue
page.productThe product
page.galleryAll image URLs
page.selected_variantThe ID of the variant selected first
page.price, page.price_formattedThe price of the selected option
page.stock, page.sold_outStock and availability of the selected option
page.rating, page.review_count, page.reviewsReviews. page.reviews.items lists them, each with rating, title, comment, author, verified and created_at.

Filters

All standard Liquid filters work, such as escape, default, upcase, size, first, newline_to_br and date. Paysum adds or changes these:

FilterWhat it does
moneyFormats a number as a price in the given currency
fixedRounds to a number of decimals
delimitedAdds thousands separators to a whole number
cap_countCaps a count, for example 99+
first_letterThe first letter, in upper case
jsonThe value as JSON text
css_urlThe value as a CSS url("…"), for inline styles
cart_jsonThe product as cart JSON, for data-os-add
plus, minus, timesArithmetic. Whole numbers stay whole, so results work as loop bounds and indexes.
divided_by, moduloDivision. Whole numbers round down. Dividing by zero is an error.
{{ 49 | money: shop.currency }}          → $49.00
{{ 4.666 | fixed: 1 }}                   → 4.7
{{ 12345 | delimited }}                  → 12,345
{{ 150 | cap_count: 99 }}                → 99+
{{ shop.name | first_letter }}           → N
{{ shop.banner | css_url }}              → url("https://…")
{{ product | cart_json | escape }}       → {"id":"…","name":"…","price":49,…}
{{ 7 | divided_by: 2 }}                  → 3

Output is escaped

Output is HTML-escaped by default. To print trusted HTML, such as product.description, add | safe. Never mark buyer or merchant text as safe unless Paysum already gives it to you as HTML.

Let merchants edit text in place

Add data-editable to an element to make its text editable in the visual builder:

ValueEdits
data-editable="hero_title"A settings field such as hero_title, hero_subtitle or cta_text
data-editable="copy:purchaseLabel"A copy value from your manifest
data-editable="list:faqs:<id>:question"A field of one item in a content list

Add data-section="<id>" to each section's root element so the builder can select, hide and reorder it.

Next steps