channel3-api

Channel3 API Integration Guide

Channel3 is a universal product catalog API. Pick the endpoint(s) that match the developer's input.

Base URL: https://api.trychannel3.com
Auth: x-api-key header (server-side). Browser clients use short-lived client tokens — see references/conversations.md.
Full docs: docs.trychannel3.com (SDK setup, per-endpoint refs, error handling, retries, async usage)
Offline quick reference: references/api-reference.md · Upgrading from SDK 3.x: references/sdk-4-upgrade.md

Anti-patterns (read first)

• Don't use /v1/similar with a free-text query or an image. Similar takes a Channel3 product_id, not a query. If the user describes a product or has an image, that's /v1/search (query and/or image_url).
• Don't reach for /v1/lookup to seed /v1/similar when a /v1/search by title would do. Lookup takes seconds and can fail on uncatalogued URLs. The intended flow is search → grab product.id → similar. Lookup-then-similar can be used if needed but is not an optimal flow for the majority of cases.
• Locale (country / currency) constrains which merchant offers come back. Pan-region storefronts can omit country and just set currency: "EUR". Default is en / US / USD.
• Filters beat query-stuffing, but query-stuffing beats dropping the constraint. Price, brand, category, color, gender, condition, availability, sale, and dimensions all have structured filters — the optimal path to precise results in default/keyword mode. If you can't express a constraint with a filter, put it in query rather than omitting it entirely. Reserve query-only phrasing for what can't be enumerated (aesthetic descriptors, model names, use cases). Agentic mode inverts this: dump the full context into query.

Quick start

npm install @channel3/sdk           # TypeScript
pip install channel3-sdk            # Python

A Go SDK is also available — see docs.trychannel3.com/sdk.

Set CHANNEL3_API_KEY in the environment (free key at trychannel3.com). Then the minimum end-to-end call:

import { Channel3 } from '@channel3/sdk'

SDK 4.0 notes: TypeScript uses a named import (import { Channel3 }), object-style requests (client.products.retrieve({ product_id })), and snake_case request fields matching the wire format. Paginated calls return a Page — .data in TS, .items in Python, async-iterable in both. On SDK 3.x code? See references/sdk-4-upgrade.md.

Locale defaults can be set client-wide via constructor (new Channel3({ country: 'GB', currency: 'GBP' })) or CHANNEL3_LANGUAGE / CHANNEL3_COUNTRY / CHANNEL3_CURRENCY env vars; per-call config.country / config.currency / config.language always wins. For async clients, error classes, retries, timeouts, and logging, see docs.trychannel3.com/sdk.

CLI (terminal & testing)

For ad-hoc API exploration from a terminal — sanity-checking a filter shape, grabbing a product_id to feed into integration tests, or one-off calls without a project — use the Channel3 CLI. It tracks the API spec automatically.

--query-param is the search term; --query is a JMESPath projection over the response. In CLI versions up to 0.4.1 the search term was --query — old commands need updating.

Use the SDK for production code. The CLI is for terminal work.

UI components (React)

Channel3 UI is an open-source (MIT) React component library, distributed as a shadcn registry and typed directly against @channel3/sdk — a Product from a search or product fetch drops straight in.

• Blocks — product-search (search bar + faceted filters + infinite-scroll grid) and product-details (full PDP: gallery, variant selection, offer comparison, price history, recommendations).
• À la carte — components (product-card, variant-selector, offers-list, image-gallery, …) and hooks (useProductSearch, useVariantSelection, useProductRecommendations, …).
• Presentational by design — components take Channel3 data as props and emit intent through callbacks; they never call the API or touch your key. Fetch and shape data on your server (where CHANNEL3_API_KEY lives), then pass results in.
• On SDK major upgrades — re-install from the registry (add --overwrite) rather than hand-fixing component types; see references/sdk-4-upgrade.md.
• Pass full SDK response objects, not trimmed subsets — e.g. PriceHistoryResponse requires canonical_product_id. Across JSON boundaries, Date fields arrive as ISO strings; coerce at the boundary (z.coerce.date()).

Endpoints

Search — POST /v1/search

Text, image, or text+image search. Returns a paginated Page of Product.

Per-call locale override: config: { country: 'GB', currency: 'GBP' }. Full filter shape in references/api-reference.md; full per-endpoint schema at docs.trychannel3.com/api-reference.

Choosing a search mode

Set via config.mode:

• default (lexical + semantic) — right for almost all calls.
• agentic — for rich natural-language briefs you didn't write: an end-user's message, or your agent passing along accumulated context. Put the full context in query and let the LLM planner decompose it into structured sub-searches instead of hand-building filters. Costs multiple seconds. This mode powers Channel3's MCP server, so it gives your own agent loop MCP-grade behavior.
• keyword — lexical-only, lowest latency; incompatible with image input. Niche (ad targeting, real-time); not for normal search.

