Skip to content
TTCGAPIs
TCGPlayer API

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.

Chainable Workflow

How the TCGPlayer API Works

categoryId → groupId → productId → skuId. Each call returns the IDs you need for the next.

1

List Games

/api/v2/games

Returns categoryId for each supported game.

2

Get Expansions

/api/v2/expansions/:categoryId

Use categoryId to fetch every expansion. Each row carries groupId.

3

Get Cards

/api/v2/cards/:groupId

Use groupId to fetch every card in the set. Each row carries productId.

4

Get Prices / SKUs / Listings

/api/v2/prices/:productId

Use productId to fetch prices, SKU prices, sales history, historic prices, or live listings.

9 Endpoints

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.

GET/api/v2/games
Public

List all supported games. Each row carries categoryId for the next step.

GET/api/v2/expansions/:categoryId
Calls: 1 on every plan

Paginated expansions for a game. Each row carries groupId.

GET/api/v2/cards/:groupId
Calls: 1 on every plan

Paginated cards in an expansion with images, names, numbers, rarities. Each row carries productId.

GET/api/v2/prices/:productId
Calls: 1 on every plan

Latest TCGPlayer prices for a card across all printings (Normal / Foil / 1st Edition / etc).

GET/api/v1/skuprices/:skuId
Calls: Hobby 5 · Business 5 · Unlimited 1

Per-SKU price for one specific condition + printing + language combination.

GET/api/v1/skuprices/product/:productId
Calls: Hobby 5 · Business 5 · Unlimited 1

Available SKU price records for a card, including supported conditions, printings and languages.

GET/api/v2/sales-history/:productId
Calls: 1 on every plan

Recent source-sale snapshot of up to 100 records, cached for up to four hours, with sample statistics.

GET/api/v2/sales-history/:productId/full
Calls: 1 on every plan

Full 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.

GET/api/v2/historic-prices/:productId
Calls: 1 on every plan

Stored snapshots keyed by available dates and printing names. Date coverage and printings can vary.

GET/api/v2/livelistings/:productId
Calls: Hobby 5 · Business 5 · Unlimited 1

Available source listing snapshot with reported condition, printing, quantity, price and shipping fields; not an exhaustive seller or language feed.

Full Schemas

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/games
Public

Top of the catalog tree. One row per source category, including categories beyond trading-card games.

FieldTypeDescription
categoryIdintegerCategory ID used by the expansions endpoint.
namestringSource category name.
displayNamestringDisplay name when supplied.
imagestringCategory image when supplied.

Expansions

GET /api/v2/expansions/:categoryId
Calls: 1 on every plan

All expansions (sets) for a game. Use the groupId to drill into cards.

FieldTypeDescription
groupIdintegerGroup ID used to request cards.
namestringSet name.
abbreviationstringSet abbreviation when supplied.
publishedOnstringSource publication date when supplied.
imagestringSet image when supplied.

Cards

GET /api/v2/cards/:groupId
Calls: 1 on every plan

Available product records in the requested group, including sealed products when present. The group filter does not restrict results to singles.

FieldTypeDescription
productIdintegerTCGPlayer product ID — primary key for prices, listings, sales, SKUs.
namestringDisplay name (may include variant suffixes).
cleanNamestringStripped name for matching/joining.
numberstringCollector / set number (e.g. "025/200").
raritystringRarity tier (Common, Rare, Holo Rare, Mythic, Secret, etc.).
imageUrlstringHosted card image URL.
expansionNamestringParent expansion.
gameNamestringParent game.

Prices (per product)

GET /api/v2/prices/:productId
Calls: 1 on every plan

Latest aggregate prices for a card. Returns a data.prices object keyed by printing.

FieldTypeDescription
data.productIdintegerTCGPlayer product ID.
data.pricesobjectPrice records keyed by printing, such as Normal or Foil.
data.prices[printing].marketPricenumber or nullSource market-price field in USD when available.
data.prices[printing].lowPricenumber or nullSource low-price field in USD when available.
data.prices[printing].midPricenumber or nullSource mid-price field in USD when available.
data.prices[printing].highPricenumber or nullSource high-price field in USD when available.
data.prices[printing].directLowPricenumber or nullSource Direct low-price field when available.
data.last_updatedstring or nullRecord 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/:productId
Calls: Hobby 5 · Business 5 · Unlimited 1

