Product schema

Product schema overview

The product schema is a standardized format that transforms your Shopify product data into an optimized structure for the search and browse engine.

Catalog scale and limits

Layers has no hard limits on the number of products, variants, or SKUs that can be synced and indexed. Layers scales with your catalog and has handled catalogs with millions of SKUs.

Schema fields

The following table outlines the key fields in the product schema, along with their data types, descriptions, and example values:

Field Name	Type	Description	Example Value
id	Integer	Unique identifier for the product	`7003338965178`
title	String	Title of the product	`"SUPREME SEALLINE SEE POUCH SMALL"`
body_html	String	HTML content describing the product	`"The Supreme Sealline See Pouch Small is a versatile and..."`
vendor	String	The product’s vendor	`"SUPREME"`
product_type	String	Type of the product	`"Accessories"`
created_at	DateTime	DateTime when the product was created	`"2022-02-05T01:22:27.000000Z"`
handle	String	A unique human-friendly string for the product, used in the product’s URL	`"supreme-pouch-44370ss18a32-sm"`
category	Object	The category of a product from Shopify’s Standard Product Taxonomy	`{"id": "gid://shopify/TaxonomyCategory/aa-1", "name": "Clothing", "is_leaf": false, "is_root": false, "full_name": "Apparel & Accessories > Clothing"}`
combined_listing_parent_product_id	Integer	Product ID of the parent for combined listings	`7003338965178`
combined_listing_role	String	Role in a combined listing	`"PARENT"`
featured_media	Object	The featured media.	`{"alt": "The top and bottom view of a snowboard. The top has view is turquoise and black with graphics of\n trees. The bottom view is turquoise with the word hydrogen written in cursive.", "src": "https://cdn.shopify.com/s/files/1/0630/8265/9999/files/Main.jpg?v=1736281499", "width": 1600, "height": 1600, "mediaContentType": "IMAGE"}`
updated_at	DateTime	DateTime when the product was last updated	`"2023-10-25T20:47:04.000000Z"`
published_at	DateTime	DateTime when the product was published	`"2022-02-05T01:22:27.000000Z"`
tags	Array of Strings	Tags associated with the product	`["Collection: Best Seller", "Collection:Accessories", "Collection:Supreme Accessories"]`
images	Array of Objects	Images related to the product.	`[{"alt": "SUPREME POUCH", "src": "https://cdn.shopify.com/", "width": 800, "height": 534, "variant_ids": []}]`
metafields	Object	Configured metafields for the product	`{"product": {"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK", "styleCode": "SS18A30 BLACK", "yearOfRelease": 2018}}`
available	Boolean	Availability status of the product	true
is_gift_card	Boolean	Whether the product is a gift card	false
has_variants_that_require_components	Boolean	Whether the product has variants that require bundle components (used for bundle products)	false
published_on_web	Boolean	Whether the product is published to the Online Store sales channel	true
published_on_app	Boolean	Whether the product is published to your storefront app sales channel	true
available_market_ids	Array of Integers	Shopify Market IDs the product is currently available in. Populated when markets sync is enabled.	`[2001, 2002]`
price_range	Object	Price range of the product, including from and to fields	`{"from": 7.97, "to": 7.97, "compare_at_price": 7.97}`
total_inventory	Integer	Sum of every variant’s `inventory_quantity` across all variants and locations. Untracked variants contribute `0`. Negative values are not clamped. This is a product-level rollup and is not scoped to a location or market.	`42`
options	Object	Dynamically created object from product options (can be an array of any type, depending on the product configuration). The key is case-sensitive.	`{"Size": ["S", "M", "L"]}`
original_options	Object	Dynamically created object from product options (can be an array of any type, depending on the product configuration). The key is case-sensitive. This set of options is unfiltered.	`{"Size": ["S", "M", "L"]}`
options_v2	Array of Objects	Extended options array with swatch and linked metafield data. Preserves Shopify’s option ordering and includes visual swatch information (color, image) and linked metafield values for each option value.	See options_v2 Structure
named_tags	Object	Dynamically created object of ‘key:value’ tags on the product. Keys/values in this object are not included in the `tags` array	`{"YearOfRelease": 2016}`
calculated	Object	Computed attributes defined in the Layers dashboard. Contains dynamic values from Functions, derived attributes, and legacy computed attributes. Attributes that evaluate to null or an empty string are excluded from this object.	`{"sku_coverage": 0.85, "days_available": 30}`
selling_plans	Object	Shopify selling plan groups the product is enrolled in, with a discount and category rollup. Deferred by default. Request it explicitly via `attributes`. See Selling plans.	`{"max_discount_percentage": 15.0, "categories": ["subscription"], "groups": [{"id": 78129334, "name": "Subscribe & Save", "merchant_code": "subscribe-and-save", "plans": [{"id": 3941002, "name": "Deliver every month", "category": "subscription"}]}]}`

