GE Partner API

Live inventory access for Game Enthusiasts LLC

The GE API provides read access to our live card inventory — Pokémon TCG, Magic: The Gathering, and Topps. All responses are JSON. The base URL for every endpoint is:

https://ge-functions-531174047904.us-central1.run.app/ge-api

Rate Limit: 100 requests per minute per API key. Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Authentication

Every request requires an API key. Pass it one of two ways:

Query parameter

GET /ge-api/products?key=ge_a3f9c2...

Authorization header

GET /ge-api/products
Authorization: Bearer ge_a3f9c2...

Keys are issued after review. Request one below. You can revoke or rotate a key at any time by contacting us.

Errors

Status	Meaning
`200`	Success
`401`	Missing, invalid, or revoked API key
`404`	Resource not found
`405`	Wrong HTTP method
`429`	Rate limit exceeded (100 req/min) — check `X-RateLimit-Reset` header
`500`	Server error — contact us if persistent

Error bodies always follow: { "error": "message" }

List Products

GET/ge-api/products

Returns a paginated list of inventory items. All filters are optional and combinable.

Query Parameters

Param	Type	Description	Default
`q`	string	Case-insensitive name substring search	—
`game`	string	Exact game name: `Pokémon TCG`, `Magic: The Gathering`, `Topps Pokémon`	all games
`set`	string	Exact set name (e.g. `Base Set`, `Scarlet & Violet`)	—
`condition`	string	One or comma-separated: `Near Mint`, `Lightly Played`, `Moderately Played`, `Heavily Played`, `Damaged`	all
`in_stock`	boolean	`true` = available only · `false` = sold out only	all
`foil`	boolean	Filter by holofoil status	all
`reverse_foil`	boolean	Filter by reverse holo status	all
`edition`	string	`1st`, `unlimited`, or `shadowless`	all
`card_number`	string	Exact card number (e.g. "25/165")	—
`featured`	boolean	Filter to featured products only	all
`min_price`	number	Minimum price (USD)	—
`max_price`	number	Maximum price (USD)	—
`sort`	string	`name_asc` · `name_desc` · `price_asc` · `price_desc` · `updated_desc` · `created_desc`	`name_asc`
`limit`	integer	Results per page (max 500)	100
`offset`	integer	Pagination offset	0

Example request

GET /ge-api/products?game=Pok%C3%A9mon%20TCG&in_stock=true&sort=price_asc&limit=20&key=ge_...

Response

