TCGPlayer API Documentation
REST access to available records from TCGPlayer's catalog and marketplace data — endpoints covering games, expansions, cards, prices, SKU pricing, sales history, historic price snapshots, and listing snapshots.
How the TCGPlayer API Works
categoryId → groupId → productId → skuId. Each call returns the IDs you need for the next.
List Games
/api/v2/gamesReturns categoryId for each supported game.
Get Expansions
/api/v2/expansions/:categoryIdUse categoryId to fetch every expansion. Each row carries groupId.
Get Cards
/api/v2/cards/:groupIdUse groupId to fetch every card in the set. Each row carries productId.
Get Prices / SKUs / Listings
/api/v2/prices/:productIdUse productId to fetch prices, SKU prices, sales history, historic prices, or live listings.
TCGPlayer API Endpoints
Authenticated via x-api-key. Every endpoint works with credits (free or bought); each badge shows how many calls one request takes from the monthly allowance on each plan.
/api/v2/gamesList all supported games. Each row carries categoryId for the next step.
/api/v2/expansions/:categoryIdPaginated expansions for a game. Each row carries groupId.
/api/v2/cards/:groupIdPaginated cards in an expansion with images, names, numbers, rarities. Each row carries productId.
/api/v2/prices/:productIdLatest TCGPlayer prices for a card across all printings (Normal / Foil / 1st Edition / etc).
/api/v1/skuprices/:skuIdPer-SKU price for one specific condition + printing + language combination.
/api/v1/skuprices/product/:productIdAvailable SKU price records for a card, including supported conditions, printings and languages.
/api/v2/sales-history/:productIdRecent source-sale snapshot of up to 100 records, cached for up to four hours, with sample statistics.
/api/v2/sales-history/:productId/fullFull historic sales archive — 90+ days of bucketed data. Server-side filters by condition, variant, language, date range. Best for trend charts and per-condition pricing.
/api/v2/historic-prices/:productIdStored snapshots keyed by available dates and printing names. Date coverage and printings can vary.
/api/v2/livelistings/:productIdAvailable source listing snapshot with reported condition, printing, quantity, price and shipping fields; not an exhaustive seller or language feed.
Every Field We Expose
Complete field-by-field reference for every TCGPlayer-source endpoint, so you know exactly what you can build with.
Games
GET /api/v2/gamesTop of the catalog tree. One row per source category, including categories beyond trading-card games.
| Field | Type | Description |
|---|---|---|
| categoryId | integer | Category ID used by the expansions endpoint. |
| name | string | Source category name. |
| displayName | string | Display name when supplied. |
| image | string | Category image when supplied. |
Expansions
GET /api/v2/expansions/:categoryIdAll expansions (sets) for a game. Use the groupId to drill into cards.
| Field | Type | Description |
|---|---|---|
| groupId | integer | Group ID used to request cards. |
| name | string | Set name. |
| abbreviation | string | Set abbreviation when supplied. |
| publishedOn | string | Source publication date when supplied. |
| image | string | Set image when supplied. |
Cards
GET /api/v2/cards/:groupIdAvailable product records in the requested group, including sealed products when present. The group filter does not restrict results to singles.
| Field | Type | Description |
|---|---|---|
| productId | integer | TCGPlayer product ID — primary key for prices, listings, sales, SKUs. |
| name | string | Display name (may include variant suffixes). |
| cleanName | string | Stripped name for matching/joining. |
| number | string | Collector / set number (e.g. "025/200"). |
| rarity | string | Rarity tier (Common, Rare, Holo Rare, Mythic, Secret, etc.). |
| imageUrl | string | Hosted card image URL. |
| expansionName | string | Parent expansion. |
| gameName | string | Parent game. |
Prices (per product)
GET /api/v2/prices/:productIdLatest aggregate prices for a card. Returns a data.prices object keyed by printing.
| Field | Type | Description |
|---|---|---|
| data.productId | integer | TCGPlayer product ID. |
| data.prices | object | Price records keyed by printing, such as Normal or Foil. |
| data.prices[printing].marketPrice | number or null | Source market-price field in USD when available. |
| data.prices[printing].lowPrice | number or null | Source low-price field in USD when available. |
| data.prices[printing].midPrice | number or null | Source mid-price field in USD when available. |
| data.prices[printing].highPrice | number or null | Source high-price field in USD when available. |
| data.prices[printing].directLowPrice | number or null | Source Direct low-price field when available. |
| data.last_updated | string or null | Record update timestamp when supplied; not a guarantee of freshness. |
SKU Prices (per SKU or per product)
GET /api/v1/skuprices/:skuId · GET /api/v1/skuprices/product/:productIdThe most granular pricing tier — one entry per (productId, condition, printing, language) combination. The number of available SKU records varies by product.
| Field | Type | Description |
|---|---|---|
| skuId | integer | TCGPlayer SKU ID. |
| productId | integer | Parent product ID. |
| lowPrice | decimal | Lowest current listing for this exact SKU. |
| lowestShipping | decimal | Cheapest shipping cost on the lowest listing. |
| lowestListingPrice | decimal | Source-provided listing-price field when available; do not infer a relationship to other fields without checking the record. |
| marketPrice | decimal | TCGPlayer market price for this exact SKU. |
| directLowPrice | decimal | Lowest TCGPlayer Direct price for this SKU. |
| last_updated | ISO timestamp | Last refresh of the SKU price row. |
Recent Sales Snapshot
GET /api/v2/sales-history/:productIdRecent source transactions from a bounded upstream snapshot; responses can be cached for up to four hours.
| Field | Type | Description |
|---|---|---|
| date | ISO timestamp | When the sale closed. |
| marketplace | string | Always "TCGPlayer". |
| condition | string | Card condition at time of sale (Near Mint, Lightly Played, etc.). |
| variant | string | Printing variant ("Normal", "Foil", "1st Edition", etc.). |
| price | decimal | Final price paid (purchase price + shipping). |
| data.statistics | object | Computed over the available source snapshot, not all historical market transactions. |
| data.statistics.last24Hours | object | Total and per-variant counts within the available snapshot for the last 24 hours. |
| data.statistics.priceAnalysis | object | Trend summary for the dominant variant in the available sample. |
| data.statistics.byVariant | object | Per-variant count, average/median/highest/lowest price and trend values for the available sample. |
Sales History (Full Archive — Filterable)
GET /api/v2/sales-history/:productId/fullStored three-day sales buckets per available condition, printing and language. Date coverage varies by product. This is separate from the cached recent-transaction snapshot.
| Field | Type | Description |
|---|---|---|
| data.summary | object | Aggregate stats: avgMarketPrice, minMarketPrice, maxMarketPrice, totalSalesAllBuckets, totalSalesLastBucket, lastBucketDate, lastUpdated. |
| data.available.skus | array | Every (skuId, condition, variant, language) tuple discovered for this product — populate filter dropdowns from one call. |
| data.available.conditions / variants / languages | string[] | Distinct sorted lists of values present for this product. |
| data.rows[].skuId | string | TCGPlayer SKU ID this bucket belongs to. |
| data.rows[].condition | string | NM / LP / MP / HP / Damaged. |
| data.rows[].variant | string | Normal / Foil / 1st Edition / etc. |
| data.rows[].language | string | English / Japanese / etc. |
| data.rows[].bucketStartDate | date string | Start of the 3-day bucket (YYYY-MM-DD). |
| data.rows[].marketPrice | decimal | TCGPlayer market price snapshot for the bucket. |
| data.rows[].quantitySold | integer | Number of units sold in the bucket (0 if no sales). |
| data.rows[].transactionCount | integer | Distinct sale transactions in the bucket. |
| data.rows[].lowSalePrice / highSalePrice | decimal | Lowest / highest single sale price in the bucket. |
| data.rows[].lowSalePriceWithShipping / highSalePriceWithShipping | decimal | Same low/high but including shipping cost. |
Historic Prices
GET /api/v2/historic-prices/:productIdStored price snapshots over the available tracked dates. The data.prices map is keyed by date (YYYY-MM-DD), then by printing name; names and dates vary and gaps can occur.
| Field | Type | Description |
|---|---|---|
| productId | integer | TCGPlayer product ID. |
| createdAt | ISO timestamp | When tracking began for this product. |
| data.prices.<date>.<printing>.lowPrice | decimal | Source low-price snapshot on that day for that variant. |
| data.prices.<date>.<printing>.midPrice | decimal | Source mid-price snapshot on that day for that variant. |
| data.prices.<date>.<printing>.highPrice | decimal | Source high-price snapshot on that day for that variant. |
| data.prices.<date>.<printing>.marketPrice | decimal | TCGPlayer market price snapshot for that day. |
| data.prices.<date>.<printing>.directLowPrice | decimal | Lowest TCGPlayer Direct price for the day (may be null). |
Live Listings
GET /api/v2/livelistings/:productIdAvailable listing snapshot. The live fetch requests up to 50 English-language listings in a US shipping context, can be cached for up to one hour and may fall back to stored data.
| Field | Type | Description |
|---|---|---|
| data.allListings | object | Listings grouped by condition, then printing, then standard/custom arrays. |
| listingId | string or number | Identifier on a returned listing entry. |
| sellerName | string | Seller name when supplied on an entry. |
| price | number | Entry price from the source. |
| shipping | number | Entry shipping amount from the source, not shippingPrice. |
| quantity | integer | Entry quantity from the source. |
| data.cheapestByConditionAndPrinting | object | Selected listing entries keyed by condition and printing. |
| data.lastUpdated | string | When the listing snapshot was processed, not a market-observation guarantee. |
Example: Search, Product and Prices
Read the product and price envelopes separately. Fields and timestamps can be missing; select the intended printing.
// Category IDs come from GET /api/v2/games.
// Run on your server. Credits (free or bought) cover all customer data endpoints.
// Monthly plans: catalog and search take 1 call; product prices take 1 call.
const headers = { 'x-api-key': process.env.TCGAPIS_KEY };
async function get(path) {
const response = await fetch('https://api.tcgapis.com/api/v2' + path, { headers });
const body = await response.json();
if (!response.ok || !body.success) throw new Error(body.error || 'API request failed');
return body;
}
const search = await get('/search?q=Lightning+Bolt&game=1&limit=1');
const productId = search.data[0]?.productId;
if (!productId) throw new Error('No matching product found');
const product = await get('/products/' + productId);
const prices = await get('/prices/' + productId);
console.log(product.data); // Catalog details and available SKU metadata
console.log(prices.data.prices); // Pricing records grouped by printing
console.log(prices.data.last_updated); // Record timestamp when provided
// SKU prices and live listings use separate endpoints: 5 credits per request; on a monthly plan 1 call on Unlimited, 5 on Hobby and Business.Frequently Asked Questions
What does the TCGPlayer API give me access to?
TCGAPIs exposes available TCGPlayer-source catalog records, product and SKU prices, recent sales snapshots, stored sales buckets, historic price snapshots and seller-listing snapshots. Availability depends on the product, source and endpoint; this is not every record or field exposed by TCGPlayer.
How is per-product pricing different from per-SKU pricing?
Product prices are keyed by printing under data.prices. SKU price records additionally identify available condition, printing and language combinations. The number of records and populated fields varies by product. Both work with credits (free or bought): 2 credits per product-price request, 5 per SKU-price request. On a monthly plan, a product-price request takes 1 call, and a SKU-price request takes 1 call on Unlimited and 5 on Hobby and Business.
When should I use sales-history vs sales-history/full vs historic-prices?
The recent sales-history endpoint returns a bounded source transaction snapshot and can be cached for up to four hours. The sales-history/full endpoint returns stored SKU-level three-day bucket rows, not individual transactions; available date coverage varies by product. Historic-prices returns stored price snapshots keyed by date and then the available printing names, which may include Normal, Foil or Holofoil. Dates and printings can be missing.
How fresh is the data?
Listing requests can use a cache for up to one hour and fall back to a stored snapshot when the source is unavailable. Recent sales can be cached for up to four hours. Product and SKU records may include update timestamps; absent timestamps do not establish freshness. Historic price snapshots can have gaps. No universal update cadence, seconds-old guarantee or guaranteed daily observation is published.
How many calls does each endpoint take?
The games endpoint is public. Everything else works with credits (free or bought): 1 credit for a catalog lookup, 2 for a price or history lookup, 5 for SKU prices or listing snapshots. After your free credits are used, buy a credit pack (from £10, no subscription) or choose a monthly plan. Every monthly plan can call every endpoint: catalog lookups, product prices and histories take 1 call, and SKU prices and listing snapshots take 1 call on Unlimited and 5 on Hobby and Business.