Shopify Liquid language and commerce data: Shopify guide for coding agents

Use this guide when reading Shopify objects, controlling Liquid flow, formatting commerce values, or building forms. Search this guide by the exact object, tag, or filter name. Check Shopify's linked reference before using an API you cannot confirm.

Keep output, logic, and whitespace distinct

{{ value }} outputs a value.
{% tag %} performs control flow, assignment, rendering, pagination, forms, or another operation.
{{- value -}} and {%- tag -%} trim surrounding whitespace. Use trimming deliberately; aggressive trimming can join text or attributes.
Liquid uses and, or, contains, and comparison operators. Parentheses are not available for grouping conditions; split complex logic into nested conditions or assigned booleans.
blank, empty, nil, true, and false are special values. Prefer explicit checks when zero, an empty string, and absence mean different things.

Use the right tags

Common control and variable tags include assign, capture, case, if, unless, for, break, continue, cycle, increment, decrement, echo, liquid, and raw.

Use render for snippets. Pass every dependency explicitly and avoid relying on outer local variables:

{% render 'price', product: product, show_compare_at: true %}

Variables created outside a snippet are not available inside a snippet rendered with render. Do not shadow predefined Shopify objects such as product, cart, section, or settings with local variable names.

Use paginate for pageable collections rather than slicing large arrays by hand. Use Shopify's form tag for supported forms such as product, cart, customer, create_customer, recover_customer_password, contact, localization, and currency. The form tag supplies Shopify-required endpoints and hidden fields.

Use section, sections, stylesheet, javascript, and style only in the file types and contexts Shopify documents. Never construct a Liquid tag or filter name dynamically.

Use content_for 'blocks' to render a theme block collection. Use content_for 'block' with a stable type and id only for a static block whose LiquidDoc contract documents that call. Use the layout tag only when a template needs to select or disable a theme layout.

Start from the page object

Important global objects include shop, request, routes, settings, localization, cart, customer, markets, content_for_header, content_for_layout, template, and canonical_url.

Template-specific objects include product, collection, search, page, blog, article, order, gift_card, and metaobject. Check whether an object exists in the current template before reading it. Do not assume product or collection is global.

Use routes instead of hard-coded storefront paths. Examples include routes.cart_url, routes.cart_add_url, routes.search_url, routes.root_url, and account routes. This keeps links compatible with locale-aware and market-aware storefronts.

Use Shopify filters for Shopify values

Prices: use money, money_with_currency, or another documented money filter. Never divide cents or concatenate currency symbols yourself.
Images: use image_url to request dimensions and image_tag to emit a responsive image. Provide width, height, and alt text. Do not use deprecated img_url.
Assets: use asset_url followed by stylesheet_tag, script_tag, or the appropriate HTML element.
Storefront files: use file_url, file_img_url only where the referenced resource type requires it, and prefer current image APIs.
Arrays: use where, map, compact, uniq, sort, reverse, first, last, join, and size instead of repeated loop work.
Strings and URLs: use escape, escape_once, url_encode, url_escape, handleize, strip_html, and truncate for their documented purpose.
Translations: use t with a locale key rather than hard-coded customer-facing copy.
Metafields: inspect the metafield type and use metafield_text or metafield_tag when suitable. Read .value only when the type's reference says so.

Filter lookup index

Use these names to locate the correct family, then confirm the signature and supported input type in Shopify's filter reference.

