Liquid objects
Every key in the v1 render context with its properties, types, and when it is present.
On this page
This is the complete contract of the data a theme sees (ThemeContextV1); nothing else ever reaches Liquid: no orders, no customers, no secrets. The contract is additive-only: fields are added, never removed or retyped. Which page carries which key is in Templates.
Money#
Every price is a { amount_minor, currency } object without decimals: the exponent comes from the platform table (SYP 0, USD and EUR 2). Never compute in Liquid; display with money.
store#
| Property | Type | Meaning |
|---|---|---|
id, name, slug |
string | store identity |
description |
string or null |
public description |
url |
string | absolute storefront path (/stores/{slug}) |
logo_url |
string or null |
the logo |
banner_urls |
string array | banner images |
social_accounts |
array of { platform_name, account_handle, url } |
social accounts |
whatsapp_number |
string or null |
a normalized WhatsApp number; use wa_href |
address |
string or null |
the address |
primary_color |
string or null |
the merchant's primary color #rrggbb |
currency |
{ code, allowed[] } |
the display currency and the allowed ones (USD, EUR, SYP) |
payment_method_ids |
string array | ids of the payment methods actually enabled at checkout (such as cod); never claim a method absent here |
theme_settings |
object | the validated theme settings for your schema; also available directly as theme_settings |
request#
| Property | Type | Meaning |
|---|---|---|
path |
string | the current path |
page_type |
home, product, category, cart, search |
the page type |
locale |
ar or en |
the visitor's language |
direction |
rtl or ltr |
the direction |
search |
string or null |
the normalized search query on list pages |
categories and category#
categories is every public category in admin order; category is the one being viewed on its page.
| Property | Type | Meaning |
|---|---|---|
id, name, slug |
string | identity |
url |
string | the category page path |
parent_id |
string or null |
the parent category |
product_count |
number | products in the subtree |
image_url |
string or null |
the resolved tile image (the merchant's image or the 30-day best seller's cover); null is a normal, permanent state and the first-letter fallback is mandatory |
image_color |
string or null |
dominant color #rrggbb for the placeholder |
image_alt |
string or null |
alt text, falling back to the category name |
image_focal_style |
string or null |
a ready style value such as object-position: 50% 30% |
products, product, related_products#
| Property | Type | Meaning |
|---|---|---|
id, name |
string | identity |
brand, description |
string or null |
brand and description (the description is sanitized HTML; output it with richtext or strip_html) |
url |
string | the product page path |
price |
money | the selling price |
compare_at_price |
money or null |
the pre-promotion price when a promotion is active |
savings |
money or null |
platform-computed compare_at_price − price; present exactly when compare_at_price is |
available |
boolean | availability |
available_quantity |
number or null |
present only when remaining stock is ≤ 5 (a scarcity signal without inventory disclosure) |
featured |
boolean | a featured product |
image_url |
string or null |
the main image |
image_color |
string or null |
the main image's dominant color |
images |
string array | the gallery (product page only; empty elsewhere) |
categories |
array of { id, name, url } |
its categories |
variants |
array | see Variants |
rating |
{ average_x10, count } or null |
the average ×10 as an integer (43 = 4.3) from published reviews only |
sold_count |
number or null |
units sold across real non-cancelled orders; null below the credibility threshold |
Variants#
| Property | Type | Meaning |
|---|---|---|
id |
string | |
attributes |
object or null |
variant attributes ({ "size": "50 ml" }) |
price, compare_at_price, savings |
money | as on the product |
available, available_quantity |
as on the product | |
image_url |
string or null |
the variant image |
pagination#
{ page, perPage, total, totalPages, hasNextPage, hasPrevPage } on list pages. See Pagination.
cart#
| Property | Type | Meaning |
|---|---|---|
lines |
array | see below |
item_count |
number | the sum of quantities |
subtotal |
money | the total before shipping |
A cart line: id (the handle for the quantity and remove controls), product_id, variant_id, name, variant_label (string or null, such as "50 ml"), quantity, unit_price, line_total, image_url.
product_reviews#
Present on the product page when published reviews exist or a page/sort query was made:
| Property | Type |
|---|---|
review_count, average_x10, recommend_percent |
number |
histogram |
[n1, n2, n3, n4, n5] review counts per star |
items |
array of reviews: id, author_name, rating, recommend, body, verified, helpful_count, created_at (YYYY-MM-DD) |
page, total_pages |
number |
sort |
newest, highest, lowest, helpful |
verified is platform-decided for order-verified reviews; no phone and no order id ever reach the theme.
page_sections and section#
page_sections is the array of resolved, visible instances in the merchant's order; inside snippets/section-body.liquid the current instance is available as section:
| Property | Type | Meaning |
|---|---|---|
id, type |
string | the instance id and its type |
settings |
object | the validated instance settings |
blocks |
array of { id, type, settings, products? } |
the blocks in order |
band |
boolean (optional) | true when the definition declares it |
products |
product array (optional) | products resolved from the instance's sources |
products_total |
money (optional) | the sum of the available ones' prices |
See Sections.
theme_settings and editor_chrome#
theme_settingsis a shortcut forstore.theme_settingsthe platform adds for every theme.editor_chromeistrueonly inside the editor canvas; never base any visitor-facing logic on it.