Trading Cards

Single trading cards across TCGs (Pokémon, Magic: The Gathering, Yu-Gi-Oh, etc.) and modern non-sports brands. Supports both graded and raw cards.

Active development

This vertical is in active development — fields, formats, and behavior may change.

External IDs

Field	Required	Description	Example
TCGPLAYER	No	TCGPlayer marketplace product ID	"593355"

Asset details

Asset-level fields identify the card itself — set + character + identity, independent of grade or print variant.

Field	Required	Type	Description	Example
id	Yes	string	Tradepost asset ID (UUID)	"be6323f8-25d0-4953-9af1-becac5f13acb"
name	No	string	Card identity	"Charizard - 4/102"
set_name	No	string	Canonical set name	"1999 Pokemon Base Set"
subcategory	No	string	TCG family	"POKEMON_CARDS", "MAGIC_CARDS", "YUGIOH_CARDS"
brand	No	string	IP / franchise	"Pokemon"
manufacturer	No	string	Company that prints the cards	"Wizards of the Coast"
subject	No	string[]	Featured characters	["Charizard"]

Config details

Configurations distinguish print variants of the same card — language, rarity, foil treatment, print run.

Field	Required	Type	Description	Example
id	Yes	string	Tradepost asset configuration ID (UUID)	"0ce36c59-1710-4c6a-93ae-86b4e8f06a24"
name	No	string	Configuration name	"Charizard - 4/102 · Base Set · Holo Rare · English"
image_url	No	string	Primary image URL	—
rarity	No	string	Official rarity	"Holo Rare", "Secret Rare", "Promo"
print_version	No	string	Edition / print run	"1st Edition", "Unlimited"
artist	No	string	Card artist	"Mitsuhiro Arita"
language	No	string	Print language	"English", "Japanese"
is_foil	No	boolean	Foil / holographic treatment	true
holo_pattern	No	string	Holographic pattern	"Cosmos", "Rainbow", "Galaxy"
reverse_holo	No	boolean	Reverse-holo printing	false
is_textured	No	boolean	Raised / textured surface	false

Item details

Item-level fields describe the physical card — grade, condition, autograph status.

For graded cards, grading_company + grade (+ cert_number) define the card and raw_condition is null. For raw cards, raw_condition defines it and the grading fields are null.

Field	Required	Type	Description	Example
key_id	No	string	Tradepost key ID (UUID, may be null)	"33d011e4-…"
key_ids	No	string[]	All key IDs for this item	["33d011e4-…"]
fair_values	No	array	Fair value entries — see Key Fair Values	[]
grading_company	No	string	PSA, BGS, CGC, SGC, TAG; null for raw	"PSA"
grade	No	string	Overall grade; null for raw	"10", "9.5"
cert_number	No	string	Grading company certification number	"12345678"
raw_condition	No	string	MINT, NEAR_MINT, EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR	"NEAR_MINT"
is_autographed	No	boolean	Autographed	false
autograph_grade	No	string	Autograph grade, when graded	"10"
serial_number	No	string	Serial numerator for limited print runs	"23"
quantity	Yes	integer	Number of units	1

Example — graded card

{
  "asset_type": "TRADING_CARD",
  "external_ids": { "TCGPLAYER": "593355" },
  "asset_details": {
    "id": "be6323f8-25d0-4953-9af1-becac5f13acb",
    "name": "Charizard - 4/102",
    "set_name": "1999 Pokemon Base Set",
    "subcategory": "POKEMON_CARDS",
    "brand": "Pokemon",
    "manufacturer": "Wizards of the Coast",
    "subject": ["Charizard"]
  },
  "config_details": {
    "id": "0ce36c59-1710-4c6a-93ae-86b4e8f06a24",
    "name": "Charizard - 4/102 · Base Set · Holo Rare · English",
    "rarity": "Holo Rare",
    "print_version": "Unlimited",
    "language": "English",
    "is_foil": true,
    "reverse_holo": false,
    "is_textured": false
  },
  "item_details": {
    "key_id": "33d011e4-60ec-51ed-a92e-30677a9066b8",
    "key_ids": ["33d011e4-60ec-51ed-a92e-30677a9066b8"],
    "fair_values": [],
    "grading_company": "PSA",
    "grade": "10",
    "cert_number": "12345678",
    "is_autographed": false,
    "quantity": 1
  }
}

Example — raw card

{
  "asset_type": "TRADING_CARD",
  "external_ids": {},
  "asset_details": {
    "id": "be6323f8-25d0-4953-9af1-becac5f13acb",
    "name": "Charizard - 4/102",
    "set_name": "1999 Pokemon Base Set",
    "subcategory": "POKEMON_CARDS",
    "brand": "Pokemon"
  },
  "config_details": {
    "id": "0ce36c59-1710-4c6a-93ae-86b4e8f06a24",
    "name": "Charizard - 4/102 · Base Set · Holo Rare · English",
    "rarity": "Holo Rare",
    "language": "English",
    "is_foil": true
  },
  "item_details": {
    "key_id": "dafe91c0-bcee-58a2-a868-006cb8e19ac0",
    "key_ids": ["dafe91c0-bcee-58a2-a868-006cb8e19ac0"],
    "fair_values": [],
    "raw_condition": "NEAR_MINT",
    "is_autographed": false,
    "quantity": 1
  }
}

Targeting with strategies

Grade targeting (PSA 10 vs 9, auto-grade AND gates, raw conditions) works through keyCriteria — see Strategies → Grade targeting and Catalog → Keys.