Add or update cards in a list

​

Adds cards to a list, or updates cards already in it, in a single call. Returns the list with its new contents.

Each entry names a catalogue product plus its finish and language. Set quantity to 0 to remove that card. To change an existing line, pass its itemId from a list response.

Every card must belong to the list's game, in a finish and language that product exists in. A single list can hold at most 2000 cards.

Send an Idempotency-Key header to make retries safe.

Requires the lists:write scope.

Path Parameters
  • listId
    Type: string
    min length:  
    1
    required

    The list's id. Path parameter.

Body
required
application/json
  • items
    Type: array object[] 1…1000
    required

    The cards to add or update, up to 1000 per request. A card already in the list — same product, finish, and language — has its quantity replaced, not added to.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/lists/{listId}/items
curl 'https://public-api.cardnexus.com/v1/lists/{listId}/items' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "items": [
    {
      "itemId": "",
      "productId": 50212,
      "finish": "Standard",
      "language": "en",
      "quantity": 0,
      "minCondition": "NM",
      "wantPrice": 0,
      "sellPrice": 0
    }
  ]
}'

{
  "id": "6512a0b4e1d2c3f4a5b6c7d8",
  "name": "Modern deck — missing pieces",
  "game": "mtg",
  "status": "toComplete",
  "description": "Cards I still need for the Modern burn deck.",
  "bannerUrl": "https://ik.imagekit.io/cardnexus/production/mtg/mh2-137-front.png",
  "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",
      "nameSlug": "lightning-bolt",
      "expansion": "Modern Horizons 2",
      "finish": "Standard",
      "language": "en",
      "minCondition": "LP",
      "quantity": 4,
      "quantityFulfilled": 3,
      "wantPrice": 1.75,
      "sellPrice": null
    },
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4e",
      "productId": 50212,
      "name": "Ragavan, Nimble Pilferer",
      "nameSlug": "ragavan-nimble-pilferer",
      "expansion": "Modern Horizons 2",
      "finish": "Foil",
      "language": "en",
      "minCondition": "NM",
      "quantity": 1,
      "quantityFulfilled": 0,
      "wantPrice": 60,
      "sellPrice": null
    }
  ]
}

List updated.