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/v1
Authentication
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_here
SDK 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/games
Response Object
Sets
Retrieve a list of all sets.
https://api.justtcg.com/v1/sets
Query Parameters
Filter by game ID (e.g., mtg
, pokemon
).
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/cards
Note: The tcgplayerId
, cardId
or variantId
will take precedence over any search query if any of those are provided.
Query Parameters
TCGplayer ID of the card.
Filter by printing type (e.g., Normal
, Foil
).
Filter by condition:
Sealed
Near Mint
Lightly Played
Moderately Played
Heavily Played
Damaged
Or abbreviations:
S
NM
LP
MP
HP
DMG
You can specify a single value (e.g., NM
) or a comma-separated list (e.g., NM,LP,HP
) to filter for multiple conditions.
Include price history data in the response.
Specify which timeframe statistics to include in the response. Defaults to all timeframes.
Options:
7d
30d
90d
1y
allTime
You can provide a comma-separated list (e.g., 7d,30d,1y
) to include multiple statistics.
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/cards
Request Body Parameters
Send an array of objects, each containing the following properties:
TCGplayer ID of the card.
Card ID of the card.
Variant ID of the card.
Filter by printing type (e.g., Normal
, Foil
).
Filter by condition:
Sealed
Near Mint
Lightly Played
Moderately Played
Heavily Played
Damaged
Or abbreviations:
S
NM
LP
MP
HP
DMG
You can specify a single value (e.g., NM
) or a comma-separated list (e.g., NM,LP,HP
) to filter for multiple conditions.
variantId
will take precedence over tcgplayerId
and tcgplayerId
will take precedence over 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
- ChangedSet IDs Standardized and set_name Added to Card Object2025-09-30
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_name
has been added to the card object to provide the human-readable name of the set. - AddedPayload Reduction Parameters Added2025-9-29
The API has been updated to include new
include_price_history
andinclude_statistics
parameters in the query. These parameters allow users to specify the level of data reduction for the /cards endpoint. The available options are7d
,30d
,90d
andallTime
. The default value is a comma-separated list of all the values, which returns the full payload. Theinclude_price_history
option returns thepriceHistory
array fields when set totrue
. - AddedJavaScript and TypeScript SDKs Released2025-09-23[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 justtcg
or yarn:yarn add justtcg
. - Added90-Day Analytics to /cards Endpoint2025-08-26
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
priceHistory90d
JSON 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 Object2025-08-12
Added a new field
language
to the variant object to specify the language of the card. - AddedNew Games Added2025-08-10
Added support for two new games: Grand Archive TCG and Pokemon Japan (
grand-archive-tcg
,pokemon-japan
). - AddedMulti-Condition and Multi-Printing Support2025-08-01
Added support for querying for multiple conditions (e.g., Near Mint, Lightly Played) and multiple printings (e.g., First Edition, Unlimited). The
cards
endpoint now acceptscondition
andprinting
query 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 Completed2025-07-11We 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
id
format forcards
andvariants
has 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 Added2025-07-04
Added support for sorting by price and price changes using the
orderBy
andorder
parameters.orderBy
can accept the following values: 'price', '24h', '7d' and '30d'.order
is the direction of the ordering: 'desc' or 'asc'. - Changed[BREAKING] Card ID Standardization2025-07-01
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 Update2025-06-14
API rate limits have been adjusted for free users. See the Rate Limits section for details.
- DeprecatedDeprecated /variants and /cards-search endpoints2025-05-15
Deprecated the /variants and /cards-search endpoints. The functionality of these endpoints are merged into the /cards endpoint.
- Addedv1 API Launched2025-04-02
Version 1 introduces initial endpoints and card structure.