Conventions

Product identity

Treat a BinderDex product ID as an opaque string. Do not parse meaning from it or manufacture IDs from product names. Names may change; an external marketplace ID is an alias within a named namespace.

Use game: pokemon or game: one_piece and kind: card or kind: sealed. Both kinds include language and market; the initial proposal targets English-language, US-market products.

For a card, check the set, collector_number, and printing. A collector number or name alone does not distinguish alternate art, reprints, or editions. Distinct verified printings have distinct product IDs. Condition and finish are separate price selections; they do not change the card’s identity.

Choose the exact variant and condition pair from a card’s price_options. Variant names are explicit catalog values, not strings to guess from card art. Supported condition labels in the draft are near_mint, lightly_played, moderately_played, heavily_played, damaged, and ungraded. An enum value is not a claim of coverage. ungraded is a source’s condition-unspecified raw reference; it does not mean Near Mint and is not a graded-card price.

For sealed products, check edition, package type, units per package, unit kind, and factory-sealed condition. A six-pack bundle and a six-box case are different sellable units. Persist an ID only after checking the fields relevant to that kind.

Price selections

The batch body contains items. Each card selection requires kind, product_id, variant, and condition. Each sealed selection requires only kind and product_id. There are no implicit card variant or condition defaults. Each result echoes the complete selection in input order.

A batch accepts 1–50 distinct selections. The same card with two different conditions is allowed; repeating the exact same selection is a 400, even if its JSON properties appear in a different order. A well-formed selection for an unsupported variant/condition or mismatched product kind returns a per-item missing result with unsupported_selection; it never falls back to another price.

Money

Prices use an integer amount_cents and an explicit currency. The initial proposal supports USD only. For example, 2799 USD cents represents $27.99. Use integer arithmetic; format dollars only for display. A legitimate zero amount is different from a missing value.

Do not apply implicit currency conversion, condition multipliers, or pack-to-box price multiplication. Those operations would introduce assumptions the response does not support.

Time

Timestamps use UTC with a Z suffix. The relevant clocks are separate:

• catalog_updated_at: when the catalog record changed.
• source_as_of: the observation time supplied by a trustworthy source, or null when unknown.
• collected_at: when the observation was collected.
• snapshot_at: the snapshot used for the response.

Collection time does not prove source freshness. Where source time is known, the intended ordering is source_as_of ≤ collected_at ≤ snapshot_at. Future-dated or inconsistent observations should not be published.

Missing values

Required nullable fields appear explicitly as null. An absent optional field does not mean zero, false, or an empty string. A missing price includes a reason; consumers should preserve that distinction.

New response fields may be added during development. Ignore fields you do not use and handle an unfamiliar status safely by requesting manual review. Requests use the documented field names; unknown or repeated query parameters are rejected in the proposal.

Pagination

Catalog pages use an opaque cursor, not an offset. The proposed limit is 1–50, with a default of 20. Continue with pagination.next_cursor until it is null.

The optional game and kind filters narrow the catalog; omitting them includes both proposed games and product kinds. Combine them with tcgplayer_id for an exact external alias lookup. A lookup may return multiple candidates; verify each identity rather than accepting the first one.

Keep all original filters and the limit when following a cursor. The draft cursor belongs to the authenticated organization, its filters, and a fixed catalog snapshot. It expires after 15 minutes; an expired cursor requires starting a new traversal. A total count is not promised.

These are proposed integration conventions. See the reference for exact schemas and availability for the current release boundary.