ProductSummary to display search results and ProductDetail for a full product record. Each entry in ProductDetail.variants is a ProductVariant. The compatibility table maps each new name to its existing SDK import and OpenAPI component.
ProductSummary
Search and More Like This return summaries initems[]. Brand product browsing returns them in products[]. See Search products and More Like This.
ProductSummary example
Scoped available options
For organizations with scoped product search and retrieve enabled,ProductSummary and ProductDetail can include availableOptions.
Compare every key and value in your selection with
selectedOptions in a row. Key order can differ. Use optionIndex to find look links, and options to display choices. Sizes and other options can vary within a look.
Find and retrieve Black + Tall
This example uses illustrative IDs and a catalog group with separate indexed looks for Black + Regular and Black + Tall. A catalog that indexes looks by color alone may return a row for Black and list fit as a display value. Send a search request for the product group.{"color":"Black","fit":"Tall"} against the complete selection in the second row. Pass its productUuid unchanged to retrieve that look.
product.variants for the purchasable units within it.
ProductDetail
Find the detail inproduct after product lookup, single-product retrieval (GET /products/retrieve/{uuid}), or resolving from HTML (POST /products/resolve-from-html). Batch retrieval (POST /products/retrieve) returns it in results[].product for each product found.
ProductDetail shares most fields with ProductSummary. The table below lists its different and additional fields. Summary fields gender, categoryPath, and catalogDisplayName appear only on ProductSummary. A detail response carries audience and categories in separate fields.
On-demand lookup can return images with the merchant URL only. Use
primaryImage.cdnUrl when available and fall back to primaryImage.url.
ProductDetail example
ProductVariant
One entry inProductDetail.variants[]. All fields can be null when the merchant supplies no value.
ProductImage
BothprimaryImage and each entry in images[] use this shape.
Supporting models
ProductBrand
Brand displayed on a product. It contains a requiredname (string) and nullable string fields slug, url, and description. Use slug with the brand_slug facet.
ProductRatingSummary
Product-level rating withaverage (number or null) and count (integer or null).
ProductColor
Color data inProductDetail.colors[] and ProductVariant.color. It contains a required label (string), plus hexCode and swatchUrl (strings or null).
ProductCategory
One entry inProductDetail.categories[]. It contains a required category name (string) and a merchant category url (string or null).
ProductAudience
Target audience represented bygenders and ageGroups (arrays of strings). Both default to empty arrays.
ProductBreadcrumb
One entry in the merchant’s navigation trail. It contains a requiredname (string) and a url (string or null).
ProductPromotion
One merchant promotion. ItspromotionId, description, and code fields are strings or null. A merchant may provide only a label in promotionId.
ProductReview
One review with nullableauthor and body strings, rating (number), ratingCount (integer), ratingType (string, such as Rating or AggregateRating), and publishedAt (date-time string).
ProductVideo
One video with nullable string fieldsurl, contentUrl, embedUrl, thumbnailUrl, and name. The API uses contentUrl, then embedUrl, then the merchant’s general URL to populate url.
ProductSpecifications
Structured product details. It containsmaterials, fit, and patterns (arrays of strings) and dimensions (a free-form string or null).
ProductIdentifiers
Merchant productproductId, product-level barcode gtin, and merchant grouping ID productGroupId. Each field is a string or null.
MerchantProvidedAttribute
One merchant-supplied name/value pair inProductDetail.additionalAttributes[]. Each entry requires a name (string) and a value (string or number). A name can repeat when the merchant provides several values.
Enrichment models
ProductEnrichment
StoreRouter-generated data inProductDetail.enrichment. It includes classification fields such as type, gender, age_groups, color, color_family, and category_path. The canonical_brand field carries normalized brand information. Use attributes for taxonomy values by name, attribute_handles for values by handle, and structured_attributes for each attribute’s name, handle, and structured values.
EnrichmentAttribute
One entry inProductEnrichment.structured_attributes[]. It contains a required name (string), a required handle (string), and values (an array of EnrichmentAttributeValue, empty by default).
EnrichmentAttributeValue
One entry inEnrichmentAttribute.values[]. It contains a required display name (string) and a required taxonomy handle (string).
Model name compatibility
The product-model update adds these names to the SDKs and OpenAPI schema. Existing SDK imports and OpenAPI components remain supported. Generated response envelopes still reference the existing component names. Both names use the same JSON fields.SDK types
Import the model names from the SDK package. Python exposes snake_case attributes such asproduct_url and primary_image. TypeScript uses the JSON names, such as productUrl and primaryImage.