Lookup Catalog

lookup_catalog turns ids or URLs into full product records.

catalog.ids - Channel3 product ids (or variant ids)
catalog.urls - links to a product page on a store’s website

Don’t put https://... links in ids. Use urls for those. Examples below use UCP CLI and curl. See quickstart to install the CLI.

By product ID

ucp catalog lookup \
  --input '{"ids":["HvGOfxD","cp_def456"]}' \
  --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": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "ids": ["HvGOfxD", "cp_def456"]
        }
      }
    }
  }'

You get one product per ID when we have it. Missing ids show up in messages but won’t fail the whole request.

By product URL

ucp catalog lookup \
  --input '{"urls":["https://merchant.example.com/products/some-shoe"]}' \
  --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": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "urls": [
            "https://merchant.example.com/products/some-shoe"
          ]
        }
      }
    }
  }'

We match the URL to our index and return the product with every store’s offer as a separate entry in variants[] (same as POST /v1/lookup). Multiple sellers for one product means multiple variants — see Extension reference. For interactive variant selection (selected, preferences), use get_product instead.

If you put a URL in catalog.ids, you’ll get a message telling you to use catalog.urls instead.

Both at once

You can send ids and urls in one request if your agent has a mix.

ucp catalog lookup \
  --input '{"ids":["HvGOfxD"],"urls":["https://merchant.example.com/products/some-shoe"]}' \
  --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": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "ids": ["HvGOfxD"],
          "urls": ["https://merchant.example.com/products/some-shoe"]
        }
      }
    }
  }'

What’s next

Get one product

When you only need a single ID

⌘I

Getting Started

Make a Search

Get Product Data

Checkout

Pricing, Reporting, and Commissions

Build

Integrate

FAQ

By product ID

By product URL

Both at once

What’s next

Get one product

​By product ID

​By product URL

​Both at once

​What’s next

Get one product

By product ID

By product URL

Both at once

What’s next