Skip to main content
Color filtering is currently in Beta. The API surface may change.
The colors filter on POST /v1/search accepts one or more hex color values and returns products whose dominant colors match the palette. This is useful for building color-matched shopping experiences — for example, finding furniture or clothing that complements a specific color scheme.

​
Basic color filter

Pass an array of { hex, percentage? } objects. The percentage field is optional and indicates the desired proportion of that color in the product image. 
import Channel3 from "@channel3/sdk";

const client = new Channel3();

const results = await client.products.search({
  query: "sofa",
  filters: {
    colors: [{ hex: "#5D3FD3" }],
  },
});

from channel3_sdk import Channel3

client = Channel3()

results = client.products.search(
    query="sofa",
    filters={
        "colors": [{"hex": "#5D3FD3"}],
    },
)

curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sofa",
    "filters": { "colors": [{ "hex": "#5D3FD3" }] }
  }'

​
Multiple colors

Provide a palette of colors to find products that match the combination. 
const results = await client.products.search({
  query: "throw pillow",
  filters: {
    colors: [{ hex: "#1A1A2E" }, { hex: "#E2B96F" }],
  },
});

results = client.products.search(
    query="throw pillow",
    filters={
        "colors": [
            {"hex": "#1A1A2E"},
            {"hex": "#E2B96F"},
        ],
    },
)

​
With percentage hints

Use percentage to signal how dominant each color should be in the product. Values are relative weights, not strict percentages.
TypeScript
const results = await client.products.search({
  query: "area rug",
  filters: {
    colors: [
      { hex: "#8B4513", percentage: 60 },
      { hex: "#F5DEB3", percentage: 40 },
    ],
  },
});