Documentation Index
Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
Use this file to discover all available pages before exploring further.
Installation
// npm
npm install @channel3/sdk
// yarn
yarn add @channel3/sdk
// pnpm
pnpm add @channel3/sdk
Authentication
You can provide your API key using the CHANNEL3_API_KEY environment variable, or by passing it directly to the client.
import Channel3 from "@channel3/sdk";
// Initialize with environment variable
const client = new Channel3();
// Or, initialize with API key directly
const clientWithKey = new Channel3({
apiKey: "your_api_key_here",
});
Default locale
Set a default locale once on the client and it’ll apply to every search and product detail call. Per-call values (e.g. config.country on search, ?country= on product detail) override the client default.
import Channel3 from "@channel3/sdk";
const client = new Channel3({
country: "GB",
currency: "GBP",
});
// Uses GB / GBP
await client.products.search({ query: "raincoat" });
// Override per-call (returns DE / EUR offers regardless of the client default)
await client.products.search({
query: "raincoat",
config: { country: "DE", currency: "EUR" },
});
CHANNEL3_LANGUAGE, CHANNEL3_COUNTRY, CHANNEL3_CURRENCY. Supported codes follow ISO 639-1 (language), ISO 3166-1 alpha-2 (country), and ISO 4217 (currency) for available locales.
When only country is set, the server infers currency (e.g. GB → GBP) and language (e.g. GB → en). When all three are unset, defaults to en / US / USD.
Usage
All top-level endpoints are available as properties on the client. For example, to use the search endpoint:
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.search({
query: "organic cotton t-shirt",
});
console.log(response);
}
main();
Async Usage
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.search({
query: "organic cotton t-shirt",
});
console.log(response);
}
main();
Advanced Usage
Search with filters
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.search({
query: "running shoes",
filters: {
brand_ids: [brand_id1, brand_id2],
gender: "unisex",
price: { min_price: 50.0, max_price: 150.0 },
availability: ["InStock", "LimitedAvailability"],
},
limit: 20,
});
console.log(response);
}
main();
next_page_token from the response to fetch the next page of results.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const page1 = await client.products.search({
query: "running shoes",
});
console.log("Page 1:", page1.products.length, "products");
if (page1.next_page_token) {
const page2 = await client.products.search({
query: "running shoes",
page_token: page1.next_page_token,
});
console.log("Page 2:", page2.products.length, "products");
}
}
main();
Search with an image URL
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.search({
image_url: "https://example.com/images/shoe.jpg",
});
console.log(response);
}
main();
Search with a base64 image
import fs from "node:fs";
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const b64 = fs.readFileSync("shoe.jpg").toString("base64");
const response = await client.products.search({
base64_image: b64,
});
console.log(response);
}
main();
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.search({
query: "linen shirt",
config: {
keyword_search_only: true,
},
});
console.log(response);
}
main();
Look up a product by URL
Pass any supported product page URL to products.lookup and get back the canonical Product from Channel3’s catalog. The returned product.id works with products.retrieve afterward.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.lookup({
url: "https://brand.com/products/linen-shirt",
});
console.log(response.product);
}
main();
Find similar products
Given a canonical product_id, products.find_similar returns the closest neighbors in the catalog using the source product’s stored embedding. Add filters to narrow results to the same gender, brand, category, or price range.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.products.find_similar({
product_id: "2yh8WH5",
filters: {
gender: "female",
price: { max_price: 200 },
},
limit: 10,
});
console.log(response.products);
}
main();
Find brands by name
Search the brand catalog by free-text query. Returns brands ordered by relevance.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.brands.search({ query: "lululemon" });
console.log(response.brands);
}
main();
Browse the brand catalog
Cursor-paginated. Pass next_cursor from the response back as cursor to fetch the next page.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const page1 = await client.brands.list({ limit: 50 });
console.log("Page 1:", page1.items.map(b => b.name));
if (page1.next_cursor) {
const page2 = await client.brands.list({
limit: 50,
cursor: page1.next_cursor,
});
console.log("Page 2:", page2.items.map(b => b.name));
}
}
main();
Find categories
Search the category taxonomy by free-text query. Use the returned slug values with the category_ids filter on products.search, or pass one to categories.retrieve for full details.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
const response = await client.categories.search({ query: "sofas" });
console.log(response.categories.map(c => c.slug));
}
main();
client.categories.list({ page, page_size, roots_only }) returns a page-numbered listing, and client.categories.retrieve(slug) returns one category with its children, attributes, and full path.
Error Handling
When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), an error will be thrown.
import Channel3 from "@channel3/sdk";
const client = new Channel3();
async function main() {
try {
await client.products.search();
} catch (err) {
if (err instanceof Channel3.APIError) {
console.log(err.status); // 400
console.log(err.name); // BadRequestError
console.log(err.headers); // {server: 'nginx', ...}
} else {
throw err;
}
}
}
main();
Error types are exposed via each SDK’s error module.
