---
title: "Browse"
method: POST
path: "/v1/browse"
tags: ["v1"]
---

# Browse

`POST /v1/browse`

## Request

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

List and page through products for a set of filters.

Useful for a static, grid view of products for a brand, website, or category.

At least one of `filters.brand_ids`, `filters.category_ids`, or
`filters.website_ids` must be provided, unless `config.collection_id` is set.

Pagination is capped at 5 pages per browse; `next_page_token` is null on
the final page. Contact support@trychannel3.com for deeper paging.

## 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

- BrowseRequest: Filter-driven product listing with pagination (no free-text query).
  - `filters` SearchFilters: Search filters for the search API.
    - `brand_ids` string[], nullable: If provided, only products from these brands will be returned
    - `gender` 'male' | 'female': Product gender. 'unisex' is deprecated: coerced to None on input, never emitted.
    - `conditions` Condition[]: Offer conditions to match (OR). Defaults to ['new'], which also matches offers whose condition is unknown. Pass every value to disable condition filtering.
    - `age` Age[], nullable: Filter by age group. Age-agnostic products are treated as adult products.
    - `price` SearchFilterPrice: Price filter for search. Values are inclusive.
      - `min_price` number, nullable: Minimum price, in dollars and cents
      - `max_price` number, nullable: Maximum price, in dollars and cents
    - `availability` OfferAvailabilityStatus[]: Offer availability statuses to match (OR). Defaults to ['InStock']. An offer with no availability data counts as 'InStock'. Pass every value to disable availability filtering.
    - `sale` 'on_sale'
    - `website_ids` string[], nullable: If provided, only products from these websites will be returned. Accepts website IDs or domains (e.g. "nike.com").
    - `category_ids` string[], nullable: If provided, only products from these categories will be returned. Accepts category slugs. Categories that do not exist, or that are not available for search, are rejected with a 422.
    - `exclude_brand_ids` string[], nullable: If provided, products from these brands will be excluded from the results
    - `exclude_website_ids` string[], nullable: If provided, products from these websites will be excluded from the results. Accepts website IDs or domains (e.g. "nike.com").
    - `exclude_category_ids` string[], nullable: If provided, products in these categories (or their descendants) will be excluded from the results. Accepts category slugs. Categories that do not exist are rejected with a 422.
    - `colors` SearchColorsFilter: [Beta] Color filter wrapper. Holds required colors and optional match mode.
      - `palette` SearchFilterColor[], required: Colors required in matching products. Treated as an AND condition.
        - `hex` string, required: sRGB hex string, e.g. '#a1b2c3'
        - `percentage` number, nullable: Percentage of color, where 1.0 is 100%
      - `match` 'strict' | 'standard' | 'loose': How tightly a product's colors must match the requested palette.
    - `attributes` object, nullable: If provided, only products matching these key/value constraints will be returned. Keys are attribute handles (e.g. 'color', 'material') and values are lists of allowed values (OR within a key, AND across keys). When a category filter is also supplied, all keys must be valid attributes of at least one of the requested categories. See `Category.attributes` for the valid keys and values per category.
    - `dimensions` SearchFilterDimensions: Physical-dimension range filters, matched against the same offer. Matching products have at least one offer satisfying every provided range (alongside any locale/price/availability filters). Values are compared with a small relative tolerance. An offer with no dimension data for a filtered field does not match; note that when a single merchant on a product reports a dimension it is shared across that product's offers, so a matching offer may not itself surface that dimension in the response.
      - `length` SearchFilterLengthDimension
        - `min` number, nullable: Minimum value, in `unit`. Inclusive.
        - `max` number, nullable: Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `width` SearchFilterLengthDimension
        - `min` number, nullable: Minimum value, in `unit`. Inclusive.
        - `max` number, nullable: Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `height` SearchFilterLengthDimension
        - `min` number, nullable: Minimum value, in `unit`. Inclusive.
        - `max` number, nullable: Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `weight` SearchFilterWeightDimension
        - `min` number, nullable: Minimum value, in `unit`. Inclusive.
        - `max` number, nullable: Maximum value, in `unit`. Inclusive.
        - `unit` 'mg' | 'g' | 'kg' | 'oz' | 'lb', required
  - `limit` integer, nullable: Optional limit on the number of results. Default is 20, max is 30.
  - `page_token` string, nullable: Opaque token from a previous browse response to fetch the next page. Browsing is limited to 5 pages; `next_page_token` is null on the final page.
  - `config` BaseConfig: Shared request config: locale, optional collection scope, and optional real-time offer refresh.
    - `language` 'en' | 'de' | 'fr' | 'it' | 'es' | 'nl' | 'sv' | 'fi' | 'pt' | 'cs' | 'el' | 'ro' | 'pl': ISO 639-1 language code.
    - `country` 'US' | 'GB' | 'EU' | 'AU' | 'CA' | 'IE' | 'DE' | 'AT' | 'FR' | 'BE' | 'IT' | 'ES' | 'NL' | 'SE' | 'FI' | 'PT' | 'CZ' | 'GR' | 'RO' | 'CH' | 'PL': ISO 3166-1 alpha-2 country code (plus the pan-region ``EU``).
    - `currency` 'USD' | 'CAD' | 'AUD' | 'GBP' | 'EUR' | 'SEK' | 'CZK' | 'RON' | 'CHF' | 'PLN': ISO 4217 currency code.
    - `length_unit` 'mm' | 'cm' | 'm' | 'in' | 'ft'
    - `weight_unit` 'mg' | 'g' | 'kg' | 'oz' | 'lb'
    - `collection_id` string, nullable: Optional saved collection to scope this request. Clauses are ORed. Within a clause, brand/website/category lists are ORed inside each list and ANDed across lists. Request filters further narrow results but cannot widen the collection scope.
    - `offer_refresh_timeout_ms` integer, nullable: Check each returned offer against the merchant's live site, waiting up to this many milliseconds (2000-10000). Offers whose page or variant is gone are dropped and offers found out of stock are returned as out of stock. Adds up to this much latency.

