SDK | Channel3

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" },
});

You can also set defaults via environment variables: CHANNEL3_LANGUAGE, CHANNEL3_COUNTRY, CHANNEL3_CURRENCY. Supported codes follow ISO 639-1 (language), ISO 3166-1 alpha-2 (country), and ISO 4217 (currency).

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:

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();

Search with pagination

Use 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();

Configure search behavior

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.

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, find the closest neighbors in the catalog. Add filters to narrow results.

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();

Available resources

Resource	Description
`products`	Search, image search, similar, lookup, retrieve
`brands`	List, search, and get brand details
`categories`	List, search, and get category details
`priceTracking`	Start/stop tracking, view history and subscriptions
`websites`	Resolve website URLs to IDs and commission rates