{
  "products": [
    {
      "id": "abc123",
      "name": "Charizard",
      "game": "Pokémon TCG",
      "set": "Base Set",
      "cardNumber": "4/102",
      "condition": "Lightly Played",
      "price": 249.99,
      "stock": 1,
      "inStock": true,
      "isFoil": true,
      "isReverseFoil": false,
      "edition": "unlimited",
      "language": "English",
      "rarity": "Rare Holo",
      "images": ["https://..."],
      "inquireOnly": false,
      "updatedAt": 1711234567890
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0,
  "hasMore": true
}

Get Product

GET/ge-api/products/:id

Returns a single product by its Firestore document ID.

Example request

GET /ge-api/products/abc123?key=ge_...

Response

{
  "product": { ...same shape as above... }
}

Returns 404 if the ID does not exist.

Inventory Summary

GET/ge-api/summary

Aggregate stats across the full inventory — useful for dashboards.

Response

{
  "totalListings": 312,
  "inStock": 189,
  "soldOut": 123,
  "byGame": {
    "Pokémon TCG":           { "total": 280, "inStock": 165, "soldOut": 115 },
    "Magic: The Gathering":  { "total": 28,  "inStock": 21,  "soldOut": 7   },
    "Topps Pokémon":         { "total": 4,   "inStock": 3,   "soldOut": 1   }
  },
  "pricing": {
    "averagePrice": 34.50,
    "minPrice": 0.50,
    "maxPrice": 1200.00,
    "totalInventoryValue": 10764.00
  }
}

List Games

GET/ge-api/games

Returns the distinct game names present in the inventory.

Response

{
  "games": ["Magic: The Gathering", "Pokémon TCG", "Topps Pokémon"]
}

List Sets

GET/ge-api/sets

Returns distinct set names. Optionally filter by game.

Param	Type	Description	Default
`game`	string	Filter sets to a specific game	all games

Response

{
  "sets": ["Base Set", "Jungle", "Fossil", "Scarlet & Violet", ...],
  "game": "Pokémon TCG"
}

Bulk Product Lookup

POST/ge-api/products/bulk

Look up multiple products by ID in a single request. Maximum 100 IDs.

Request Body

{
  "ids": ["abc123", "def456", "ghi789"]
}

Response

{
  "products": [ ... ],
  "missing": ["def456"]
}

Recent Sales

GET/ge-api/recent-sales

Returns recently sold items with optional buyer reviews.

Param	Type	Description	Default
`limit`	integer	Number of sales to return (1–100)	20

Response

{
  "sales": [
    { "id": "...", "name": "Charizard ex", "game": "Pokémon TCG", "set": "Obsidian Flames",
      "price": 42.99, "condition": "Near Mint", "soldAt": 1711756800000,
      "buyerReview": { "stars": 5, "text": "Perfect card, fast shipping!" } }
  ],
  "total": 1
}

Webhooks

Register webhook URLs to receive real-time notifications when inventory changes. Webhooks are automatically disabled after 10 consecutive delivery failures.

List Webhooks

GET/ge-api/webhooks

Register Webhook

POST/ge-api/webhooks

Request Body

{
  "url": "https://your-server.com/ge-webhook",
  "events": ["product.created", "product.updated", "product.deleted", "product.sold", "sale.started", "sale.ended"]
}

Webhook Payload (POST to your URL)

{
  "event": "product.created",
  "timestamp": "2026-03-30T12:00:00.000Z",
  "data": { "id": "abc123", "name": "Charizard ex", "game": "Pokémon TCG", ... }
}

Delete Webhook

DELETE/ge-api/webhooks/:id

Rate Limiting

All authenticated endpoints are rate-limited to 100 requests per minute per API key. Rate limit info is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (100)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Seconds until the window resets

When rate limited, the API returns 429 Too Many Requests with a retryAfterMs field.

TCGPlayer Internal API

Admin Only: This section documents TCGPlayer's undocumented public APIs. No API key required — just a User-Agent header. Rate limits apply per domain (IP-based).

Required Header (all requests)

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)

Without this header, all requests return 403 Forbidden.

Product Details

GEThttps://mp-search-api.tcgplayer.com/v1/product/{productId}/details

Returns product name, market price, lowest price, seller count, set info, and card attributes.

Example

GET https://mp-search-api.tcgplayer.com/v1/product/632987/details

{
  "productName": "Team Rocket's Spidops - 187/182",
  "marketPrice": 5.65,
  "lowestPrice": 4.00,
  "lowestPriceWithShipping": 6.21,
  "sellers": 171,
  "listings": 175,
  "setName": "Scarlet & Violet: Paldean Fates",
  "setCode": "PAF",
  "rarityName": "Illustration Rare"
}

Live Listings (condition-specific)

POSThttps://mp-search-api.tcgplayer.com/v1/product/{productId}/listings

Returns active seller listings. Sorted by price+shipping ascending. Supports condition, language, and printing filters.

Request Body

{
  "filters": {
    "term": {
      "sellerStatus": "Live",
      "channelId": 0,
      "condition": ["Near Mint"],
      "language": ["English"],
      "printing": ["Holofoil"]
    },
    "range": { "quantity": { "gte": 1 } },
    "exclude": { "channelExclusion": 0 }
  },
  "from": 0,
  "size": 25,
  "sort": { "field": "price+shipping", "order": "asc" },
  "context": { "shippingCountry": "US", "cart": {} }
}

Filter	Type	Description	Values
`condition`	string[]	Card condition filter	`"Near Mint"`, `"Lightly Played"`, `"Moderately Played"`, `"Heavily Played"`, `"Damaged"`
`language`	string[]	Language filter	`"English"`, `"Japanese"`, etc.
`printing`	string[]	Variant/printing filter	`"Normal"`, `"Holofoil"`, `"Reverse Holofoil"`, `"1st Edition Holofoil"`

Response — each listing

{
  "price": 4.04,
  "shippingPrice": 1.31,
  "sellerName": "House of Reeves",
  "verifiedSeller": true,
  "sellerRating": 100.0,
  "sellerSales": "6444",
  "condition": "Near Mint",
  "printing": "Holofoil",
  "language": "English",
  "quantity": 2,
  "conditionId": 1,
  "productConditionId": 8727978
}

Aggregations Only (get variant counts, no listings)

POSThttps://mp-search-api.tcgplayer.com/v1/product/{productId}/listings

{
  "filters": {
    "term": { "sellerStatus": "Live", "channelId": 0 },
    "range": { "quantity": { "gte": 1 } },
    "exclude": { "channelExclusion": 0 }
  },
  "context": { "shippingCountry": "US", "cart": {} },
  "aggregations": ["listingType"],
  "size": 0
}

Returns condition/language/printing counts without listing data. Useful for discovering available variants.

Latest Sales

POSThttps://mpapi.tcgplayer.com/v2/product/{productId}/latestsales

Returns most recent completed sales. Uses numeric condition IDs (different from listing conditionId).

Request Body

{
  "offset": 0,
  "limit": 25,
  "variants": [],
  "conditions": [1],
  "languages": [1],
  "listingType": "All"
}

Sales Condition IDs

ID	Condition
`1`	Near Mint
`2`	Lightly Played
`3`	Moderately Played
`4`	Heavily Played
`5`	Damaged

Note: Listing conditionId values are different: NM=1, DMG=33, MP=34, HP=35, LP=36. Use name strings for the listings endpoint, numeric IDs only for sales.

Response

{
  "totalResults": 5,
  "data": [
    {
      "condition": "Near Mint",
      "variant": "Holofoil",
      "language": "English",
      "quantity": 1,
      "purchasePrice": 6.57,
      "shippingPrice": 0.00,
      "orderDate": "2026-03-25T07:28:40.547+00:00"
    }
  ]
}

Price History

GEThttps://infinite-api.tcgplayer.com/price/history/{productId}/detailed?range=annual

Returns historical price data. Warning: This domain has the most aggressive rate limiting.

Getting Product IDs

Product IDs can be obtained from:

TCGPlayer Search: mp-search-api.tcgplayer.com/v1/search/request?q={query} — returns productId in results
TCGPlayer URLs: e.g. tcgplayer.com/product/632987 — the number is the productId

Rate Limiting

Caution: Each domain (mp-search-api, mpapi, infinite-api) has independent IP-based rate limits. The history API is the most restrictive. For our scanner use case (individual card lookups), limits are unlikely to be hit. Avoid bulk scraping.

Request API Key

Submit your details below. Requests are reviewed manually — you'll be contacted at your email once approved.

Partner / Company Name Required

Contact Email Required

Use Case Optional