Catalog and discovery

Products, listings, filters, search, merchandising entities, and product history.

These pages list the exact data fields available to hosted Vascula themes. Add a root name such as product to a section's ctx_needs, then read it directly as product.title in the template. The ctx. prefix shown here identifies the public contract; do not include that prefix in a Vascula expression. Required fields are present whenever their containing object is present. Optional fields may be absent, and nullable fields may be present as null. [] marks an array item and {key} marks a key selected at runtime. Named types such as Price and Media are detailed on Shared data shapes.

ctx.product#

The routed product with variants, options, pricing, availability, session state, and storefront-visible metafields. Available on Product routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.product`	Object	Declared root
`ctx.product.available_for_sale`	Boolean	Required
`ctx.product.barcode`	String or null	Required; may be null
`ctx.product.brand`	String or null	Optional; may be null
`ctx.product.brand_ref`	Entity	Optional
`ctx.product.cart_requirements`	Array of object	Optional
`ctx.product.cart_requirements[].key`	String	Required
`ctx.product.cart_requirements[].namespace`	String	Required
`ctx.product.categories`	Array of object	Required
`ctx.product.categories[].id`	Integer	Required
`ctx.product.categories[].name`	String	Required
`ctx.product.categories[].slug`	String	Required
`ctx.product.categories[].url`	URL	Required
`ctx.product.collections`	Array of catalog entity ref	Optional
`ctx.product.condition`	String	Optional
`ctx.product.country_of_origin`	String or null	Optional; may be null
`ctx.product.description`	HTML or null	Required; may be null
`ctx.product.dimension_unit`	String or null	Optional; may be null
`ctx.product.display_variant`	Variant or null	Required; may be null
`ctx.product.featured_image`	Media or null	Required; may be null
`ctx.product.gift_only`	Boolean	Required
`ctx.product.height`	Number or null	Optional; may be null
`ctx.product.id`	Integer	Required
`ctx.product.identifier_status`	String	Optional
`ctx.product.images`	Array of media or null	Required
`ctx.product.inventory_status`	String	Required
`ctx.product.is_gift_card`	Boolean	Required
`ctx.product.length`	Number or null	Optional; may be null
`ctx.product.max_order_quantity`	Integer or null	Required; may be null
`ctx.product.metafields`	Metafields	Optional
`ctx.product.mpn`	String or null	Optional; may be null
`ctx.product.no_manufacturer_identifiers`	Boolean	Optional
`ctx.product.notify_me_eligible`	Boolean	Required
`ctx.product.options`	Array of option	Required
`ctx.product.price`	Price or null	Required; may be null
`ctx.product.price_range`	Price range or null	Required; may be null
`ctx.product.price_tiers`	Array of price tier	Required
`ctx.product.purchase_state`	String (`in_stock`, `unavailable`)	Required
`ctx.product.quantity_available`	Integer or null	Optional; may be null
`ctx.product.quantity_max`	Integer or null	Required; may be null
`ctx.product.rating`	Rating	Optional
`ctx.product.related`	Array of product card	Optional
`ctx.product.requested_options`	Array of selected option	Required
`ctx.product.requires_shipping`	Boolean	Required
`ctx.product.selected_variant`	Variant or null	Required; may be null
`ctx.product.selection_complete`	Boolean	Required
`ctx.product.seo_description`	String or null	Required; may be null
`ctx.product.seo_title`	String or null	Required; may be null
`ctx.product.session_state`	Object	Required
`ctx.product.session_state.cart`	Object	Required
`ctx.product.session_state.cart.direct_line_count`	Integer	Required
`ctx.product.session_state.cart.direct_quantity`	Integer	Required
`ctx.product.session_state.cart.line_count`	Integer	Required
`ctx.product.session_state.cart.quantity`	Integer	Required
`ctx.product.session_state.wishlist`	Object	Required
`ctx.product.session_state.wishlist.direct_item_count`	Integer	Required
`ctx.product.session_state.wishlist.direct_saved`	Boolean	Required
`ctx.product.session_state.wishlist.item_count`	Integer	Required
`ctx.product.session_state.wishlist.saved`	Boolean	Required
`ctx.product.short_description`	String or null	Required; may be null
`ctx.product.sku`	String or null	Required; may be null
`ctx.product.slug`	String	Required
`ctx.product.tag_refs`	Array of object	Required
`ctx.product.tag_refs[].id`	Integer	Required
`ctx.product.tag_refs[].name`	String	Required
`ctx.product.tag_refs[].slug`	String	Required
`ctx.product.tag_refs[].url`	URL	Required
`ctx.product.tags`	Array of string or null	Required; may be null
`ctx.product.title`	String	Required
`ctx.product.type`	String	Required
`ctx.product.url`	URL	Required
`ctx.product.variants`	Array of variant	Required
`ctx.product.vendor`	String or null	Required; may be null
`ctx.product.vendor_ref`	Entity	Optional
`ctx.product.weight`	Number or null	Optional; may be null
`ctx.product.weight_unit`	String or null	Optional; may be null
`ctx.product.width`	Number or null	Optional; may be null

ctx.products#

A routed product grid with platform search, sort, and pagination state. Available on Shop, Search, Collection, Category, Vendor, Brand routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.products`	Object	Declared root
`ctx.products.items`	Array of product card	Required
`ctx.products.pagination`	Pagination	Required
`ctx.products.search`	Object	Required
`ctx.products.search.enabled`	Boolean	Required
`ctx.products.search.query`	String	Required
`ctx.products.search.url`	URL	Required
`ctx.products.sort`	Object	Required
`ctx.products.sort.current`	String	Required
`ctx.products.sort.options`	Array of object	Required
`ctx.products.sort.options[].key`	String	Required
`ctx.products.sort.options[].selected`	Boolean	Required
`ctx.products.sort.options[].url`	URL	Required

