/api/v1/inventory read:inventory Searches your whole inventory: raw cards and graded slabs together in one list, one ordering and one total. By default it shows what you hold right now (status OFFCHAIN); cards on an order, shipped or withdrawn appear only when you ask for them with ?status=. Use it to build an inventory screen or a report — "my basketball cards filed under PrizePicks that arrived last week, most valuable first". Every row is the same card object List cards returns, plus the card’s status, so one parser reads both endpoints. List cards stays the tool for reconciliation: it sweeps one stream in the order cards became visible, with a drift-free cursor. This endpoint pages by offset and sorts however you ask, so rows can shift between pages while cards are arriving; for a complete, drift-free copy of your inventory, sweep List cards instead. Every filter is validated: a value we do not recognise returns 400 naming the valid ones, never an empty list that looks like missing inventory. Filters combine with AND; the values inside one comma-separated filter combine with OR.
When a raw-card response includes identity and pricing, use their status fields to interpret it. An unconfirmed identity has null market and insured prices; declared_value remains separate. A returned card is not automatically verified or eligible for a quote or order. Intake-held, REMOVED and other-account cards remain excluded; existing graded publication controls still apply.
Start a full sweep with GET /cards?type=raw&since=0 (or type=all for both streams), then pass each returned cursor unchanged. Upsert by unique_id and repeat full sweeps to refresh existing identity and pricing. since is a visible-sequence cursor, not an updated_at change feed. Historical rows newly included by a visibility-policy change can be behind a saved cursor; a real identity publication can return the same unique_id again. Reading inventory generates no receipt or confirmation events and changes no publication timestamp. GET /inventory/events alone does not guarantee historical-card or catalog-price updates.
Uses the same raw visibility policy as List cards and Get card, with the requested search/status filters applied to both rows and pagination.total. Released pending OFFCHAIN raw cards can appear when included by the account visibility policy; intake-held, REMOVED, other-owner and unpublished graded cards remain excluded. Slab photograph/certificate controls remain in force.
Grade filters narrow to slabs. With the default type=all, setting grading_company, min_grade or max_grade returns graded cards only, because a raw card has neither.
Sorting and filtering happen across both kinds at once, so one page can hold raw cards and slabs side by side. Branch on each row’s type, not on the page.
Offset paging reflects the inventory as it is when each page is read. If cards arrive or ship while you page, a card can move between pages. Re-run from offset 0 to refresh a view, and use List cards with ?since when you need every card exactly once.
A card that comes back to us on a returned order — the carrier could not deliver it and the order is now RETURNED (see Get order) — is OFFCHAIN again from the moment the warehouse scans it out of the package: it is in this endpoint’s default view, still filed under the same sub_account, and can be ordered, transferred or withdrawn like any other card. A card the order listed that was not in the package stays REDEEMED. The activity log announces each one as card.returned.
GET /api/v1/inventory?limit=10 These inputs are shared across all docs pages, so an id entered here carries over.
Not run yet. Press Run to make a live call against https://service.rip.fun (through this demo's server-side proxy; the API key never reaches the browser).
curl -X GET 'https://service.rip.fun/api/v1/inventory?limit=10' \ -H 'X-API-Key: rip_…'
| Field | Type | Required | Description |
|---|---|---|---|
type | query string | — | `raw` | `graded` | `all` (default). Unlike List cards, the default here is all of it |
category | query string | — | `tcg` | `sports` |
game | query string | — | Comma-separated: pokemon, onepiece, basketball, baseball, football, soccer, hockey, other. Case, spaces, hyphens and underscores are ignored, so `One Piece` and `one-piece` both mean onepiece. Matches exactly the rows whose `game` field has that value. A game from the other category than ?category= is a 400 |
sub_account | query string | — | Comma-separated sub-account slugs, plus `main` for cards in your own inventory and `all` for no filter. `sub_account=prizepicks,main` is PrizePicks cards and your own, without your other sub-accounts. Matched case-insensitively; an unknown slug is a 400 listing yours. Read the slugs from GET /sub-accounts |
status | query string | — | Comma-separated, case-insensitive: `OFFCHAIN` (in the vault — the only status you can order, transfer or withdraw), `PENDING_REDEEM` (on a committed order, being packed), `REDEEMED` (shipped on an order; a card the carrier brings back to us on a RETURNED order goes back to `OFFCHAIN` once the warehouse scans it in), `PENDING_WITHDRAWAL` (on an open withdrawal), `SHIPPED_OUT` (withdrawn, shipped back to you). Omitted, you get `OFFCHAIN` only — the cards you hold right now — so a plain call is your current inventory. Pass other statuses to see cards on orders or already shipped, or `status=all` for every status (on its own, not combined with others) |
created_from / created_to | query string | — | Intake date range on created_at, both ends inclusive. A date (`2026-09-01`) is the whole UTC day, so created_from=2026-09-01&created_to=2026-09-30 is all of September. A date-time must carry its zone (`2026-09-01T14:00:00Z` or `…-05:00`); one without a zone is a 400 rather than a guess. created_to earlier than created_from is a 400 |
q | query string | — | Case-insensitive text search, 2–100 characters, matched anywhere in the card name or player name, team, set name, card number, unique_id and, on slabs, the cert number. `%` and `_` are matched literally |
set_id | query string | — | Exact TCG catalog set id, e.g. `sv3pt5`. Sports cards have no catalog set id — search their set name with q |
inbound_shipment_id | query int | — | Only the cards and slabs that came out of one package — the id of an inbound shipment you announced. See inbound_shipment on List cards |
year_from / year_to | query int | — | Inclusive range on the `year` field: set release year for TCG, season start year for sports (a 2023-24 card is 2023) |
min_value_cents / max_value_cents | query int | — | Inclusive range on declared_value.amount_cents. A card with no declared value is excluded when either bound is set, not treated as $0 |
grading_company | query string | — | Comma-separated, case-insensitive: PSA, CGC, BGS, TAG, …. Slabs only (see notes) |
min_grade / max_grade | query string | — | Inclusive grade range as written: `9`, `9.5`, `10`, up to `10.5`. Slabs only (see notes). A slab whose grade we could not resolve never matches a grade range |
sort | query string | — | `created_at` (default), `declared_value` or `name` (card name, or player name for sports). Cards with no value or no name sort last in either direction; ties fall back to newest first |
order | query string | — | `asc` | `desc`. Defaults to `desc` for created_at and declared_value, `asc` for name |
limit | query int | — | 1..100, default 50 |
offset | query int | — | 0..10_000, default 0 |
data)| Field | Description |
|---|---|
cards[].identity | Optional metadata on RAW-card responses: { status, published_at, blockers }. status is "unconfirmed" while identity_published_at is null, "confirmed" when published, or "unknown" if the deployment cannot track publication. published_at is the actual ISO 8601 timestamp or null; it is never fabricated. The pending blocker is "identity_not_published". A sports.record_status of "canonical" alone does not establish publication |
cards[].pricing | Optional metadata on RAW-card responses: { status, market_price, currency, blockers }. status is "unverified" for pending identity, "unpriced" for published identity without a catalog price, or "priced" when a catalog price is available. market_price is a USD decimal string or null, never declared_value. Pending identity always returns null with blocker "identity_not_published"; missing catalog price returns null with "missing_market_price". priced reports an available catalog price, not a new live appraisal. On a card from a box announced with declared-value bounds, market_price is clamped into those bounds — see the declared-value bounds note |
cards[] | The same card object List cards returns — unique_id, card_id, category, game, energy_types, name, card_number, set_name, release_date, year, image_url, scan_image_url, insured_price, declared_value, created_at, updated_at, sub_account, sports (sports rows only), type and graded (slabs only), inbound_shipment, language, language_code, tcgplayer_id, series, supertype, subtypes, rarity, in the same key order. See List cards for every field |
cards[].status | Where the card is right now: OFFCHAIN, PENDING_REDEEM, REDEEMED, PENDING_WITHDRAWAL or SHIPPED_OUT — see ?status= above. Appended as the last key, after everything List cards returns |
pagination | { limit, offset, total, has_more }. total counts every card matching your filters across all pages. has_more is true while another page exists |
| Status | Code | When |
|---|---|---|
| 400 | Invalid <filter> | a filter value is not recognised or out of range — message names the filter (Invalid game, Invalid status, Invalid created_from, …) and error lists the valid values or the accepted format. Also when a filter is repeated (?game=a&game=b): send one value, comma-separated |
| 400 | Invalid status | a status that is not one of the five above or `all`, or `all` combined with other statuses |
| 400 | Invalid type | grading_company, min_grade or max_grade was combined with type=raw — a raw card has no grade, so that query could only ever be empty |
| 400 | Invalid sub_account | a slug your account does not have (the message lists yours, retired included) |
| 403 | Insufficient permissions | the key lacks read:inventory |
| 403 | Tenant API key required | key is not tenant-scoped |
See Errors for the response envelope and the full code list.