API Documentation
Learn how to integrate the JustTCG API into your applications.
Overview
The JustTCG API provides real-time pricing data for trading card games including Magic: The Gathering, Pokémon, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Digimon, and Union Arena. Our API is designed to be simple, fast, and reliable.
We strongly recommend using our official justtcg-js SDK. It provides type safety, automatic authentication, and cleaner data models to accelerate your development.
Base URL
https://api.justtcg.com/v1Authentication
All API requests require authentication using an API key. You can obtain an API key by signing up for an account and subscribing to a plan.
JUSTTCG_API_KEY environment variable.Learn more about SDK configuration →Manual API Key Authentication
Include your API key in the request headers:
x-api-key:tcg_your_api_key_hereSDK Authentication Example
The SDK handles authentication automatically:
import { JustTCG } from 'justtcg-js';
// Automatic authentication via environment variable
const client = new JustTCG();
// Or provide the key directly
const client = new JustTCG({ apiKey: 'your_api_key_here' });API Reference
Our API is focused on three main endpoints for a more intuitive and seamless experience:
- Games and Sets: For discovering available games and sets.
- Cards: For searching and direct lookups. If you pass an
id, you get a direct lookup. If you do not pass anid, the endpoint serves as a flexible search.
Collection Resources
These endpoints provide information about the available trading card games and sets in our database. Start with these endpoints to understand what's available before diving into the cards endpoint.
Games
Retrieve a list of all games.
https://api.justtcg.com/v1/gamesResponse Object
Sets
Retrieve a list of all sets.
https://api.justtcg.com/v1/setsQuery Parameters
Search query for finding sets by name.
Filter by game ID (e.g., mtg, pokemon).
Field to sort by: name or release_date.
Sort order for results: asc or desc.
Response Object
Cards
This high-performance endpoint provides rapid access to card data whether you already have identifier values or not. For the best performance when retrieving specific cards, use this endpoint with IDs obtained from the games or sets endpoints.
Card Lookup
Retrieve a card and its variant prices by ID or search query. You can optionally filter the returned variants by condition and printing type.
https://api.justtcg.com/v1/cardsNote: Any identifier will take precedence over any search query if multiple of those are provided.
Query Parameters
TCGplayer ID of the card.
MTGJSON ID of the card.
Scryfall ID of the card.
TCGPlayer SKU ID of the variant. Note, printing and condition filters do not apply when this is defined.
Filter by printing type (e.g., Normal, Foil).
An array of conditions to filter by. Supports fully spelled names or abbreviations. Full names: "Sealed", "Near Mint", "Lightly Played", "Moderately Played", "Heavily Played", "Damaged". Abbreviations: "S", "NM", "LP", "MP", "HP", "DMG".
Specify the duration of price history to include. Options are 7d, 30d, 90d, or 180d. This is ignored if include_price_history is set to false.
Include price history data in the response.
Specify which timeframe statistics to include in the response. Defaults to all timeframes.
Options:
7d30d90d1yallTime
You can provide a comma-separated list (e.g., 7d,30d,1y) to include multiple statistics.
Include cards with no pricing data in the response. Defaults to false. This parameter is ignored if a search query is passed in.
Response Object
Batch Card Lookup
Retrieve multiple cards and their variants in a single request. For each card, you can optionally filter variants by specifying condition and printing parameters.
https://api.justtcg.com/v1/cardsRequest Body Parameters
Send an array of objects, each containing the following properties:
TCGplayer ID of the card.
MTGJSON ID of the card.
Scryfall ID of the card.
TCGPlayer SKU ID of the variant. Note, printing and condition filters do not apply when this is defined.
Card ID of the card.
Variant ID of the card.
Filters results to include only card variants whose pricing information has been updated at or after the provided timestamp. Format: Unix Timestamp in seconds. Compatible with most filters (e.g., game, set, cardId, orderBy), but cannot be combined with the search query parameter (q).
Filter by printing type (e.g., Normal, Foil).
An array of conditions to filter by. Supports fully spelled names or abbreviations. Full names: "Sealed", "Near Mint", "Lightly Played", "Moderately Played", "Heavily Played", "Damaged". Abbreviations: "S", "NM", "LP", "MP", "HP", "DMG".
If multiple identifiers are provided, precedence is as follows:
variantId > tcgplayerSkuId > tcgplayerId > mtgjsonId > scryfallId > cardId.Note: The maximum number of items supported in a single request is 200 for "Enterprise" plans, 100 for "Starter" and "Pro" plans, and 20 for the free plan. For larger queries, please consider batching your requests.
Response Object
Card Object
The Card object contains detailed information about a trading card, including its variants with pricing information.
Variant Object
Each variant represents a specific combination of condition and printing for a card, with its associated price.
Example Card Object
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped",
"name": "Fire Energy (#22 Charizard Stamped)",
"game": "Pokemon",
"set": "battle-academy-pokemon",
"set_name": "Battle Academy",
"number": "N/A",
"tcgplayerId": "219042",
"rarity": "Promo",
"details": null,
"variants": [
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_near-mint",
"printing": "Normal",
"condition": "Near Mint",
"price": 4.99,
"lastUpdated": 1743100261
},
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_lightly-played",
"printing": "Normal",
"condition": "Lightly Played",
"price": 3.50,
"lastUpdated": 1743101175
}
]
}Card IDs
Each card object has a unique id, sometimes referred to as the cardId or "Card ID".
The card ID is structured as game-set-name-rarity. This ID can be used for direct lookups using the /cards endpoint.
Note: Multiple variants of the same card ID may exist, each with its own unique variant ID. The card ID is not guaranteed to be unique across all variants.
Variant IDs
Each variant has a unique id, sometimes referred to as variantId or "Variant ID".
The variant ID is structured as cardId_condition_printing and can be used for direct, high-performance lookups using the /cards endpoint.
If you already have the variant ID, using it directly is the fastest way to retrieve pricing information.
Filtering Variants
When retrieving cards, you can filter the variants by adding optional printing and condition parameters to your requests. This helps reduce response size and narrow down results to specific variants you're interested in.
Consistency Note
All endpoints that return card data use this same structure. Every card will have at least one variant in its variants array.
Response Format
All API responses follow a consistent format with a data field containing the requested information, a meta field with pagination details (when applicable), and a _metadata field with API usage statistics.
Response Structure
Error Handling
The JustTCG API uses standard HTTP status codes and returns consistent error response formats to help you quickly identify and resolve issues.
HTTP Status Codes
Error Response Format
All error responses follow a consistent format with an error object containing details about the error.
{
"error": "Invalid game parameter. Must be one of: magic-the-gathering, mtg, pokemon, yugioh, age-of-sigmar, warhammer-40000, union-arena, flesh-and-blood-tcg, disney-lorcana, digimon-card-game, one-piece-card-game",
"code": "INVALID_REQUEST"
}Common Error Codes
Code Examples
Practical examples showing how to integrate the JustTCG API in real-world scenarios.
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Fetch all cards from a set (automatically handles pagination)
async function updatePricesForSet(gameId, setId) {
console.log(`Updating prices for ${gameId} set: ${setId}...`);
let allCards = [];
let hasMoreResults = true;
let offset = 0;
const LIMIT = 20;
// Keep fetching until we've got all cards
while (hasMoreResults) {
try {
// Create URL with query parameters
const url = new URL(`${BASE_URL}/cards`);
url.searchParams.append('game', gameId);
url.searchParams.append('set', setId);
url.searchParams.append('limit', LIMIT);
url.searchParams.append('offset', offset);
// Make the API request
const response = await fetch(url, {
headers: { 'X-API-Key': API_KEY }
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'API request failed');
}
const cards = result.data;
console.log(`Fetched ${cards.length} cards (offset: ${offset})`);
// Add cards to our collection
allCards = [...allCards, ...cards];
// Check if we've reached the end
hasMoreResults = cards.length === LIMIT;
offset += LIMIT;
// For demo purposes, just log first card's variants
if (offset === LIMIT && cards.length > 0) {
console.log('Sample card variation prices:');
cards[0].variants.forEach(v => {
console.log(`- ${v.condition} / ${v.printing}: $${v.price}`);
});
}
} catch (error) {
console.error('Error fetching cards:', error);
break;
}
}
console.log(`✅ Updated prices for ${allCards.length} cards`);
return allCards;
}
// Example usage
updatePricesForSet('magic-the-gathering', 'modern-horizons-2-magic-the-gathering');// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Display a product page with multiple cards
async function fetchProductPageCards(cardIds) {
console.log('Fetching data for product display...');
try {
// Batch card lookup for efficiency
const response = await fetch(`${BASE_URL}/cards`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cardIds.map(id => ({ tcgplayerId: id })))
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch cards');
}
// Display the cards (in a real app, you'd render these to the DOM)
console.log(`Displaying ${result.data.length} cards:`);
result.data.forEach(card => {
console.log(`${card.name} - ${card.set_name}`);
// Get the lowest price for display
const lowestPrice = Math.min(
...card.variants.map(v => v.price)
);
console.log(` Starting from: $${lowestPrice.toFixed(2)}`);
});
return result.data;
} catch (error) {
console.error('Error fetching product data:', error);
return [];
}
}
// Example usage
fetchProductPageCards(['219042', '25788', '1369']);// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Calculate shopping cart total with specific variants
async function calculateShoppingCart(cartItems) {
console.log('Calculating shopping cart total...');
try {
// Get up-to-date prices for all variants in cart
const response = await fetch(`${BASE_URL}/cards`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cartItems)
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch prices');
}
// Calculate total (in a real app, you'd update the cart UI)
let total = 0;
result.data.forEach(item => {
const subtotal = item.variants[0].price;
total += subtotal;
console.log(
`${item.name} (${item.variants[0].condition}, ${item.variants[0].printing}): $${item.variants[0].price.toFixed(2)}`
);
});
console.log(`Cart Total: $${total.toFixed(2)}`);
return total;
} catch (error) {
console.error('Error calculating cart:', error);
return 0;
}
}
// Example usage
calculateShoppingCart([
{ tcgplayerId: '219042', condition: 'Near Mint', printing: 'Normal' },
{ tcgplayerId: '25788', condition: 'Lightly Played', printing: '1st Edition' }
]);Rate Limits & Usage
The JustTCG API has rate limits based on your subscription plan. You can monitor your API usage in your dashboard.
Rate Limits by Plan
429 Too Many Requests response. If you exceed your monthly limit, you'll need to upgrade your plan to continue using the API.Note: Rate limits are enforced per API key. If you have multiple keys, each key has its own rate limit.
Reset Times
Support
If you have any questions or need help with the API, please contact our support team.
Change Log
- Changed90-Day and 180-Day Price History Support AddedDec 19, 2025
Added support for 90d and 180d price history. Deprecated
priceHistory30din the process. Use query parampriceHistoryDurationto select desired durations (7d, 30d, 90d, 180d). Defaults to 7d. Notice to developers:priceHistory30dwill be removed in a future major release. Update your integrations accordingly, asap. - AddedNew Games Added: hololive OFFICIAL CARD GAME and Dragon Ball Super: Fusion WorldDec 15, 2025
Added support for two new games: hololive OFFICIAL CARD GAME (
hololive-official-card-game) and Dragon Ball Super: Fusion World (dragon-ball-super-fusion-world). - AddedGame and Set Value Index Fields AddedDec 13, 2025
Added new fields
game_value_usdto the/gamesendpoint andset_value_usdto the/setsendpoint. These fields represent the total value of all cards in the game or set, calculated by taking the highest price of any variant for each card. This addition provides developers with a quick overview of the market value of entire games and sets. - Addedinclude_null_prices Parameter AddedDec 9, 2025
Added the
include_null_pricesboolean query parameter to the/cardsendpoint. When set totrue, this parameter includes cards that do not have any pricing data in the response. By default, this parameter is set tofalse, meaning only cards with pricing data are returned. This enhancement allows users to retrieve a more comprehensive list of cards, including those without current market prices. - AddedCard Number Filter Added to /cards EndpointDec 8, 2025
Added the
numberquery parameter to the/cardsendpoint. This allows users to filter cards by their specific card number within a set, enhancing search precision and usability. - ChangedIntroduced sealed_count and variants_count FieldsNov 21, 2025
Fixed card counts in /sets and /games endpoints to not include sealed products. Introduced sealed_count to both endpoints and variants_count field to /sets endpoint to provide more accurate data.
- Addedupdated_after Parameter Added to /cards EndpointNov 19, 2025
Added the
updated_afterparameter to bothGET /cardsandPOST /cards(Batch) endpoints. This parameter filters results to include only card variants whose pricing information has been updated at or after the provided Unix timestamp (in seconds). This enables efficient delta synchronization workflows. The parameter is compatible with most filters (e.g.,game,set,cardId,orderBy) but cannot be combined with the search query parameter (q). - AddedExternal Identifiers AddedOct 27, 2025
Added support for querying cards by MTGJSON and Scryfall IDs. Furthermore, variants can be queried using TCGPlayer SKU IDs.
- AddedSet Release Dates Added to /sets EndpointOct 17, 2025
The /sets endpoint now includes the release date of each set. This information is crucial for developers looking to query based on set release dates.
- ChangedSet IDs Standardized and set_name Added to Card ObjectSep 30, 2025
To improve consistency and usability, set IDs have been standardized to use lowercase letters and hyphens instead of spaces and special characters. Furthermore, the set ID now includes the game name to eliminate ambiguity across different games with identical set names. Additionally, a new field
set_namehas been added to the card object to provide the human-readable name of the set. - AddedPayload Reduction Parameters AddedSep 29, 2025
The API has been updated to include new
include_price_historyandinclude_statisticsparameters in the query. These parameters allow users to specify the level of data reduction for the /cards endpoint. The available options are7d,30d,90dandallTime. The default value is a comma-separated list of all the values, which returns the full payload. Theinclude_price_historyoption returns thepriceHistoryarray fields when set totrue. - AddedJavaScript and TypeScript SDKs ReleasedSep 23, 2025[GitHub Repository](https://github.com/justtcg/justtcg-js)
Released official JavaScript and TypeScript SDKs to facilitate easier integration with the API. Check out the official GitHub repository for more details. Install via npm:
npm install justtcgor yarn:yarn add justtcg. - Added90-Day Analytics to /cards EndpointAug 26, 2025
The /cards endpoint has been enhanced with a new suite of 90-day statistical data fields to provide a deeper, quarterly view of market performance. This update is designed to help developers build more sophisticated valuation and trend analysis tools.
Note
This update includes the calculated statistical fields only. The full, point-by-point
priceHistory90dJSON object has been intentionally deferred to a future major release (API v2) to ensure continued API performance and stability for all users. Please see the full API reference for detailed descriptions of each new field. - AddedLanguage Field Added to Variant ObjectAug 12, 2025
Added a new field
languageto the variant object to specify the language of the card. - AddedNew Games AddedAug 10, 2025
Added support for two new games: Grand Archive TCG and Pokemon Japan (
grand-archive-tcg,pokemon-japan). - AddedMulti-Condition and Multi-Printing SupportAug 1, 2025
Added support for querying for multiple conditions (e.g., Near Mint, Lightly Played) and multiple printings (e.g., First Edition, Unlimited). The
cardsendpoint now acceptsconditionandprintingquery parameters that can take multiple values comma-separated. Example:/cards?condition=NM,LP&printing=First Edition,Unlimited.This allows for more granular searches and better filtering of card data. - Changed[BREAKING] Card ID Standardization CompletedJul 11, 2025We recognize this is the second breaking change to Card IDs in a short period, and we sincerely apologize for the inconvenience this causes. JustTCG is experiencing steady adoption, and our developer community is growing every day. We made the difficult but necessary decision to implement this fix now, as delaying it would have exposed a much larger number of developers to this issue in the near future. This update was essential to correctly support cards that exist in multiple rarities, which a few of you had pointed out were missing. We have now stabilized the ID schema, and we are confident this will prevent future breaking changes to these specific identifiers. ---- Should you have any questions, or if you find that re-fetching data has significantly impacted your monthly quota, please contact our support team for assistance.
To more accurately represent card variations, the
idformat forcardsandvariantshas been updated to include the card's rarity. This is a breaking change that primarily affects any application that stores card or variant IDs.- Old ID Format:
game-set-name - New ID Format:
game-set-name-rarity
API consumers must update their code to generate and use the new ID format. All previously stored IDs are now invalid and must be re-fetched or programmatically updated.
- Old ID Format:
- AddedOrderBy Parameters AddedJul 4, 2025
Added support for sorting by price and price changes using the
orderByandorderparameters.orderBycan accept the following values: 'price', '24h', '7d' and '30d'.orderis the direction of the ordering: 'desc' or 'asc'. - Changed[BREAKING] Card ID StandardizationJul 1, 2025
Card IDs now include the full game name. Some IDs with invalid characters have been standardized. Backwards compatibility is maintained for the old game names.
- ChangedRate Limit Policy UpdateJun 14, 2025
API rate limits have been adjusted for free users. See the Rate Limits section for details.
- DeprecatedDeprecated /variants and /cards-search endpointsMay 15, 2025
Deprecated the /variants and /cards-search endpoints. The functionality of these endpoints are merged into the /cards endpoint.
- Addedv1 API LaunchedApr 2, 2025
Version 1 introduces initial endpoints and card structure.