---
title: "Lookup Product"
method: POST
path: "/v1/lookup"
tags: ["v1"]
---

# Lookup Product

`POST /v1/lookup`

## Request

- Base URL: `https://api.trychannel3.com`
- URL: `https://api.trychannel3.com/v1/lookup`
- Auth: API key in header `x-api-key`

Retrieve product information for any product URL.

Returns the same Product model as GET /v1/products/{product_id}.
The product_id in the response can be used with the Product Detail endpoint.
Products from merchants outside the Channel3 catalog resolve for display
purposes, but are not available to other endpoints (e.g. /v1/similar,
price tracking).

## Headers

- `x-user-id` string, nullable: Optional user identifier to attribute clicks and sales to a user in your system. Channel3 appends it to buy URLs in the response.

## Request body

- LookupRequest
  - `url` string, required: The URL of the product to look up
  - `max_staleness_hours` integer: Maximum age (in hours) of cached product data before forcing a fresh lookup. Defaults to 3 hours.
  - `realtime_fetch` boolean: Fetch the product page live when the URL is not in the Channel3 catalog or its data is older than max_staleness_hours. When false, only catalog products are returned: stale data is returned as-is, and URLs not in the catalog return 404.

## Response `200`

Successful Response

- LookupResponse: Response from the /v1/lookup endpoint.
  - `product` Product, required: Product with detailed information.
    - `id` string, required
    - `title` string, required
    - `description` string, nullable
    - `brands` ProductBrand[]: Ordered list of brands.
      - `id` string, required
      - `name` string, required
    - `images` ProductImage[]
      - `url` string, required
      - `cleaned_url` string, nullable: Background-removed square image on Channel3 CDN when available. Use for product grids; ``url`` is the regular hosted shot.
      - `is_main_image` boolean
      - `shot_type` 'hero' | 'lifestyle' | 'on_model' | 'detail' | 'scale_reference' | 'angle_view' | 'flat_lay' | 'in_use' | 'packaging' | 'size_chart' | 'product_information' | 'merchant_information': Product image type classification for API responses.
      - `alt_text` string, nullable
    - `category` CategorySummary: Lean category representation used in search hits and list rows.
      - `slug` string, required: URL-friendly slug (e.g. 'sofas')
      - `title` string, required: Human-readable category title
      - `path` CategoryRef[]: Hierarchical path as a structured list, root first; the last entry is this category itself
        - `slug` string, required: URL-friendly slug (e.g. 'sofas')
        - `title` string, required: Human-readable category title
      - `has_children` boolean, required: Whether this category has subcategories
    - `gender` 'male' | 'female': Product gender. 'unisex' is deprecated: coerced to None on input, never emitted.
    - `age` 'newborn' | 'infant' | 'toddler' | 'kids' | 'adult'
    - `materials` string[], nullable
    - `key_features` string[], nullable
    - `colors` ProductColor[]: Colors of the cleaned main product image, ordered by pixel share (descending). Empty when the product has no cleaned image palette.
      - `hex` string, required: sRGB hex string, e.g. '#a1b2c3'
      - `percentage` number, required: Fraction of foreground pixels in [0, 1]; 1.0 is 100%.
    - `offers` ProductOffer[]: All merchant offers for this product in the requested locale.
      - `url` string, required
      - `domain` string, required
      - `price` Price, required
        - `price` number, required: The current price of the product, including any discounts.
        - `compare_at_price` number, nullable: The original price of the product before any discounts.
        - `currency` string, required: The currency code of the product, like USD, EUR, GBP, etc.
      - `availability` 'InStock' | 'OutOfStock', required: The two availability values the public API emits on offers. Internal ``AvailabilityStatus`` values are collapsed to these via ``AvailabilityStatus.to_api()``.
      - `condition` 'new' | 'used': Offer condition. 'refurbished' is deprecated: rejected as a filter value, coerced to None on responses.
      - `max_commission_rate` number: The maximum commission rate for the merchant, as a decimal fraction: 0 is no commission, 0.5 is 50% commission. 'Max' because the actual commission rate may be lower due to vendor-specific affiliate rules.
      - `dimensions` Dimensions: Physical dimensions of a product offer. Members are null when unknown. Values are standardized to the supported unit set; a merchant-stated value whose unit is not one of those units is omitted rather than shown.
        - `length` LengthDimension: A length measurement, in one of the supported length units.
          - `number` number, required
          - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
        - `width` LengthDimension: A length measurement, in one of the supported length units.
          - `number` number, required
          - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
        - `height` LengthDimension: A length measurement, in one of the supported length units.
          - `number` number, required
          - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
        - `weight` WeightDimension: A weight measurement, in one of the supported weight units.
          - `number` number, required
          - `unit` 'mg' | 'g' | 'kg' | 'oz' | 'lb', required
    - `variants` Variants: Wrapper for variant-interaction state on a Product. Holds `options` and `selected`. `options` represent all of the configuration options for the product. `selected` represents the currently selected option values.
      - `options` VariantOption[], required
        - `name` string, required: The name of the option (e.g. 'Color', 'Size')
        - `values` OptionValue[], required: The values of the option (e.g. ['Blue', 'Red', 'Green'])
          - `label` string, required: The display value of the option value (e.g. 'Blue')
          - `exists` boolean, required: Whether the option value exists on the product, or is a configuration only present on another variant of the same product. For example, a shirt that comes in multiple colors, but only one color is available in Size XL.
          - `available` 'InStock' | 'OutOfStock': The two availability values the public API emits on offers. Internal ``AvailabilityStatus`` values are collapsed to these via ``AvailabilityStatus.to_api()``.
          - `thumbnail_url` string, nullable: For options that reference different products, this is the URL of the thumbnail image for the option value. E.g., a shoe that comes in multiple colors will have an OptionValue for each color with a thumbnail_url set.
          - `product_id` string, nullable: The product id that represents this value. Variants that point to different products will have this field set, as well as thumbnail_url for displaying selector icons.
      - `selected` SelectedOption[], required
        - `name` string, required: The name of the selected option (e.g. 'Color', 'Size')
        - `label` string, required: The display value of the selected option (e.g. 'Blue', 'XL')
    - `structured_attributes` object: Structured attributes extracted for this product, keyed by attribute handle (e.g. 'color', 'material'). Values are the canonical allowed values for that handle.
    - `ratings` ProductRatings: Count-weighted rating rollup across merchants that sell this product.
      - `value` number, required: Average on a 0–5 scale, weighted by each merchant's review count.
      - `count` integer, required: Total review count after collapsing identical merchant pools.
      - `source_count` integer, required: Distinct merchant rating pools that contributed.