Arrays: compact, concat, find, find_index, first, has, join, last, map, reject, reverse, size, sort, sort_natural, sum, uniq, where.
Cart: item_count_for_variant, line_items_for.
Collections and tags: highlight_active_tag, link_to_add_tag, link_to_remove_tag, link_to_tag, link_to_type, link_to_vendor, sort_by, url_for_type, url_for_vendor, within.
Color: brightness_difference, color_brightness, color_contrast, color_darken, color_desaturate, color_difference, color_extract, color_lighten, color_mix, color_modify, color_saturate, color_to_hex, color_to_hsl, color_to_oklch, color_to_rgb, hex_to_rgba.
Customer: avatar, customer_login_link, customer_logout_link, customer_register_link, login_button.
Defaults and pagination: default, default_errors, default_pagination.
Fonts: font_face, font_modify, font_url.
Formatting: date, json, structured_data, unit_price_with_measurement, weight_with_unit.
Hosted files: asset_img_url, asset_url, file_img_url, file_url, global_asset_url, shopify_asset_url. Some image-specific legacy filters remain documented for compatibility; prefer current image APIs for new work.
HTML: class_list, highlight, inline_asset_content, link_to, placeholder_svg_tag, preload_tag, script_tag, stylesheet_tag, time_tag.
Localization: currency_selector, format_address, t (translate).
Math: abs, at_least, at_most, ceil, divided_by, floor, minus, modulo, plus, round, times.
Media: article_img_url, collection_img_url, external_video_tag, external_video_url, image_tag, image_url, img_tag, img_url, media_tag, model_viewer_tag, product_img_url, video_tag. Treat img_url and related legacy URL filters as compatibility surfaces, not defaults.
Metafields: metafield_tag, metafield_text.
Money: money, money_with_currency, money_without_currency, money_without_trailing_zeros.
Payments: payment_button, payment_terms, payment_type_img_url, payment_type_svg_tag.
Strings and encoding: append, base64_decode, base64_encode, base64_url_safe_decode, base64_url_safe_encode, camelize, capitalize, downcase, escape, escape_once, handleize, hmac_sha1, hmac_sha256, lstrip, md5, newline_to_br, pluralize, prepend, remove, remove_first, remove_last, replace, replace_first, replace_last, rstrip, sha1, sha256, slice, split, strip, strip_html, strip_newlines, truncate, truncatewords, upcase, url_decode, url_encode, url_escape, url_param_escape.

Filter chains evaluate left to right. Each output must be a valid input for the next filter. Assign intermediate values when the intended grouping is not obvious.

Object lookup index

Common global objects include additional_checkout_buttons, all_country_option_tags, all_products, articles, blogs, canonical_url, cart, closest, collections, content_for_additional_checkout_buttons, content_for_header, content_for_index, content_for_layout, country_option_tags, current_page, customer, handle, images, linklists, localization, metaobjects, page_description, page_image, page_title, pages, powered_by_link, request, routes, scripts, settings, shop, template, and theme.

Template objects are narrower: article and blog on article pages; blog and current_tags on blog pages; collection and current_tags on collection pages; product on product pages; page on page templates; search on search templates; cart on cart pages; customer and order on customer pages; gift_card and recipient on gift-card pages; metaobject on metaobject templates; and robots on robots.txt.liquid.

Tag lookup index

Control and variable tags include assign, break, capture, case, comment, continue, cycle, decrement, echo, for, if, increment, liquid, raw, tablerow, and unless. Theme and rendering tags include content_for, doc, form, javascript, layout, paginate, render, section, sections, style, and stylesheet.

Use the form tag with a documented type: activate_customer_password, cart, contact, create_customer, currency, customer, customer_address, customer_login, guest_login, localization, new_comment, product, recover_customer_password, reset_customer_password, or storefront_password.

Liquid for loops render at most 50 iterations on one page. Use paginate for supported arrays such as products, articles, comments, search results, customer orders, addresses, pages, collections, and product variants. Shopify pagination has a platform depth limit, so filter large result sets before paginating.

Build product and cart behavior on real variants

Product forms must submit a real variant ID as name="id". A product can have unavailable or sold-out variants, and product.selected_or_first_available_variant may change with the selected URL variant. Do not use the product ID where Shopify expects a variant ID.

Use quantity_rule, quantity_price_breaks, selling-plan data, and line-item properties when the merchant's catalog needs them. Do not invent inventory claims. Cart and checkout are the final source of price and availability truth.

Shopify Liquid language and commerce data