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.
Notice: The card-search and variants endpoints are deprecated and will be phased out over time. Please migrate to the cards endpoint, which now supports both searching and direct lookups. This change is part of our effort to provide a more intuitive and seamless API experience. For most use-cases, you only need to use the games, sets, and cards endpoints.

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.

API Key Authentication

Include your API key in the request headers:

x-api-key:tcg_your_api_key_here
Keep your API key secure and never expose it in client-side code.
If you suspect your API key has been compromised, regenerate it immediately.

API Reference

API Architecture Update: Our API is now 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 an id, the endpoint serves as a flexible search.

The updated architecture is simple: use games and sets to discover, and cards for both searching and direct lookups. Direct lookups are triggered by passing an id. If no id is passed, the cards endpoint acts as a search endpoint.

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 card-specific endpoints.

Get All Games

GET

Returns a list of all supported trading card games.

https://api.justtcg.com/v1/games
curl -X GET "https://api.justtcg.com/v1/games" \
  -H "X-API-Key: your_api_key_here"

Get Sets

GET

Returns a paginated list of sets for a specific game.

https://api.justtcg.com/v1/sets

Query Parameters

Name
Type
Required
Description
game
string
Required
Game ID (e.g., mtg, pokemon)
curl -X GET "https://api.justtcg.com/v1/sets?game=mtg" \
  -H "X-API-Key: your_api_key_here"

Direct Lookups

These high-performance endpoints provide rapid access to card data when you already have identifier values. For the best performance when retrieving specific cards, use these endpoints with TCGplayer IDs obtained from the browsing endpoints.

Quick tip: Use "Card by ID" for retrieving all variants of a single card. Use "Variant Lookups" when you need specific variant information by its unique variantId for ultra-fast performance. The variantId is the primary key in our database structure, making lookups extremely efficient.

Card by ID

GET

Retrieve a card and all its variant prices by TCGplayer ID. You can optionally filter the returned variants by condition and printing type.

https://api.justtcg.com/v1/cards

Query Parameters

Name
Type
Required
Description
tcgplayerId
string
Required
TCGplayer ID of the card
printing
string
Optional
Filter by printing type (e.g., "Normal", "Foil")
condition
string
Optional
Filter by condition (e.g., "Near Mint", "Lightly Played")
curl -X GET "https://api.justtcg.com/v1/cards?tcgplayerId=25788&condition=Near%20Mint&printing=1st%20Edition" \
  -H "X-API-Key: your_api_key_here"

Batch Card Lookup

POST

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

Send an array of objects, each containing the following properties:

Property
Type
Description
tcgplayerId
string
TCGplayer ID of the card
printing
string
Optional: Filter by printing type (e.g., "Normal", "Foil")
condition
string
Optional: Filter by condition (e.g., "Near Mint", "Lightly Played")
curl -X POST "https://api.justtcg.com/v1/cards" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "tcgplayerId": "25788",
      "condition": "Near Mint",
      "printing": "1st Edition"
    },
    {
      "tcgplayerId": "514475",
      "condition": "Near Mint",
      "printing": "Foil"
    }
  ]'

Get Single Variant (Deprecated)

GET

[DEPRECATED] The /variants endpoint is deprecated and will be phased out over time. Please use the /cards endpoint for all direct lookups and variant retrieval. The /cards endpoint now supports all previous functionality and more.

https://api.justtcg.com/v1/variants
Deprecation Notice: The card-search and variants endpoints are now deprecated. They will continue to work for existing users, but we recommend migrating to the cards endpoint for all search and lookup use-cases. This change simplifies the API and ensures a more consistent experience.

Query Parameters

Name
Type
Required
Description
variantId
string
Required
Unique variant ID for the specific card variant
curl -X GET "https://api.justtcg.com/v1/variants?variantId=yugioh-force-of-the-breaker-lich-lord,-king-of-the-underworld_near-mint_1st-edition" \
  -H "X-API-Key: your_api_key_here"

Batch Variant Lookup (Deprecated)

POST

[DEPRECATED] The /variants endpoint is deprecated and will be phased out over time. Please use the /cards endpoint for all direct lookups and variant retrieval. The /cards endpoint now supports all previous functionality and more.

https://api.justtcg.com/v1/variants
Deprecation Notice: The card-search and variants endpoints are now deprecated. They will continue to work for existing users, but we recommend migrating to the cards endpoint for all search and lookup use-cases. This change simplifies the API and ensures a more consistent experience.

Request Body

Send an array of objects, each containing the following property:

Property
Type
Description
variantId
string
Unique variant ID for the specific card variant
curl -X POST "https://api.justtcg.com/v1/variants" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "variantId": "yugioh-egyptian-god-deck-slifer-the-sky-dragon-lair-of-darkness_near-mint_foil"
    },
    {
      "variantId": "magic-murders-at-karlov-manor-case-of-the-stashed-skeleton_played_normal"
    }
  ]'

Card Objects

The Card object contains detailed information about a trading card, including its variants with pricing information.

Card Structure

Every card in our database has a standard structure that includes basic card information and an array of variants.

Card Properties

Property
Type
Description
id
string
Unique identifier for the card
name
string
Name of the card
game
string
Game identifier (e.g., "Pokemon", "mtg")
set
string
Name of the set the card belongs to
number
string
Card number within the set
tcgplayerId
string
TCGplayer product ID
rarity
string
Rarity of the card (e.g., "Common", "Rare", "Promo")
details
object | null
Additional card-specific details (optional)
variants
array
Array of variant objects with pricing information
Cards don't directly contain pricing information. Instead, pricing is stored in variant objects within the "variants" array.