## Other responses

- `401`: Unauthorized - Invalid or missing authentication
- `402`: Payment required
- `404`: Product not found
- `422`: URL is not a product page (e.g. category listing, search results, homepage) or is on an explicitly disallowed domain
- `500`: Unable to extract product data from the given URL
- `504`: Timeout

## Changes

- **2026-10-16** `1ae48413f6a7`: 1 info
  - added the new optional request property `realtime_fetch`
- **2026-10-16** `93329818bdf4`: 2 warning, 9 info
  - removed the optional property `product/categories` from the response with the `200` status
  - removed the optional property `product/images/items/is_cleaned_image` from the response with the `200` status
  - added the new optional `header` request parameter `x-user-id`
  - added the optional property `product/colors` to the response with the `200` status
  - …7 more
- **2026-07-29** `1200b0ff4724`: 1 info
  - response property `product/images/items/is_cleaned_image` deprecated
- **2026-07-29** `e235d378571b`: 1 info
  - added the optional property `product/images/items/cleaned_url` to the response with the `200` status
- **2026-07-09** `cd7de4a95828`: 1 info
  - added the optional property `product/offers/items/dimensions` to the response with the `200` status

[Operation history](https://skmtc.dev/channel3-ai/apis/channel3-typescript-api/changes/v1/lookup/post.md)

---

[API](https://skmtc.dev/channel3-ai/apis/channel3-typescript-api.md) - [All operations](https://skmtc.dev/channel3-ai/apis/channel3-typescript-api/llms.txt) - [OpenAPI document](https://skmtc.dev/channel3-ai/apis/channel3-typescript-api/revisions/f9f7b422ab5d?raw)