ctx.filters#

Platform-resolved filters and active filter state for the current product listing. Available on Shop, Search, Collection, Category, Vendor, Brand routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.filters`	Object	Declared root
`ctx.filters.applied_count`	Integer	Required
`ctx.filters.clear_url`	URL	Required
`ctx.filters.count_label`	String	Optional
`ctx.filters.counts_estimated`	Boolean	Optional
`ctx.filters.inputs`	Array of object	Required
`ctx.filters.inputs[].name`	String	Required
`ctx.filters.inputs[].value`	String	Required
`ctx.filters.items`	Array of object	Required
`ctx.filters.items[].allow_multiple`	Boolean	Required
`ctx.filters.items[].applied_count`	Integer	Required
`ctx.filters.items[].clear_url`	URL	Required
`ctx.filters.items[].display_type`	String	Required
`ctx.filters.items[].filter_type`	String	Required
`ctx.filters.items[].key`	String	Required
`ctx.filters.items[].label`	String	Required
`ctx.filters.items[].range`	Object or null	Required; may be null
`ctx.filters.items[].range.action`	URL	Required
`ctx.filters.items[].range.applied_max`	String	Required
`ctx.filters.items[].range.applied_min`	String	Required
`ctx.filters.items[].range.clear_url`	URL	Required
`ctx.filters.items[].range.inputs`	Array of object	Required
`ctx.filters.items[].range.inputs[].name`	String	Required
`ctx.filters.items[].range.inputs[].value`	String	Required
`ctx.filters.items[].range.integer`	Boolean	Required
`ctx.filters.items[].range.max`	Decimal string or null	Required; may be null
`ctx.filters.items[].range.max_input`	String	Required
`ctx.filters.items[].range.min`	Decimal string or null	Required; may be null
`ctx.filters.items[].range.min_input`	String	Required
`ctx.filters.items[].values`	Array of object	Required
`ctx.filters.items[].values[].color`	String or null	Required; may be null
`ctx.filters.items[].values[].count`	Integer	Required
`ctx.filters.items[].values[].count_estimated`	Boolean	Optional
`ctx.filters.items[].values[].count_label`	String	Optional
`ctx.filters.items[].values[].image_url`	String or null	Required; may be null
`ctx.filters.items[].values[].key`	String	Required
`ctx.filters.items[].values[].label`	String	Required
`ctx.filters.items[].values[].selectable`	Boolean	Required
`ctx.filters.items[].values[].selected`	Boolean	Required
`ctx.filters.items[].values[].url`	URL	Required
`ctx.filters.items[].values_page`	Object or null	Required; may be null
`ctx.filters.items[].values_page.action`	URL	Required
`ctx.filters.items[].values_page.clear_url`	URL	Required
`ctx.filters.items[].values_page.has_next`	Boolean	Required
`ctx.filters.items[].values_page.has_previous`	Boolean	Required
`ctx.filters.items[].values_page.inputs`	Array of object	Required
`ctx.filters.items[].values_page.inputs[].name`	String	Required
`ctx.filters.items[].values_page.inputs[].value`	String	Required
`ctx.filters.items[].values_page.limit`	Integer	Required
`ctx.filters.items[].values_page.next_url`	URL	Required
`ctx.filters.items[].values_page.offset`	Integer	Required
`ctx.filters.items[].values_page.previous_url`	URL	Required
`ctx.filters.items[].values_page.search`	String	Required
`ctx.filters.items[].values_page.search_input`	String	Required
`ctx.filters.items[].values_page.total`	Integer	Required
`ctx.filters.price`	Object	Optional
`ctx.filters.price.action`	URL	Required
`ctx.filters.price.applied_max`	String	Required
`ctx.filters.price.applied_min`	String	Required
`ctx.filters.price.clear_url`	URL	Required
`ctx.filters.price.currency_code`	String	Required
`ctx.filters.price.inputs`	Array of object	Required
`ctx.filters.price.inputs[].name`	String	Required
`ctx.filters.price.inputs[].value`	String	Required
`ctx.filters.price.integer`	Boolean	Required
`ctx.filters.price.label`	String	Required
`ctx.filters.price.max`	Decimal string or null	Required; may be null
`ctx.filters.price.max_input`	String	Required
`ctx.filters.price.max_money`	Money input or null	Required; may be null
`ctx.filters.price.min`	Decimal string or null	Required; may be null
`ctx.filters.price.min_input`	String	Required
`ctx.filters.price.min_money`	Money input or null	Required; may be null

Use filters in a section’s ctx_needs. Iterate filters.items to render enabled choice, numeric, and price filters in merchant order. filters.price also provides the price currency and money objects; do not render a second price control from it. The same contract is available on shop, search, collection, category, vendor, and brand product listings.

Use each choice’s url for navigation. selected identifies active choices and selectable tells you whether toggling the choice stays within the query limits. A selected value can have a count of zero. Keep it visible so the shopper can remove it. allow_multiple controls whether another choice is added or replaces the current one; use it to distinguish multiple-choice and single-choice controls.

Render numeric and price controls from item.range. For the item whose key is price, filters.price adds currency and money-formatting fields. The available min and max are decimal strings or null when no products provide a range. applied_min and applied_max preserve the current bounds even when the results are empty. Integer sources require whole-number bounds. Price bounds use the resolved storefront currency; custom numeric ranges may be negative.

For a range form, use GET with the supplied action, render every inputs entry as a hidden name/value input, and use min_input and max_input as the editable field names. Display editable amounts left-to-right with a period as the decimal separator and no grouping. An empty bound removes that boundary. Use the supplied clear_url to remove the range.

values_page describes the current window of choices: search text, offset, limit, total and previous/next links. Pages default to 50 choices and allow up to 100. Selected choices are returned as well, including selections outside the current page or search. Render each value once; do not treat the returned array length as the page size. For value search, use GET with the page’s action, inputs, and search_input.

Use filters.inputs to preserve filter selections in a product-search form. These pairs include all applied choice and range inputs. Preserve the listing sort separately. Selection or range changes reset product pagination; paging the choices does not change the selected products. Use filters.clear_url for clear all and each item’s clear_url for that filter.

Direct URL input uses repeated filter.<key>=<value> for choices and filter.<key>.min / .max for ranges. Attribute keys are attribute:<slug>; metafield keys are metafield:<owner_type>:<namespace>.<key>. For example, filter.metafield:variant:specs.length.min=10.5. Choice paging uses facet.<key>.search, .offset, and .limit. Prefer generated controls so URL encoding and preservation remain correct.

Requests accept at most 50 selected filter keys, 100 values per key, 256 choice values overall, and 8,192 URL-encoded filter bytes. Choice values are limited to 255 characters. Disabled or unknown keys, unsupported multiple choices, malformed bounds, and exceeded limits are rejected with STOREFRONT_FILTER_INVALID. Counts apply every other selected filter, while variant-level choices and ranges must match the same variant.

ctx.search#

The search query, grouped result totals, and canonical result projections. Available on Search routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.search`	Object	Declared root
`ctx.search.query`	String	Required
`ctx.search.results`	Object	Required
`ctx.search.results.products`	Object	Optional
`ctx.search.results.products.items`	Array of product card	Required
`ctx.search.results.products.pagination`	Object	Required
`ctx.search.results.products.pagination.count_label`	String	Optional
`ctx.search.results.products.pagination.current_page`	Integer	Required
`ctx.search.results.products.pagination.has_next`	Boolean	Required
`ctx.search.results.products.pagination.has_prev`	Boolean	Required
`ctx.search.results.products.pagination.next_cursor`	String	Optional
`ctx.search.results.products.pagination.next_url`	String	Optional
`ctx.search.results.products.pagination.prev_url`	String	Optional
`ctx.search.results.products.pagination.total_count`	Integer	Required
`ctx.search.results.products.pagination.total_estimated`	Boolean	Optional
`ctx.search.results.products.pagination.total_pages`	Integer	Required
`ctx.search.results.{key}`	Array of object	Dynamic key
`ctx.search.results.{key}[].excerpt`	String	Required
`ctx.search.results.{key}[].image`	Media or null	Optional; may be null
`ctx.search.results.{key}[].title`	String	Required
`ctx.search.results.{key}[].url`	URL	Required
`ctx.search.totals`	Object keyed by name	Required
`ctx.search.totals.{key}`	Integer	Dynamic key