You can provide type-hints to Named Tags by using the {key}:{type}:{value} tag format. Supported types: number, boolean, and date.

King Linked Options groups

Enable King Linked Options and sync the catalog before using its product-card data. In search, browse, or block requests, include external.king_linked_options.group in attributes alongside the other fields your cards need. Read the group at results[].external.king_linked_options.group, not a top-level linked_options field. This follows the normal external-attribute projection: requesting the whole external object or using the default response also includes synced integration data. The group is an object or null; handle an absent integration or empty group without failing the rest of the product card.

Field	Meaning
`groupId`	King group identifier, returned as a string.
`name`	Group title.
`hideOnCards`	King’s hide-on-collection-cards preference. Your renderer must honor it.
`values`	Published sibling entries in King’s stored order. It can be empty.
`values[].productId`	Numeric Shopify product ID, or `null` if unavailable.
`values[].handle`	Product handle used to build a product link.
`values[].label`	Option label supplied by King.
`values[].colors`	Zero, one, or two color values for the swatch.
`values[].image`	Swatch image when no color values are present, otherwise `null`.
`values[].available`	Availability derived from King’s out-of-stock flag at sync time.
`values[].current`	Whether the entry’s product ID matches the product being returned.

Validate that a handle and usable label exist before rendering a link. Use colors when present, otherwise the swatch image or a text fallback. Treat availability as synced display data, not a checkout guarantee. This integration does not merge sibling products into a single result or add swatch UI automatically. Layers refreshes eligible storefront-sourced integration data every six hours, in addition to product resyncs. Missing, inactive, deleted, or invalid groups replace stale group data with null; incomplete or failed sync responses keep the previous data. Disabling the integration removes its external attributes through normal integration cleanup.

API response type consistency

The following fields are guaranteed to always be returned as JSON objects (or null) in API responses, never as empty arrays. This keeps types consistent for API consumers and prevents type mismatches in strongly-typed clients:

metafields - Always an object or null
calculated - Always an object or null
named_tags - Always an object or null
category - Always an object or null
featured_media - Always an object or null
first_or_matched_variant - Always an object or null
price_range - Always an object or null

When these fields have no data, the API returns {} (empty object) or null, never [] (empty array). The API enforces this behavior at the response level to maintain consistent typing across all endpoints.

Sequential array fields like tags and images are not affected by this enforcement and continue to return as arrays.

Data types and formatting

Integer: Whole numbers without decimals.
String: Textual data, often used for titles or descriptions.
Decimal: Numbers with decimal points, typically used for prices.
Array: A list of values, used for tags or features.
Boolean: A true or false value, indicating binary states such as availability.

Overview

Metafields

Product schema

Product schema overview

Catalog scale and limits

Schema fields

King Linked Options groups

API response type consistency

Data types and formatting

See also

​Product schema overview

​Catalog scale and limits

​Schema fields

​King Linked Options groups

​API response type consistency

​Data types and formatting

​See also

Product schema overview

Catalog scale and limits

Schema fields

King Linked Options groups

API response type consistency

Data types and formatting

See also