## Response `200`

Successful Response

- SearchResponse: v1 paginated search response.
  - `products` Product[], required
    - `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.
  - `next_page_token` string, nullable: Token to fetch the next page. Null when no more results.

## Other responses

- `401`: Unauthorized - Invalid or missing authentication
- `402`: Payment required
- `422`: Validation error — at least one of 'filters.brand_ids', 'filters.category_ids', or 'filters.website_ids' must be provided, unless 'config.collection_id' is set; or the page token is past page 5.
- `500`: Internal Server Error

## Changes

- **2026-10-23** `7aededb0a617`: 1 info
  - added the new optional request property `config/offer_refresh_timeout_ms`
- **2026-10-20** `f642382eaf91`: 3 info
  - added the new `PL` enum value to the request property `config/country/anyOf[subschema #1: CountryCode]/`
  - added the new `PLN` enum value to the request property `config/currency/anyOf[subschema #1: CurrencyCode]/`
  - added the new `pl` enum value to the request property `config/language/anyOf[subschema #1: LanguageCode]/`
- **2026-10-19** `7d1e0ccffc95`: 2 info
  - added the new `CH` enum value to the request property `config/country/anyOf[subschema #1: CountryCode]/`
  - added the new `CHF` enum value to the request property `config/currency/anyOf[subschema #1: CurrencyCode]/`
- **2026-10-16** `93329818bdf4`: 3 breaking, 3 warning, 14 info
  - removed `subschema #1` from the `filters/sale` request property `anyOf` list
  - request property `filters/availability` list-of-types was narrowed by removing types `null` from media type `application/json`
  - the `filters/availability` request property's minItems was increased to `1`
  - removed the request property `filters/condition`
  - …16 more
- **2026-07-29** `1200b0ff4724`: 1 info
  - response property `products/items/images/items/is_cleaned_image` deprecated

[Operation history](https://skmtc.dev/channel3-ai/apis/channel3-typescript-api/changes/v1/browse/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)