ctx.collection#

The routed collection metadata and storefront-visible metafields. Available on Collection routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.collection`	Object	Declared root
`ctx.collection.ancestors`	Array of catalog entity ref	Optional
`ctx.collection.children`	Array of catalog entity ref	Optional
`ctx.collection.description`	String or null	Required; may be null
`ctx.collection.id`	String	Required
`ctx.collection.image`	Media or null	Required; may be null
`ctx.collection.metafields`	Metafields	Optional
`ctx.collection.name`	String	Required
`ctx.collection.parent`	Catalog entity ref or null	Optional; may be null
`ctx.collection.product_count`	Integer	Required
`ctx.collection.seo_description`	String or null	Optional; may be null
`ctx.collection.seo_title`	String or null	Optional; may be null
`ctx.collection.slug`	String	Required
`ctx.collection.url`	URL	Optional

ctx.category#

The routed category metadata and storefront-visible metafields. Available on Category routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.category`	Object	Declared root
`ctx.category.ancestors`	Array of catalog entity ref	Optional
`ctx.category.children`	Array of catalog entity ref	Optional
`ctx.category.description`	String or null	Required; may be null
`ctx.category.id`	Integer	Required
`ctx.category.image`	Media or null	Required; may be null
`ctx.category.metafields`	Metafields	Optional
`ctx.category.name`	String	Required
`ctx.category.parent`	Catalog entity ref or null	Optional; may be null
`ctx.category.product_count`	Integer	Required
`ctx.category.seo_description`	String or null	Optional; may be null
`ctx.category.seo_title`	String or null	Optional; may be null
`ctx.category.slug`	String	Required
`ctx.category.url`	URL	Optional