The most granular pricing tier — one entry per (productId, condition, printing, language) combination. The number of available SKU records varies by product.

FieldTypeDescription
skuIdintegerTCGPlayer SKU ID.
productIdintegerParent product ID.
lowPricedecimalLowest current listing for this exact SKU.
lowestShippingdecimalCheapest shipping cost on the lowest listing.
lowestListingPricedecimalSource-provided listing-price field when available; do not infer a relationship to other fields without checking the record.
marketPricedecimalTCGPlayer market price for this exact SKU.
directLowPricedecimalLowest TCGPlayer Direct price for this SKU.
last_updatedISO timestampLast refresh of the SKU price row.

Recent Sales Snapshot

GET /api/v2/sales-history/:productId
Calls: 1 on every plan

Recent source transactions from a bounded upstream snapshot; responses can be cached for up to four hours.

FieldTypeDescription
dateISO timestampWhen the sale closed.
marketplacestringAlways "TCGPlayer".
conditionstringCard condition at time of sale (Near Mint, Lightly Played, etc.).
variantstringPrinting variant ("Normal", "Foil", "1st Edition", etc.).
pricedecimalFinal price paid (purchase price + shipping).
data.statisticsobjectComputed over the available source snapshot, not all historical market transactions.
data.statistics.last24HoursobjectTotal and per-variant counts within the available snapshot for the last 24 hours.
data.statistics.priceAnalysisobjectTrend summary for the dominant variant in the available sample.
data.statistics.byVariantobjectPer-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/full
Calls: 1 on every plan

Stored three-day sales buckets per available condition, printing and language. Date coverage varies by product. This is separate from the cached recent-transaction snapshot.

FieldTypeDescription
data.summaryobjectAggregate stats: avgMarketPrice, minMarketPrice, maxMarketPrice, totalSalesAllBuckets, totalSalesLastBucket, lastBucketDate, lastUpdated.
data.available.skusarrayEvery (skuId, condition, variant, language) tuple discovered for this product — populate filter dropdowns from one call.
data.available.conditions / variants / languagesstring[]Distinct sorted lists of values present for this product.
data.rows[].skuIdstringTCGPlayer SKU ID this bucket belongs to.
data.rows[].conditionstringNM / LP / MP / HP / Damaged.
data.rows[].variantstringNormal / Foil / 1st Edition / etc.
data.rows[].languagestringEnglish / Japanese / etc.
data.rows[].bucketStartDatedate stringStart of the 3-day bucket (YYYY-MM-DD).
data.rows[].marketPricedecimalTCGPlayer market price snapshot for the bucket.
data.rows[].quantitySoldintegerNumber of units sold in the bucket (0 if no sales).
data.rows[].transactionCountintegerDistinct sale transactions in the bucket.
data.rows[].lowSalePrice / highSalePricedecimalLowest / highest single sale price in the bucket.
data.rows[].lowSalePriceWithShipping / highSalePriceWithShippingdecimalSame low/high but including shipping cost.

Historic Prices

GET /api/v2/historic-prices/:productId
Calls: 1 on every plan

Stored 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.

FieldTypeDescription
productIdintegerTCGPlayer product ID.
createdAtISO timestampWhen tracking began for this product.
data.prices.<date>.<printing>.lowPricedecimalSource low-price snapshot on that day for that variant.
data.prices.<date>.<printing>.midPricedecimalSource mid-price snapshot on that day for that variant.
data.prices.<date>.<printing>.highPricedecimalSource high-price snapshot on that day for that variant.
data.prices.<date>.<printing>.marketPricedecimalTCGPlayer market price snapshot for that day.
data.prices.<date>.<printing>.directLowPricedecimalLowest TCGPlayer Direct price for the day (may be null).

Live Listings

GET /api/v2/livelistings/:productId
Calls: Hobby 5 · Business 5 · Unlimited 1

Available 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.

FieldTypeDescription
data.allListingsobjectListings grouped by condition, then printing, then standard/custom arrays.
listingIdstring or numberIdentifier on a returned listing entry.
sellerNamestringSeller name when supplied on an entry.
pricenumberEntry price from the source.
shippingnumberEntry shipping amount from the source, not shippingPrice.
quantityintegerEntry quantity from the source.
data.cheapestByConditionAndPrintingobjectSelected listing entries keyed by condition and printing.
data.lastUpdatedstringWhen 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.

Search → product → prices
// 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.