Product data models: search items and full views

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 endpoint. Every field present on a list item is also present on a view.

MerchantProductListItem

Returned as elements of the items array in POST /products/search and POST /products/more-like-this responses.

string

required

Stable unique identifier for this product record. Use this to deduplicate items across pages.

string | null

Catalog that supplied this product. Present for search and More Like This results so cross-catalog responses can link back to the correct catalog.

string

required

Canonical product page URL on the merchant’s site. You can pass this directly to POST /products/lookup to retrieve the full view.

string | null

Product title as indexed from the merchant.

object | null

Brand information associated with this product.

Show BrandView properties

string

required

Brand display name.

string | null

URL-safe brand identifier used in brand_slug facet filters.

string | null

URL of the brand’s page on the merchant site.

string | null

Short brand description.

number | null

Current sale or listing price. Used as the basis for price_min and price_max filter comparisons.

number | null

Pre-discount price. null when no markdown or promotion applies.

string | null

Primary product image URL.

string[]

All product image URLs, including the primary image. May be empty if no images are indexed.

object | null

Aggregated customer rating data.

Show RatingView properties

number | null

Average rating value (typically on a 1–5 scale).

integer | null

Total number of individual ratings.

boolean

Whether the product is active in the current index.

integer | null

Optional user-facing match score from 0 to 100, when the search strategy returns one. It is intended for display only.

datetime | null

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/lookup responses. Contains all fields from MerchantProductListItem plus the following additional fields.

string | null

Full product description text as indexed from the merchant.

boolean | null

true if at least one variant is currently available to purchase. null if stock status is not available.

CategoryView[]

Categories the product is assigned to on the merchant site. Each item has name (string, required) and optional url (string).

string[]

Available size labels as strings, e.g. ["xs", "s", "m", "l", "xl"]. Empty array if the product has no size options.

ColorView[]

Available color options for this product.

Show ColorView properties

string

required

Color display label, e.g. "Black".

string | null

Hex color code, e.g. "#000000".

string | null

URL of a swatch image for this color.

string[]

Free-form tags associated with the product, e.g. ["hoodie", "graphic", "streetwear"].

MerchantVariantView[]

Individual SKU-level variants of the product.

Show MerchantVariantView properties

string | null

SKU identifier for this variant.

string | null

URL of this specific variant’s product page, if it differs from the parent.

ColorView | null

Color of this variant. Same shape as the top-level ColorView.

string | null

Size label for this variant.

boolean | null

Whether this specific variant is in stock.

string | null

Image URL specific to this variant.

ProductDetailsView

Structured product attribute details.

Show ProductDetailsView properties

string[]

List of materials, e.g. ["100% cotton"].

string[]

Fit descriptors, e.g. ["oversized", "relaxed"].

string | null

Dimensions or measurements as a free-form string.

string[]

Pattern descriptors, e.g. ["solid", "graphic"].

AudienceView | null

Intended target audience for the product.

Show AudienceView properties

string[]

Target genders. Values: "male", "female", "unisex".

string[]

Target age groups. Values: "infant", "toddler", "kids", "adult".

IdentifiersView

External product identifiers for cross-referencing with other systems.

Show IdentifiersView properties

string | null

Merchant’s internal product ID.

string | null

Global Trade Item Number (barcode / UPC / EAN).

string | null

ID grouping related product variants together on the merchant’s platform.

BreadcrumbView[]

Navigation breadcrumb trail from the merchant’s site. Each item has name (string, required) and optional url (string).

PromotionView[]

Active promotions for this product. Each item has optional description (string) and code (string).

ReviewView[]

Customer reviews. Each item has optional author (string), rating (number), body (string), and publishedAt (datetime).

VideoView[]

Associated product videos. Each item has optional url (string), thumbnailUrl (string), and name (string).

ProductEnrichment | null

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;
}

Catalog API

Voyage API

Coverage API

Data Models

Product data models: search items and full views

MerchantProductListItem

Example — MerchantProductListItem

MerchantProductView

Example — MerchantProductView

SDK types

​MerchantProductListItem

​Example — MerchantProductListItem

​MerchantProductView

​Example — MerchantProductView

​SDK types

MerchantProductListItem

Example — MerchantProductListItem

MerchantProductView

Example — MerchantProductView

SDK types