Lists

A list is a named collection of cards you build for a purpose — a deck you're assembling, a want list you're chasing, or a batch of cards you're offering for sale. Each list belongs to one game, holds a set of cards, and tracks how complete it is.

{
  "id": "6512a0b4e1d2c3f4a5b6c7d8",
  "name": "Modern deck — missing pieces",
  "game": "mtg",
  "status": "toComplete",
  "description": "Cards I still need for the Modern burn deck.",
  "completionPercentage": 64,
  "itemCount": 2,
  "totalQuantity": 5,
  "isPublic": false,
  "currency": "USD",
  "defaultMinCondition": "NM",
  "defaultLanguage": "en",
  "createdAt": "2026-03-11T09:15:00.000Z",
  "updatedAt": "2026-06-28T14:02:47.000Z",
  "items": [
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4d",
      "productId": 71044,
      "name": "Lightning Bolt",
      "expansion": "Modern Horizons 2",
      "finish": "Standard",
      "language": "en",
      "minCondition": "LP",
      "quantity": 4,
      "quantityFulfilled": 3,
      "wantPrice": 1.75,
      "sellPrice": null
    }
  ]
}

What a list holds

Field	Type	Description
`id`	string	Stable opaque identifier for the list. Don't parse it.
`name`	string	The list's name.
`game`	string	The game the list belongs to, as a slug, e.g. `pokemon`.
`status`	string	`forSale`, `toComplete`, or `hold` — see Statuses.
`description`	string \| null	Your free-text note on the list. `null` when there is none.
`completionPercentage`	number	How complete the list is, from 0 to 100.
`itemCount`	number	How many distinct lines the list holds.
`totalQuantity`	number	The sum of every line's quantity.
`isPublic`	boolean	`true` when anyone with the link can view the list.
`currency`	string	The currency your `wantPrice` and `sellPrice` values are in, as an ISO 4217 code.
`defaultMinCondition`	string \| null	The minimum condition applied to new cards when you don't set one.
`defaultLanguage`	string \| null	The language applied to new cards when you don't set one.
`createdAt`	string	When the list was created, ISO 8601 UTC.
`updatedAt`	string	When the list was last modified, ISO 8601 UTC.
`items`	array	Every card in the list — see What a card holds.

Only GET /v1/lists/{listId} returns items. The list collection endpoint omits them.

What a card holds

Each entry in items is one product in one set of attributes:

Field	Type	Description
`id`	string	Stable opaque identifier for this line in the list.
`productId`	number	The catalogue product. Returned by `POST /v1/products/search`.
`name`	string	The product's name, e.g. `Lightning Bolt`.
`expansion`	string \| null	The name of the product's expansion.
`finish`	string	The card's finish, e.g. `Standard`, `Foil`, `Reverse Holo`.
`language`	string \| null	The card's language as a short code, e.g. `en`.
`minCondition`	string \| null	The minimum condition you'll accept: `NM`, `LP`, `MP`, `HP`, or `DMG`.
`quantity`	number	How many copies this line calls for.
`quantityFulfilled`	number	How many of the wanted copies you already hold, worked out from your inventory. Read-only.
`wantPrice`	number \| null	Your target price per copy, in the list's currency.
`sellPrice`	number \| null	Your sale price per copy, in the list's currency.

Statuses

Status	Meaning
`forSale`	Cards you're offering for sale.
`toComplete`	Cards you're working to complete, such as a want list or a deck in progress.
`hold`	Cards you're keeping aside.

Scopes

List endpoints require an API key with the matching scope:

Scope	Grants
`lists:read`	Read your lists and the cards in them.
`lists:write`	Create, update, and delete lists, and add or remove cards.

See Authentication for how scopes attach to a key.

Managing lists

GET /v1/lists returns your lists without their cards, paginated with offset and limit. Filter by game, status, isPublic, and name.
POST /v1/lists creates a new, empty list.
GET /v1/lists/{listId} returns a single list in full, including its cards.
PATCH /v1/lists/{listId} changes a list's settings. Send only the fields you want to change.
DELETE /v1/lists/{listId} deletes a list and every card in it. Your inventory is not affected.

curl https://public-api.cardnexus.com/v1/lists \
  -H "Authorization: Bearer cnk_live_your_key"

Managing cards

Add cards, change them, or remove them with POST /v1/lists/{listId}/items. Each entry names a catalogue product plus its finish and language. A card already in the list — same product, finish, and language — has its quantity replaced. Set quantity to 0 to remove a card, and pass an existing line's itemId to update it in place.

curl https://public-api.cardnexus.com/v1/lists/6512a0b4e1d2c3f4a5b6c7d8/items \
  -X POST \
  -H "Authorization: Bearer cnk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1e9c2a-8b3d-4e7a-9c1b-2f5a7d0e4c3b" \
  -d '{
    "items": [
      { "productId": 71044, "finish": "Standard", "language": "en", "quantity": 4, "minCondition": "NM", "wantPrice": 1.75 }
    ]
  }'

To remove a single card by its line id, use DELETE /v1/lists/{listId}/items/{itemId}.

Every card must belong to the list's game, and a single list can hold at most 2000 cards.

Products — find the productId for a card
Inventory — the stock your lists' fulfillment is worked out from
Authentication — how API keys and scopes work

Inventory webhooks

Sync inventory