ctx.vendor#

The routed vendor metadata and storefront-visible metafields. Available on Vendor routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.vendor`	Entity	Declared root

ctx.brand#

The routed brand metadata and storefront-visible metafields. Available on Brand routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.brand`	Entity	Declared root

ctx.list#

The generic vendor, brand, collection, or category index for the routed list page. Available on Vendor list, Brand list, Collection list, Category list routes when declared in ctx_needs.

Field	Type	Requirement
`ctx.list`	Object	Declared root
`ctx.list.items`	Array of entity	Required
`ctx.list.pagination`	Object	Required
`ctx.list.pagination.current_page`	Integer	Required
`ctx.list.pagination.has_next`	Boolean	Required
`ctx.list.pagination.has_prev`	Boolean	Required
`ctx.list.pagination.next_url`	String	Required
`ctx.list.pagination.prev_url`	String	Required
`ctx.list.pagination.total_count`	Integer	Required
`ctx.list.pagination.total_count_capped`	Boolean	Required
`ctx.list.pagination.total_pages`	Integer	Required
`ctx.list.title`	String	Required

ctx.recently_viewed#

Visibility-gated product cards recently viewed on this device. Loaded when a section declares it in ctx_needs.

Field	Type	Requirement
`ctx.recently_viewed`	Object	Declared root
`ctx.recently_viewed.items`	Array of product card	Required

ctx.restock_notifications#

Availability and channel rules for a product restock request form. Loaded when a section declares it in ctx_needs.

Field	Type	Requirement
`ctx.restock_notifications`	Object	Declared root
`ctx.restock_notifications.email_input_required`	Boolean	Required
`ctx.restock_notifications.enabled`	Boolean	Required
`ctx.restock_notifications.login_required`	Boolean	Required
`ctx.restock_notifications.mode`	String	Required
`ctx.restock_notifications.sms_available`	Boolean	Required