Catalog data

Render translated cards, prices, filters, references and catalog entities.

Catalog data available to themes#

themectx/contract.go, domains.go, and the exported metafield_types map are canonical. Catalog reads use the same channel, currency, inventory and tax rules on every card surface. These fields are available on grids, rails, merchant picks, product/variant metafield references and search cards.

Path	Value and meaning
`product_card.slug`, `media`	Effective URL slug and featured media; `media` has the same shape as `featured_image`.
`product_card.inventory_status`	`in_stock`, `low_stock`, or `out_of_stock`, resolved from live online-fulfilment stock for this sales channel.
`product_card.rating`	`{average, count}` from approved review statistics; absent when reviews are off or there are no approved reviews.
`product_card.vendor_url`, `brand_url`	Addressed, translated entity URLs; null without the entity. `vendor` and `brand` are translated names.
`product_card.published_at`, `sales_count`	UTC publication timestamp or null; sold units including the merchant's baseline.
`price.variant_id`	Variant supplying a variable product's starting price; null for a simple product.
`price_range.min_variant_id`, `max_variant_id`	Variant at each end of the range. Tax projection uses that variant's market tax class.
`price.sale_starts_at`, `sale_ends_at`	Scheduled sale window in UTC, or null for an open end. The dates can exist before a sale becomes active. Use `on_sale` for current sale state.
`product.cart_requirements[]`	`{namespace, key}` required cart-line properties; render the corresponding app-owned input before adding to cart.
`product.collections[]`	Active memberships as `{id, name, slug, url}` in the shopper's language.
`product.mpn`, `condition`, `identifier_status`, `no_manufacturer_identifiers`	Merchant identifier facts; `sku` and `barcode` remain available.
`variant.barcode`, `mpn`, `condition`, `identifier_status`, `no_manufacturer_identifiers`	Effective variant value, inheriting the product value when unset. SKU remains variant-specific.
`product` and `variant`: `weight`, `weight_unit`, `length`, `width`, `height`, `dimension_unit`, `country_of_origin`	Nullable physical facts. Variants inherit unset values; origin is an ISO country code.
`collection` and `category`: `url`, `seo_title`, `seo_description`	Addressed entity URL and nullable translated SEO text.
`collection` and `category`: `parent`, `children[]`, `ancestors[]`	Navigation references `{id, name, slug, url}`. Category ancestors are root first and exclude the category itself. Collections are flat: null parent and empty arrays.
`products.pagination.total_estimated`, `count_label`	Above 20,000 matching products, `total_count` is a bounded lower estimate; display the backend's label (for example `20000+`). Whole-catalog search considers at most 1,000 indexed candidates.
`products.pagination.next_cursor`, `next_url`	Numbered page links stop at 50. Follow `next_url` to continue through a keyset cursor, preserving filters and sort. A filter/sort change clears the cursor.
`filters.counts_estimated`, `count_label`	Counts over a large scope are bounded lower estimates.
`filters.items[].values[].count_estimated`, `count_label`	Render this label beside the value, instead of treating `count` as exact. Price slider bounds remain exact within the listing/search scope and use cards' tax display.
`search.results.<content_type>[].image`	Translated file media or null, loaded once across content search groups.
Cart `property_list[].name`	Translated metafield-definition name. Select display values use translated choice labels. Property keys and saved values stay canonical.

Foreign-currency prices apply the request's current rate and rounding to native endpoints, including automatic exchange rates. Explicit currency rows still override conversion per variant. Equal displayed endpoints prefer an explicit currency price, then the native endpoint and the lowest variant ID; PDP and cards use the same rule.

Quantity tiers are always attached after tax projection, including rails, picks, references and wishlists. The product, variant and card purchase_state enum is in_stock or unavailable; preview uses the same enum.

Text tries the requested locale, its language, then the store's source/default text. An empty translation continues down that chain. Slugs use their exact locale, then the source slug: borrowing another locale's slug would create URL collisions. Media alt_text uses product_media.alt_text for galleries and variant images, and file.alt_text for file metafields and collection/category images. Do not substitute a product title for a translated alt value.

Facet headings and select labels are translated independently. Free-text attribute labels use attribute_text_value.label, whose resource id is attribute_id:value_text. Non-select metafields use the corresponding product/variant metafield value translation; when a source value is shared, the first available translated owner value in product order supplies its label. Tokens in filter URLs always remain source values.

Metafield value types#

Read metafields[namespace][key] directly, without a {type, value} wrapper. Schema.metafield_types declares every supported definition type:

Definition type	Theme value
`string`, `url`, `single_select`	Text; a select is its translated display label.
`integer`, `decimal`, `boolean`	Native integer, decimal or boolean. Decimals retain numeric operations and their stored precision when printed.
`date`, `datetime`	Native date value accepted by the date filter; JSON is ISO text, with the store offset for datetime.
`json`	Parsed JSON.
`file_reference`	`{id, url, alt_text, media_type, mime_type, filename, width, height}` or null. `media_type` also permits `document`.
`product_reference`	A visibility-checked product card, or null.
`variant_reference`	`{id, title, sku, url, available_for_sale, price, featured_image, product}`, with picker `options`, `price_str`, `regular_price_str` when resolved. `product` is the card; the resolved variant `price` is money input `{amount, currency_code}`.
`list.string`, `list.url`, `list.single_select`, `list.file_reference`, `list.product_reference`, `list.variant_reference`	Array of the corresponding value type; unavailable references are omitted.

Reference hydration is lazy and batched across the grid. It admits at most 256 unique product/variant references per request and follows one reference level. Product galleries read at most 250 media rows and PDP rosters at most 2,000 variants. Card pricing reads only the precomputed price endpoints.

Proposal: product specifications#

P2-4 remains a proposal. A future specification-value table could hold non-variant attributes such as Material and expose product.specifications[]. This change adds no table or theme field for it.