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": []}]`
media	Array of Objects	Ready images, videos, external videos, and 3D models in Shopify order.	See Product media.
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.

Product media

Use media for images, Shopify-hosted videos, external videos, and 3D models in Shopify order. It is not returned by default: include media in attributes to get it. Requesting media does not also select images. The existing images field is unchanged. Each entry includes these fields:

Field	Type	Description
`id`	String or null	Shopify media ID, such as `gid://shopify/MediaImage/123456789`, or `null` if unavailable.
`type`	String	`IMAGE`, `VIDEO`, `EXTERNAL_VIDEO`, or `MODEL_3D`.
`position`	Integer	One-based position in the full Shopify media list. Positions can have gaps when entries are skipped.
`alt`	String or null	Alt text for the media.

The remaining fields depend on type:

Type	Additional fields
`IMAGE`	`src`, `width`, `height`.
`VIDEO`	`duration`, `preview`, `sources`: an array of objects with `url`, `mime_type`, `format`, `width`, `height`.
`EXTERNAL_VIDEO`	`host`, `embed_url`, `origin_url`, `preview`.
`MODEL_3D`	`preview`, `sources`: an array of objects with `url`, `mime_type`, `format`, `filesize`.

preview is either an object containing src, width, and height, or null when no preview image is available. URLs, alt text, host, MIME types, and formats are strings; dimensions, video duration, and file size are numbers. Missing metadata is null, not an omitted key. Only media with Shopify status READY is included. Images without an image URL, videos and 3D models without sources, and external videos without an embed URL are skipped. The result is always a list, including [] when empty. For products that have not yet re-synced since media became available, media falls back to their existing images as IMAGE entries with id: null, position, alt, src, width, and height. Each product’s next sync replaces that fallback with its ready Shopify media; you do not need to change how you read images.

Selecting media

Use these selectors in attributes to return only the media you need:

Selector	Result
`media[0]`	The first entry, still wrapped in a list.
`media[:2]`	The first two entries.
`media[type=VIDEO]`	Shopify-hosted videos only.
`media[type=VIDEO,EXTERNAL_VIDEO]`	Shopify-hosted and external videos, in their original order.

Indexes are zero-based, unlike the one-based position field. Type values are case-insensitive, so media[type=video] also works. Only type filters with IMAGE, VIDEO, EXTERNAL_VIDEO, or MODEL_3D are supported; another filter key or an unknown type returns a 400 invalid-field-selector error. The image fallback applies before filtering or slicing. For a product awaiting its next media sync, media[type=IMAGE] returns its fallback images and media[type=VIDEO] returns []. An out-of-range index or a filter with no matches also returns []; the product stays in the results.

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, images, and media 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

Product media

Selecting media

King Linked Options groups

API response type consistency

Data types and formatting

See also

​Product schema overview

​Catalog scale and limits

​Schema fields

​Product media

​Selecting media

​King Linked Options groups

​API response type consistency

​Data types and formatting

​See also

Product schema overview

Catalog scale and limits

Schema fields

Product media

Selecting media

King Linked Options groups

API response type consistency

Data types and formatting

See also