Structured attribute and color filters

Color constraints use filters.colors, not filters.attributes. Map color words (navy, blue, red, ...) to sRGB hex. filters.attributes is for non-color handles only (material, frame-color, ...).

• colors.palette — products must contain every listed color (AND). hex is sRGB (#rrggbb); percentage (0–1) is an optional minimum share of that color in the product image.
• attributes — Record<string, string[]>. Keys are non-color attribute handles (e.g. material, frame-color); values are OR within a key, AND across keys. Discover valid handles and values for a category via client.categories.retrieve({ slug }) → Category.attributes. Do not pass the color handle here — use filters.colors instead. When a category filter is also supplied, every attribute key must be valid for at least one of those categories.

Don't guess attribute handles or values — categories.retrieve is the source of truth for non-color attributes. Returned products carry structured_attributes (e.g. { color: ["Navy"], material: ["Leather"] }) for display; filter color via filters.colors, not by echoing structured_attributes.color into filters.attributes.

For raw HTTP / non-SDK callers:

Similar — POST /v1/similar

"More like this" from a Channel3 product_id you already have. Almost always seeded from a previous /v1/search response. Returns the same paginated shape; the source product is excluded.

Filters are recommended to keep results in the same slice (gender, brand, category, price). For "more like this, but in navy", use filters.colors (e.g. { hex: '#001f3f' }), not filters.attributes.color. Non-color attributes use filters.attributes. Returns 404 if the product isn't in the catalog yet — fall back to /v1/search by title.

Lookup — POST /v1/lookup

Resolve a merchant URL to the canonical Channel3 Product. Use this only when the developer's only handle on a product is a URL (e.g. a user-pasted link).

Latency: typically 2–10 seconds for uncached URLs (real-time extraction), sub-second for cached. Returns 422 for non-product pages (category listings, search results, homepages) and 504 on timeout. max_staleness_hours (default 3) bounds cache freshness. The response carries the same hydrated variants and structured_attributes as GET /v1/products/{id}. Once you have product.id, use it with client.products.retrieve() or client.products.findSimilar().

Product Details — GET /v1/products/{product_id}

Full Product for a known product_id. Same response shape as search results, but with variants fully hydrated for the current selection — including per-option-value availability and thumbnails. This call is free.

Locale via config (language, country, currency, length_unit, weight_unit); constrain retailers via filters.website_ids (accepts domains, e.g. "nike.com"). Returns 404 when the product has no merchant offer in the requested locale — seed product_id from a /v1/search call run under the same locale, or omit the locale to fall back to default.

Variants and selected_options

A Product with variations carries:

• variants.options — every dimension (e.g. Color, Size) and its values (label, exists, available, optional thumbnail_url and product_id for color-as-product-swap setups).
• variants.selected — the dimensions currently resolved on this response ([{ name: "Color", label: "Navy" }, ...]).
• structured_attributes — extracted attribute values for the resolved variant (e.g. { color: ["Navy"], material: ["Leather"] }).

To re-fetch the product under a different variant configuration, pass selected_options (SDK) or option_<DimensionName>=<Label> query params (HTTP). Multiple dimensions can be combined; case is preserved on the name and matched case-insensitively against the product family.

The server returns the same Product shape with variants.selected updated to reflect the resolved configuration. Diff your requested options against variants.selected to detect server-side relaxation (e.g. the requested size was unavailable in the requested color).

For the full variant model — search-vs-detail differences, product_id navigation (color-as-separate-product), and the exists/available UI tiers — see references/variants.md. In React, the Channel3 UI useVariantSelection hook implements this selection-and-re-resolution loop for you.

Browse — POST /v1/browse

Filter-only product listing — no query or image. Use it to render a brand page, category page, or retailer collection. At least one of brand_ids, category_ids, or website_ids is required (422 otherwise); all other SearchFilters fields work too. Returns the same paginated shape as search.

Conversations — POST /v1/conversations

Turn-based conversational shopping: the developer sends a user message, Channel3 runs the agent (search, compare, refine) and streams back the reply. Browser clients authenticate with short-lived client tokens minted on your server — the API key never ships to the browser.

Full auth model, SSE event reference, and Python examples: references/conversations.md.

Reporting — /v1/reporting/...

Click and transaction attribution for your API key, filterable by the user_id you tagged requests with (see User attribution below).

• GET /v1/reporting/clicks?start_date=&end_date= — offer-link clicks
• GET /v1/reporting/transactions?start_date=&end_date= — attributed sales

Date windows are capped at 90 days per call (default: last 30 days); responses are paginated (page / limit, max 100). Field reference: references/api-reference.md.

Price Tracking — /v0/price-tracking/...

• client.priceTracking.start({ canonical_product_id }) — start tracking
• client.priceTracking.stop({ canonical_product_id }) — stop tracking
• client.priceTracking.retrieveHistory({ canonical_product_id, days }) — default 90 days, max 90; returns current_price, min/max/mean/std_dev, current_status (low / typical / high)
• client.priceTracking.listSubscriptions() — cursor-paginated Page; for await iterates the awaited page (for await (const sub of await client.priceTracking.listSubscriptions()))

Brands and Websites — /v1/brands*, /v0/websites

Lookup helpers, mostly used to obtain IDs for search filters.

• client.brands.search({ query, limit? }) — find brands by name; returns up to limit matches ordered by relevance (default 5, max 20)
• client.brands.retrieve({ brand_id }) — by ID
• client.brands.list() — cursor-paginated Page; for await iterates the awaited page. Iterating to exhaustion walks the entire brand catalog (thousands of brands, many pages of API calls); always break early or use client.brands.search when you just need one brand.
• client.websites.retrieve({ query: 'nike.com' }) — find a retailer

Categories — /v1/categories*

Discover the category slugs you can pass to SearchFilters.category_ids / exclude_category_ids, and the attribute keys/values you can pass to SearchFilters.attributes. Slugs are stable URL-friendly identifiers (e.g. shoes, sofas, handbags) — prefer them over internal IDs. The taxonomy doesn't have a leaf for every conceivable subcategory, and unknown slugs are silently dropped, so always discover real slugs with client.categories.search rather than guessing.

• client.categories.search({ query, limit? }) — free-text → CategorySummary[] (limit 1–20, default 5)
• client.categories.list({ roots_only?, page?, page_size? }) — paginated browse, roots first (page_size 1–100, default 20)
• client.categories.retrieve({ slug }) — full Category with description, attributes, direct children, and root-to-self path

exclude_category_ids excludes the category and all its descendants.

Category.attributes lists indexed attribute handles for SearchFilters.attributes. Use non-color slugs (e.g. material, frame-color). The color entry is informational on products — filter color with filters.colors, not attributes.color.

User attribution

Pass your end-user's ID on any request to attribute their clicks and sales in reporting. Raw HTTP takes the x-user-id header; the Python SDK takes a user_id kwarg (mapped to the header); in TypeScript, pass the header via request options. Channel3 appends it to buy URLs in the response. Max 128 chars; letters, numbers, and . _ @ - only.

Affiliate links

Every ProductOffer.url in a response is an affiliate-tracked link. Surface them as the buy buttons in any UI — sales driven through these URLs earn commission with no additional setup. Use offer.domain to identify the retailer and offer.max_commission_rate to compare earning potential across merchants.

Caching and freshness

• Cache IDs, not data. product.id and category slugs are stable — cache them freely. Treat everything else on a product (prices, availability, offers, images, descriptions, variants) as unstable; it changes as merchants update catalogs.
• Refresh at display time. Before showing a product to a user, refetch with GET /v1/products/{id} (client.products.retrieve) — this call is free and returns current prices, stock, hydrated variant availability, and fresh offer URLs.
• Offer URLs are short-lived. Never cache ProductOffer.url and serve it later; fetch it fresh before presenting the buy link.
• Short TTLs (minutes to a few hours) on presentational fields (title, images) are fine; avoid caching pricing or availability for hours or days.

Locale codes

• Languages: en, de, fr, it, es, nl, sv, fi, pt, cs, el, ro
• Countries: US, GB, EU, AU, CA, IE, DE, AT, FR, BE, IT, ES, NL, SE, FI, PT, CZ, GR, RO
• Currencies: USD, CAD, AUD, GBP, EUR, SEK, CZK, RON
• Length units: mm, cm, m, in, ft · Weight units: mg, g, kg, oz, lb

When country is set alone, the server infers currency (GB → GBP) and language (GB → en). When all three are unset, defaults are en / US / USD. length_unit / weight_unit only control the units dimensions are rendered in — unset returns the merchant's stated unit.

When to use the MCP instead

For no-code agent integration, use the Channel3 MCP instead of writing API code when the host already supports it.

When stuck

• SDK guide (install, async, errors, retries, logging): docs.trychannel3.com/sdk
• Full API reference (try-it examples, schemas): docs.trychannel3.com/api-reference
• Offline quick-card: references/api-reference.md
• Migrating existing code to SDK 4.0: references/sdk-4-upgrade.md
• Support: support@trychannel3.com