Each section declares its own ctx_needs. A parent section does not grant its declarations to a child section. Declare a root such as product, or a supported dotted need such as cart.item_count; read the resulting object directly by name.
CTX values are prepared for the selected storefront and shopper. Use the provided URLs, prices, availability, and limits instead of reconstructing them from names or identifiers. Undeclared data is not available to the section.
Area |
Roots |
Use |
|---|---|---|
Shop and navigation |
shop, routes, menus |
Shop identity, canonical links, and menu summaries. A menu picker setting supplies the selected menu's items. |
Localization |
localization, localization_prompt |
Active language and country, the country and language choices, and whether to suggest a change. |
Consent |
consent |
Whether to ask for cookie consent, the recorded choice, and the categories the banner offers. |
Catalog |
product, products, collection, category, vendor, brand, list |
Product details, grids, merchandising entities, and their indexes. |
Discovery |
search, filters, breadcrumbs, recently_viewed |
Grouped search results, filtering, navigation trails, and recently viewed products. |
Content |
page, pages, policy, policies, blog_post, blog, blog_category, blog_recent |
Published content and bounded content indexes. |
Shopping |
cart, wishlist, restock_notifications |
Counts, requested product lines, purchase state, and restock-form availability. |
Reviews |
reviews, store_reviews |
Enabled state, approved review summaries, and requested review items. |
Customers and forms |
customer, customer_settings, forms, phone_countries |
Customer identity, merchant account options, and form constraints. |
Form feedback |
form_error, auth_notice, auth_form, form_notice, review_notice, csrf_token |
Localized feedback and hosted-form state. review_notice remains a compatibility alias. |
localization.country is the country the shopper is shopping in, and its currency is the currency prices use. On a shared domain, a country other than the store's own is served at a /{locale}-{country} address such as /en-gb/; see Locale, country, and currency.
consent.required says whether to ask the visitor, consent.given and consent.categories describe the recorded choice, and consent.available_categories lists the categories the banner offers. See Customers, carts, and consent and Consent categories.
Counts and full lists#
Use cart.item_count or wishlist.item_count for a header badge. Declare cart.items or wishlist.items for product lines. Declare reviews.items for review rows, and customer.addresses or customer.orders for account lists. Use the exact reference for each shape and its pagination fields.
Catalog and search#
A product page provides product. Shop, category, collection, vendor, brand, and search pages can provide products. The products object contains items, sort, search, and pagination. An empty search query or disabled product-search result type does not turn a search page into the whole catalog.
On a search page, search.query is the query, search.totals contains counts by result type, and search.results contains the enabled groups. search.results.products contains items and pagination; content groups such as pages and blog_posts contain title, excerpt, and url cards. The products root and search product group describe the same product results. Follow the supplied pagination and filter URLs.
Filters expose selected values, counts, toggle URLs, applied_count, and clear_url. Counts keep other choices usable while a filter is selected. filters.price is optional: an empty result set may have no price range. Keep the clear-filter control available when applied_count is nonzero.
Content and account data#
Blog and blog-category pages use blog for article cards and pagination; blog_category supplies category details. A blog-post page uses blog_post, including its approved comments and comment-form availability. pages, policies, and blog_recent can be requested for navigation or content sections on other normal storefront pages.
customer is absent for guests. Use customer_settings for the account methods and features the merchant has enabled. Account addresses, orders, and receipts are available only for the authenticated customer; a template does not select another customer by ID.
Typed values and failures#
Required fields exist when their containing object exists. Optional fields may be absent; nullable fields may be null. Money amounts and tax-rate decimals use the string forms documented in the reference. Use the money filter for display. An unavailable price is not zero, and a failed required data read is not an empty result.
The complete field definitions are in Context Reference. They are the authoritative list for developer tooling as well. When you upload a theme, each section's ctx_needs is checked against the same contract, and a section that declares a root that does not exist is rejected.