Skip to main content
Use 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 in items[]. 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.
The search response includes the group and its look links. This excerpt focuses on the option fields.
Match {"color":"Black","fit":"Tall"} against the complete selection in the second row. Pass its productUuid unchanged to retrieve that look.
The retrieve response identifies the same look and confirms its fixed selection. Read product.variants for the purchasable units within it.

ProductDetail

Find the detail in product 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 in ProductDetail.variants[]. All fields can be null when the merchant supplies no value.

ProductImage

Both primaryImage and each entry in images[] use this shape.

Supporting models

ProductBrand

Brand displayed on a product. It contains a required name (string) and nullable string fields slug, url, and description. Use slug with the brand_slug facet.

ProductRatingSummary

Product-level rating with average (number or null) and count (integer or null).

ProductColor

Color data in ProductDetail.colors[] and ProductVariant.color. It contains a required label (string), plus hexCode and swatchUrl (strings or null).

ProductCategory

One entry in ProductDetail.categories[]. It contains a required category name (string) and a merchant category url (string or null).

ProductAudience

Target audience represented by genders and ageGroups (arrays of strings). Both default to empty arrays.

ProductBreadcrumb

One entry in the merchant’s navigation trail. It contains a required name (string) and a url (string or null).

ProductPromotion

One merchant promotion. Its promotionId, description, and code fields are strings or null. A merchant may provide only a label in promotionId.

ProductReview

One review with nullable author 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 fields url, 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 contains materials, fit, and patterns (arrays of strings) and dimensions (a free-form string or null).

ProductIdentifiers

Merchant product productId, product-level barcode gtin, and merchant grouping ID productGroupId. Each field is a string or null.

MerchantProvidedAttribute

One merchant-supplied name/value pair in ProductDetail.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 in ProductDetail.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 in ProductEnrichment.structured_attributes[]. It contains a required name (string), a required handle (string), and values (an array of EnrichmentAttributeValue, empty by default).

EnrichmentAttributeValue

One entry in EnrichmentAttribute.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 as product_url and primary_image. TypeScript uses the JSON names, such as productUrl and primaryImage.
See the Python SDK and TypeScript SDK guides.