Batch Product Lookup

Look up multiple products in a single request. Useful for validating a list of products before syncing inventory.

POST/products/lookup/batch

Look up multiple products by their external IDs. Returns results for all lookups, including those not found.

On larger screens, use the API Playground panel on the right to try this endpoint.

Name	Type	Required	Description
`lookups`	array	Required	Array of lookup objects with source and externalId

bash

curl -X POST "https://api.ctcgx.com/api/v1/products/lookup/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lookups": [
    { "source": "tcgplayer", "externalId": "12345" },
    { "source": "scryfall", "externalId": "abc-123-def" },
    { "source": "tcgplayer", "externalId": "99999" }
  ]
}'

Response

Returns results for each lookup with a summary of found/not found counts.

json

{
  "results": [
    {
      "source": "tcgplayer",
      "externalId": "12345",
      "found": true,
      "product": {
        "id": "clxxx...",
        "name": "Black Lotus",
        "setName": "Alpha",
        "gameType": "magic"
      }
    },
    {
      "source": "scryfall",
      "externalId": "abc-123-def",
      "found": true,
      "product": {
        "id": "clyyy...",
        "name": "Ancestral Recall",
        "setName": "Alpha",
        "gameType": "magic"
      }
    },
    {
      "source": "tcgplayer",
      "externalId": "99999",
      "found": false,
      "product": null
    }
  ],
  "summary": {
    "total": 3,
    "found": 2,
    "notFound": 1
  }
}

Use Cases

Batch lookup is ideal for:

Pre-validation - Check which products exist before running a full inventory sync
Product matching - Map your catalog to CTCGX products in bulk
Missing product reports - Identify which products need to be added to CTCGX

Limits

Batch lookups are limited to 100 products per request. For larger catalogs, split your lookups into multiple requests.

Mixed Sources

You can mix different sources in a single batch request:

{
  "lookups": [
    { "source": "tcgplayer", "externalId": "12345" },
    { "source": "scryfall", "externalId": "abc-123-def" },
    { "source": "pokemontcg", "externalId": "swsh1-1" }
  ]
}