Product Lookup

Find a CTCGX product using an external ID from TCGPlayer, Scryfall, or other supported sources.

GET/products/lookup

Product Lookup

Look up a single product by its external ID from a supported source.

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

Name	Type	Required	Description
`source`	stringtcgplayer \| scryfall \| cardmarket \| cardtrader \| ygoprodeck \| pokemontcg	Required	The external ID source
`externalId`	string	Required	The external ID value

bash

curl "https://api.ctcgx.com/api/v1/products/lookup" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns the matching product with full details including all known external IDs.

json

{
  "found": true,
  "product": {
    "id": "clxxx...",
    "name": "Black Lotus",
    "productSlug": "black-lotus-12345",
    "setName": "Alpha",
    "gameSlug": "magic-the-gathering",
    "cardNumber": "232",
    "rarity": "Rare",
    "imageUrl": "https://...",
    "externalIds": [
      { "source": "tcgplayer", "externalId": "12345" },
      { "source": "scryfall", "externalId": "abc-123-def" }
    ],
    "variants": {
      "finishes": ["nonfoil", "foil"],
      "editions": ["Unlimited"],
      "languages": ["English", "Japanese", "German"]
    }
  }
}

Examples

# Look up by TCGPlayer ID
GET /products/lookup?source=tcgplayer&externalId=12345

# Look up by Scryfall ID
GET /products/lookup?source=scryfall&externalId=abc-123-def

# Look up by Pokemon TCG API ID
GET /products/lookup?source=pokemontcg&externalId=swsh1-1

Available Variants

The response includes a variants object showing what options are available for this card:

finishes - Available finishes (nonfoil, foil, etched, reverse-holo, etc.)
editions - Available editions (1st Edition, Unlimited, Shadowless, etc.)
languages - Available language printings

Use this information to know what variant combinations you can create listings for. When syncing inventory, specify these variant fields to create separate listings.

Product Not Found

If no matching product is found, the API returns a 404 error:

{
  "error": "not_found",
  "message": "Product not found for source 'tcgplayer' with ID '99999'"
}

This can happen if:

The product doesn't exist in the CTCGX database
We don't have a mapping for that external ID
The external ID format is incorrect