Introducing Stable UUIDs

As the trading card game ecosystem scales, the applications built on top of our pricing data have grown significantly. We are increasingly seeing the JustTCG API power live e-commerce storefronts, high-frequency inventory management systems, and production-level card marketplaces. When your daily business operations depend on data consistency, minor text shifts cannot be allowed to break your local database relations.

To support the high-stakes applications being built with our data, we are introducing permanent, stable UUIDs across our entire data layer. This change hardens our infrastructure and lays the essential groundwork for the upcoming release of JustTCG v2.

The Evolution from Slugs to Stable IDs #

When we launched JustTCG, we relied on human-readable text slugs as our primary identifiers (such as pokemon-legendary-treasures-booster-box). Slugs were a deliberate choice for early-stage development. They made it simple to prototype, allowed developers to diagnose issues quickly without constant database cross-references, and kept our initial architecture incredibly lightweight.

However, as our platform has matured and our customer base has grown immensely, text slugs are no longer sufficient as unique production keys. Slugs are inherently tied to card titles. In the TCG world, upstream data from publishers and market feeds frequently changes to fix typos, update punctuation, or correct formatting post-release. If an upstream name changes, a derived slug changes with it.

For an online storefront or an inventory tracker storing these slugs as foreign keys, an upstream typo fix can break local historical tracking. Stable UUIDs solve this permanently. Each UUID is deterministically generated from the immutable underlying identity of the card itself. It remains rock-solid and completely unchanged, even if a display name or text slug is corrected upstream.

Seamless Integration #

We want to professionalize our identifier layer without cluttering our API surface or creating tedious integration work for your engineering team. Instead of adding a separate query parameter or forcing a structural migration, we made our existing cardId and variantId parameters intelligent.

The API automatically detects the format of the identifier you provide. If you pass a classic text slug, the system resolves it using slug logic. If you pass a UUID, it instantly executes an exact point lookup.

// Fetch data using a human-readable slug  
GET /cards?cardId=pokemon-legendary-treasures-legendary-treasures-booster-box  
  
// Fetch the exact same data using the new stable UUID  
GET /cards?cardId=907005b3-b7bd-5eac-aed9-d20454b7fe8a

This polymorphic routing behavior works identically inside single lookups, search parameters, and high-volume batch requests.

Backward Compatible and Ready for v2 #

This update is entirely additive and fully backward compatible. Every existing field in our payload remains completely unchanged, meaning your production systems will continue to run with zero code breakages.

Stable UUID fields are live in all production API responses today. You can begin storing these keys in your local databases immediately to ensure absolute relationship stability before the wider release of the JustTCG v2 ecosystem. Review the core documentation updates to see the updated payload schemas and verify your integrations.