Search the Catalog

search_catalog finds products across stores from a text query. Optional: API key via --header or profile headers.json for Token tier (limits, monetizable links, placements). Without a key, the CLI runs as Anonymous.

Basic search

ucp catalog search \
  --set /query='wireless headphones under $100' \
  --set '/pagination/limit=10' \
  --format json

curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "query": "wireless headphones under $100",
          "pagination": { "limit": 10 }
        }
      }
    }
  }'

In the MCP response, open structuredContent (curl stream) or result (CLI):

products - matches with price, variants, and store info
pagination.has_next_page - more results available?
pagination.cursor - send this back for the next page

ucp catalog search \
  --set /query='running shoes' \
  --set '/pagination/limit=10' \
  --set '/pagination/cursor=<paste cursor from last response>' \
  --format json

curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "query": "running shoes",
          "pagination": {
            "limit": 10,
            "cursor": "<paste cursor from last response>"
          }
        }
      }
    }
  }'

Filter by store (Channel3 extension)

Limit results to specific merchants:

ucp catalog search \
  --input '{
    "query": "trail running shoes",
    "pagination": { "limit": 10 },
    "filters": {
      "website_ids": ["lGBj", "nike.com"]
    }
  }' \
  --format json

curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "query": "trail running shoes",
          "pagination": { "limit": 10 },
          "filters": {
            "website_ids": ["lGBj", "nike.com"]
          }
        }
      }
    }
  }'

website_ids can be merchant ids or domains. Same as REST website_ids / shop_ids. More filters: Extension reference.

Placement commission data (Token tier)

Opt in with catalog.placements: ["affiliate"] and a valid API key. Matching variants include placement with commission percentage. Omit placements (or pass []) and responses are unchanged.

ucp catalog search \
  --header "x-api-key: $CHANNEL3_API_KEY" \
  --set /query='trail running shoes' \
  --set '/pagination/limit=10' \
  --set '/placements=["affiliate"]' \
  --format json

curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "query": "trail running shoes",
          "pagination": { "limit": 10 },
          "placements": ["affiliate"]
        }
      }
    }
  }'

See Extension reference for response shape.

Fields worth saving

Field	Why
`products[].id`	Product id for lookup or get_product
`products[].variants[]`	Per-store listings (SKUs, prices, seller)
`products[].variants[].seller.domain`	Which store
`messages[]`	Warnings (empty query, bad filter, etc.)

Variant options (Color, Size, …) are returned by get_product, not by search.

Getting Started

Make a Search

Get Product Data

Checkout

Pricing, Reporting, and Commissions

Build

Integrate

FAQ

Search the Catalog

Basic search

Next page

Filter by store (Channel3 extension)

Placement commission data (Token tier)

Fields worth saving

What’s next

Lookup

Get product

​Basic search

​Next page

​Filter by store (Channel3 extension)

​Placement commission data (Token tier)

​Fields worth saving

​What’s next

Lookup

Get product

Basic search

Next page

Filter by store (Channel3 extension)

Placement commission data (Token tier)

Fields worth saving

What’s next