The Platform Catalog API uses two product shapes depending on the endpoint. MerchantProductListItem is the compact shape returned in search and More Like This results — it carries the fields needed to render a product card. MerchantProductView extends the list item with full detail fields and is returned only by the POST /products/lookup
MerchantProductListItem Returned as elements of the items array in POST /products/searchPOST /products/more-like-this
Stable unique identifier for this product record. Use this to deduplicate items across pages.
Catalog that supplied this product. Present for search and More Like This results so cross-catalog responses can link back to the correct catalog.
Canonical product page URL on the merchant’s site. You can pass this directly to POST /products/lookup to retrieve the full view.
Product title as indexed from the merchant.
Brand information associated with this product. Show BrandView properties
URL-safe brand identifier used in brand_slug facet filters.
URL of the brand’s page on the merchant site.
Current sale or listing price. Used as the basis for price_min and price_max filter comparisons.
Pre-discount price. null when no markdown or promotion applies.
Primary product image URL.
All product image URLs, including the primary image. May be empty if no images are indexed.
Aggregated customer rating data. Show RatingView properties
Average rating value (typically on a 1–5 scale).
Total number of individual ratings.
Whether the product is active in the current index.
Optional user-facing match score from 0 to 100, when the search strategy returns one. It is intended for display only.
ISO 8601 UTC timestamp of the last update to this product record in the index.
Example — MerchantProductListItem { "uuid" : "prod_01HX..." , "catalogKey" : "warrenlotas" , "productUrl" : "https://warrenlotas.com/products/black-hoodie" , "title" : "Black Hoodie" , "brand" : { "name" : "Warren Lotas" , "slug" : "warren-lotas" , "url" : null , "description" : null }, "currentPrice" : 180 , "originalPrice" : null , "imageUrl" : "https://cdn.example.com/black-hoodie.jpg" , "images" : [ "https://cdn.example.com/black-hoodie.jpg" ], "rating" : null , "isActive" : true , "updatedAt" : "2026-05-19T18:04:10Z" }
MerchantProductView Returned as the product field in POST /products/lookupMerchantProductListItem plus the following additional fields.
Full product description text as indexed from the merchant.
true if at least one variant is currently available to purchase. null if stock status is not available.
Categories the product is assigned to on the merchant site. Each item has name (string, required) and optional url (string).
Available size labels as strings, e.g. ["xs", "s", "m", "l", "xl"]. Empty array if the product has no size options.
Available color options for this product. Show ColorView properties
Color display label, e.g. "Black".
Hex color code, e.g. "#000000".
URL of a swatch image for this color.
Free-form tags associated with the product, e.g. ["hoodie", "graphic", "streetwear"].
Individual SKU-level variants of the product. Show MerchantVariantView properties
SKU identifier for this variant.
URL of this specific variant’s product page, if it differs from the parent.
Color of this variant. Same shape as the top-level ColorView.
Size label for this variant.
Whether this specific variant is in stock.
Image URL specific to this variant.
Structured product attribute details. Show ProductDetailsView properties
List of materials, e.g. ["100% cotton"].
Fit descriptors, e.g. ["oversized", "relaxed"].
Dimensions or measurements as a free-form string.
Pattern descriptors, e.g. ["solid", "graphic"].
Intended target audience for the product. Show AudienceView properties
Target genders. Values: "male", "female", "unisex".
Target age groups. Values: "infant", "toddler", "kids", "adult".
External product identifiers for cross-referencing with other systems. Show IdentifiersView properties
Merchant’s internal product ID.
Global Trade Item Number (barcode / UPC / EAN).
ID grouping related product variants together on the merchant’s platform.
Navigation breadcrumb trail from the merchant’s site. Each item has name (string, required) and optional url (string).
Active promotions for this product. Each item has optional description (string) and code (string).
Customer reviews. Each item has optional author (string), rating (number), body (string), and publishedAt (datetime).
Associated product videos. Each item has optional url (string), thumbnailUrl (string), and name (string).
Octogen-generated enrichment metadata. Includes classification fields like type, gender, age_groups, color, color_family, category_path, and attributes, plus canonical_brand with brand-level intelligence data.
Example — MerchantProductView { "uuid" : "prod_01HX..." , "productUrl" : "https://warrenlotas.com/products/black-hoodie" , "title" : "Black Hoodie" , "brand" : { "name" : "Warren Lotas" , "slug" : "warren-lotas" , "url" : null , "description" : null }, "currentPrice" : 180 , "originalPrice" : null , "imageUrl" : "https://cdn.example.com/black-hoodie.jpg" , "images" : [ "https://cdn.example.com/black-hoodie.jpg" ], "rating" : null , "updatedAt" : "2026-05-19T18:04:10Z" , "description" : "Heavyweight cotton hoodie with screen-printed graphics." , "inStock" : true , "categories" : [{ "name" : "Hoodies & Sweatshirts" , "url" : null }], "sizes" : [ "s" , "m" , "l" , "xl" ], "colors" : [{ "label" : "Black" , "hexCode" : "#000000" , "swatchUrl" : null }], "tags" : [ "hoodie" , "black" , "graphic" ], "variants" : [ { "sku" : "WL-BH-001-M" , "productUrl" : null , "color" : { "label" : "Black" , "hexCode" : "#000000" , "swatchUrl" : null }, "size" : "m" , "inStock" : true , "imageUrl" : null } ], "details" : { "materials" : [ "100% heavyweight cotton" ], "fit" : [ "oversized" ], "dimensions" : null , "patterns" : [ "graphic" ] }, "audience" : { "genders" : [ "male" , "unisex" ], "ageGroups" : [ "adult" ] }, "identifiers" : { "productId" : "WL-BH-001" , "gtin" : null , "productGroupId" : null }, "breadcrumbs" : [ { "name" : "Home" , "url" : "https://warrenlotas.com" }, { "name" : "Tops" , "url" : "https://warrenlotas.com/collections/tops" }, { "name" : "Black Hoodie" , "url" : null } ], "promotions" : [], "reviews" : [], "videos" : [], "enrichment" : null }
SDK types # octogen_ai_sdk.models class MerchantProductListItem ( _ResponseModel ): uuid: str product_url: str # JSON alias: "productUrl" title: str | None brand: BrandView | None current_price: float | None # JSON alias: "currentPrice" original_price: float | None # JSON alias: "originalPrice" image_url: str | None # JSON alias: "imageUrl" images: list[ str ] rating: RatingView | None updated_at: datetime | None # JSON alias: "updatedAt" class MerchantProductView ( MerchantProductListItem ): description: str | None in_stock: bool | None # JSON alias: "inStock" categories: list[CategoryView] sizes: list[ str ] colors: list[ColorView] tags: list[ str ] variants: list[MerchantVariantView] details: ProductDetailsView audience: AudienceView | None identifiers: IdentifiersView breadcrumbs: list[BreadcrumbView] promotions: list[PromotionView] reviews: list[ReviewView] videos: list[VideoView] enrichment: ProductEnrichment | None
// @octogen-ai/sdk: models interface MerchantProductListItem { uuid : string ; productUrl : string ; title ?: string | null ; brand ?: BrandView | null ; currentPrice ?: number | null ; originalPrice ?: number | null ; imageUrl ?: string | null ; images ?: string []; rating ?: RatingView | null ; updatedAt ?: string | null ; } interface MerchantProductView extends MerchantProductListItem { description ?: string | null ; inStock ?: boolean | null ; categories ?: CategoryView []; sizes ?: string []; colors ?: ColorView []; tags ?: string []; variants ?: MerchantVariantView []; details ?: ProductDetailsView ; audience ?: AudienceView | null ; identifiers ?: IdentifiersView ; breadcrumbs ?: BreadcrumbView []; promotions ?: PromotionView []; reviews ?: ReviewView []; videos ?: VideoView []; enrichment ?: ProductEnrichment | null ; }