Variant Structure

Each variant represents a specific combination of condition and printing for a card, with its associated price.

Variant Properties

Property
Type
Description
id
string
Unique identifier for this specific variant
condition
string
Condition of the card (e.g., "Near Mint", "Lightly Played")
printing
string
Printing type (e.g., "Normal", "Foil")
price
number
Current price in USD
lastUpdated
number
Unix timestamp (in seconds) of when the price was last updated

Example Card Object

{
  "id": "pokemon-battle-academy-fire-energy-22-charizard-stamped",
  "name": "Fire Energy (#22 Charizard Stamped)",
  "game": "Pokemon",
  "set": "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
    }
  ]
}

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.

Variant IDs

Each variant has a unique id which serves as the primary key in our database. The variant ID is structured as card-id_condition_printing and can be used for direct, high-performance lookups using the /variants endpoint. If you already have the variant ID, using it directly is the fastest way to retrieve pricing information.

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 and a meta field with API usage statistics.

Response Structure

Field
Type
Description
cards
array
The requested data. An array of card objects.
meta
object
Metadata about the response, including pagination details.
meta.total
integer
Total number of cards available for this query.
meta.limit
integer
Total results to limit this query to.
meta.offset
integer
The current offset for these results.
meta.hasMore
boolean
Indicates if there are more pages available for this query.
_metadata
object
API usage metadata and rate limit information included with each response.
_metadata.apiPlan
string
The name of your current API subscription plan.
_metadata.apiRequestLimit
integer
Total number of API requests allowed for your plan.
_metadata.apiRequestsUsed
integer
Number of API requests you have used so far.
_metadata.apiRequestsRemaining
integer
Number of API requests remaining before you reach your total limit.
_metadata.apiDailyLimit
integer
Maximum number of API requests allowed per day.
_metadata.apiDailyRequestsUsed
integer
Number of API requests used today.
_metadata.apiDailyRequestsRemaining
integer
Number of API requests remaining for today.
_metadata.apiRateLimit
integer
Maximum number of requests allowed per minute.
_metadata.error
string
Detailed error message if an error occurred, otherwise null.
_metadata.code
string
Error code indicating the type of error, if applicable.

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

Status Code
Error Type
Description
400
Bad Request
The request was malformed or missing required parameters.
401
Unauthorized
Missing or invalid API key.
403
Forbidden
Valid API key, but insufficient permissions for the requested resource.
404
Not Found
The requested resource could not be found.
429
Too Many Requests
Rate limit exceeded. Slow down your requests.
500
Server Error
An unexpected error occurred on the server.

Error Response Format

All error responses follow a consistent format with an error object containing details about the error.

{
  "error": {
    "code": "invalid_card_id",
    "message": "The provided TCGplayer ID does not exist in our database.",
    "status": 404,
    "details": {
      "tcgplayerId": "999999999"
    }
  },
  "meta": {
    "api_calls_used": 1,
    "api_calls_remaining": 99991
  }
}

Common Error Codes

Error Code
Description
invalid_api_key
The API key provided is invalid or has been revoked.
missing_required_param
A required parameter is missing from the request.
invalid_card_id
The provided card ID does not exist in our database.
invalid_game_id
The provided game ID does not exist or is not supported.
invalid_set_id
The provided set ID does not exist in our database.
rate_limit_exceeded
You have exceeded your rate limit. Please slow down your requests.
usage_limit_exceeded
You have exceeded your monthly API usage limit. Please upgrade your plan.
Pro tip: We recommend implementing error handling that gracefully retries requests in case of temporary server errors (500 status codes) or rate limiting (429 status codes), with exponential backoff for best results.

Code Examples

Practical examples showing how to integrate the JustTCG API in real-world scenarios.

Price Sync for Inventory
Automatically fetch and update prices for all cards in a specific set
// 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 = 50;
  
  // Keep fetching until we've got all cards
  while (hasMoreResults) {
    try {
      // Create URL with query parameters
      const url = new URL(`${BASE_URL}/cards-search`);
      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('mtg', 'mh2');
Product Page Display
Fetch card data for a product page using batch lookup for better performance
// 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}`);
      
      // 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(['123456', '789012', '345678']);
Shopping Cart Calculation
Calculate the total for a shopping cart with specific card variants
// 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}/variants`, {
      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.price;
      total += subtotal;
      
      console.log(
        `${item.card.name} (${item.condition}, ${item.printing}): $${item.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: '123456', condition: 'Near Mint', printing: 'Foil' },
//   { tcgplayerId: '789012', condition: 'Lightly Played', printing: 'Normal' }
// ]);

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

Plan
Monthly Limit
Rate Limit
Starter
10,000 requests
20 requests/second
Professional
50,000 requests
50 requests/second
Enterprise
500,000 requests
100 requests/second
If you exceed your rate limit, the API will return a 429 Too Many Requests response. If you exceed your monthly limit, you'll need to upgrade your plan to continue using the API.

Reset Times: Daily rate limits reset at midnight (00:00) UTC. Monthly usage limits reset on the first day of each month at midnight (00:00) UTC.

Support

If you have any questions or need help with the API, please contact our support team.