Identifiers

Sets and cards can be addressed two ways: a canonical id that always resolves to exactly one record, or a shorter, friendlier id that's easier to hardcode but can occasionally be ambiguous. Sealed products only have one id: their slug.

Sets

A set's canonical id is its tcg_api_id (e.g. sv1). Most sets also have a shortcut, a lowercase community-style code (the same value TCGplayer/ptcgo use) that you can pass anywhere a set identifier is expected, matched case-insensitively. A shortcut can be reused across languages or regions (for example, the same pop shortcut exists for both an English and a Japanese set), in which case pass ?language= and/or ?region= to narrow it down, or use the canonical id directly.

Cards

A card's canonical id is its tcg_api_id (e.g. pbl-63). Its friendly id is {shortcut}_{number} (the card's set shortcut, an underscore, then the card number, lowercased). Card pbl-63 (number 63 in the set with shortcut pbl) has friendly id pbl_63. Only the first underscore splits shortcut from number, because card numbers can themselves contain an underscore (e.g. number 15_A1 gives friendly id neo_15_a1 for a card in the set with shortcut neo, and still resolves correctly). A set shortcut must not contain an underscore, since that would be split incorrectly.

curl "https://tcgplein.nl/api/v1/cards/pbl_63" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE"

{
  "data": {
    "id": "pbl-63",
    "friendly_id": "pbl_63",
    "name": "Pikachu",
    "number": "63"
  }
}

Every card response includes both fields: id (canonical, always present) and friendly_id (null when the card's set has no shortcut). Use whichever suits your integration. The canonical id never changes; the friendly id is easier to read and write by hand.

Ambiguous identifiers

A friendly id (set shortcut, or a card's {shortcut}_{number}) must be unambiguous. If it matches more than one record (most commonly the same shortcut reused across languages, like the English and Japanese pop sets both having a card numbered 1), the API responds 409 with error.type set to ambiguous_identifier and a list of candidates:

curl "https://tcgplein.nl/api/v1/cards/pop_1" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE"

{
  "error": {
    "type": "ambiguous_identifier",
    "message": "Card identifier 'pop_1' matches multiple cards. Use the canonical id, or narrow with ?language= or ?region=.",
    "fields": {
      "candidates": [
        { "id": "pop1-1", "name": "Pikachu", "number": "1", "set": "POP Series 1", "language": "EN", "region": "en" },
        { "id": "popjp-1", "name": "Pikachu", "number": "1", "set": "POP Series 1", "language": "JP", "region": "jp" }
      ]
    }
  }
}

Resolve it either by switching to one candidate's canonical id, or by adding ?language=en (or ?region=) to the same request. For example, GET /cards/pop_1?language=en resolves cleanly to pop1-1. The same 409 contract applies to ambiguous set shortcuts.

Sealed products

Sealed products (booster boxes, elite trainer boxes, tins, and so on) have a single id: their slug (e.g. scarlet-violet-elite-trainer-box). There is no separate canonical / friendly distinction for products: the slug is both.

Filtering products by set

GET /products?set= accepts a set shortcut the same way card and set lookups do, but that endpoint has no ?language= / ?region= filters to disambiguate with. If the shortcut you pass is ambiguous there, the only escape is to use the set's canonical tcg_api_id instead of its shortcut.