Update an inventory line

Changes a single inventory line — its quantity, condition, language, finish, grading, customId, comment, notes, location, tags, or photos. Send only the fields you want to change. A field this endpoint does not list is rejected with BAD_REQUEST.

finish and language must be ones the product exists in — see the product's finishes and languages on GET /v1/products/{productId}. A finish the product doesn't come in is rejected with INVALID_FINISH; a language it doesn't come in with INVALID_LANGUAGE.

Quantity takes either {"set": n} (new total) or {"adjust": n} (signed change). A change that would leave zero or fewer cards is rejected with INSUFFICIENT_QUANTITY — use DELETE /v1/inventory/{inventoryId} to remove a line.

photos takes the url values of the photos to keep, from the line's photos, in the order you want them: a photo you leave out is removed, and [] removes every photo. A URL that is not on the line returns PHOTO_NOT_FOUND. New photos are uploaded with PUT /v1/inventory/{inventoryId}/media.

location takes a location name, or null to move the line to no location. tags takes {"set": [...]} (replace the whole set, [] clears), {"add": [...]} (add, keep the rest), or {"remove": [...]} (remove only those). location and tags names must already exist — a name that matches none of your labels returns LOCATION_NOT_FOUND or TAG_NOT_FOUND. notes is your private note; pass null to remove it.

count applies the attribute changes to only part of the line. When count is lower than the line's quantity, the line splits: count cards take the changes and come back as line, the rest stays unchanged and comes back as remainder. The split-off part inherits the original line's comment unless you send a new one, and never inherits its customId — send customId to give the new part its own. count needs at least one attribute change and cannot be combined with quantity.

If the changes make this line identical to another of your lines (same product, finish, condition, language, grading, and listing state, neither line carrying a customId), the two merge; line is the surviving line.

Send an Idempotency-Key header to make retries safe: the same key returns the same response for 24 hours.

Requires the inventory:write scope.

Path Parameters

inventoryId
Type: string
min length:
1
required

The inventory line's identifier. Returned by GET /v1/inventory. Path parameter.

Body

application/json

comment
Type:
max length:
2000nullable

Free-text note for the line, shown to buyers on your Marketplace listing. Pass null to remove it.
condition
Type: enum

New condition: NM, LP, MP, HP, or DMG.
values
- NM
  
  Near Mint.
- LP
  
  Lightly Played.
- MP
  
  Moderately Played.
- HP
  
  Heavily Played.
- DMG
  
  Damaged.
count
Type: integer
min:
1
max:
9007199254740991

Apply the attribute changes to only this many cards. When count is lower than the line's quantity, the line splits: count cards take the changes and come back as line, the rest stays unchanged and comes back as remainder. Cannot be combined with quantity.
customId
Type:
min length:
1
max length:
255nullable

Your own stable identifier for this line, unique across your live lines. Pass null to remove it.
finish
Type: stringenum

New finish, e.g. Standard, Foil, Reverse Holo.
values
- Standard
  
  A standard, non-foil card.
- Foil
  
  A foil card.
- Rainbow
- Gold
- Rainbow Foil
- Cold Foil
- Gold Foil
- Etched
  
  A card with an etched-foil finish.
graded
Type: objectnullable

New grading details, or null to turn the line back into a raw card (set condition in the same call).

Properties: 3
language
Type: string
min length:
1

New language, as a two-letter code, e.g. en.
location
Type: string
min length:
1
max length:
100nullable

The location for this line, by name. Must match one of your existing locations. Pass null to move the line to no location.
notes
Type: string
max length:
2000nullable

Private note for the line, visible only to you. Pass null to remove it.
photos
Type: array of string …10Format: uri

The photos to keep on the line, as url values from its photos, in the order you want them. A photo you leave out is removed; [] removes every photo. New photos are uploaded with PUT /v1/inventory/{inventoryId}/media.
quantity

Quantity change: {"set": n} replaces the quantity, {"adjust": n} adds or removes cards — one or the other, never both. A change that would leave zero or fewer cards is rejected — use DELETE /v1/inventory/{inventoryId} to remove a line.
Quantity change: {"set": n} replaces the quantity, {"adjust": n} adds or removes cards — one or the other, never both. A change that would leave zero or fewer cards is rejected — use DELETE /v1/inventory/{inventoryId} to remove a line.
set
Type: integer
min:
1
max:
9007199254740991
required

The line's new total quantity.
tags

How to change the line's tags: {"set": [...]} replaces the whole set ({"set": []} clears them), {"add": [...]} adds without removing others, {"remove": [...]} removes only the ones you name. Choose exactly one. Every name must match one of your existing tags.
How to change the line's tags: {"set": [...]} replaces the whole set ({"set": []} clears them), {"add": [...]} adds without removing others, {"remove": [...]} removes only the ones you name. Choose exactly one. Every name must match one of your existing tags.
set
Type: array of string …50
min length:
1
max length:
100
required

Replace the line's tags with exactly these. Send [] to remove all tags.

Responses

application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json

patch/inventory/{inventoryId}

curl 'https://public-api.cardnexus.com/v1/inventory/{inventoryId}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "quantity": {
    "set": 1
  },
  "condition": "NM",
  "language": "",
  "finish": "Standard",
  "graded": {
    "grade": "9.5",
    "certification": "0084712663",
    "gradingService": "PSA"
  },
  "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
  "comment": "Slight edge wear on the back corner",
  "notes": "Bought at the March show, restock from supplier A",
  "location": "Trade binder",
  "tags": {
    "set": [
      "Trade binder"
    ]
  },
  "photos": [
    ""
  ],
  "count": 1
}'

Show Schema

{
  "line": {
    "id": "665f3a2b1c8d4e9f7a6b5c52",
    "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01-B",
    "comment": "Minor whitening on the bottom edge",
    "notes": "Bought at the March show",
    "location": "Shelf A",
    "tags": [
      "Trade binder",
      "Graded pile"
    ],
    "productId": 50212,
    "game": "ygo",
    "finish": "Standard",
    "condition": "LP",
    "language": "en",
    "quantity": 2,
    "graded": null,
    "forSale": true,
    "listing": {
      "price": {
        "amount": 42.5,
        "currency": "EUR"
      }
    },
    "updatedAt": "2026-06-10T09:15:31.000Z"
  },
  "remainder": {
    "id": "665f3a2b1c8d4e9f7a6b5c4d",
    "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
    "comment": "Minor whitening on the bottom edge",
    "notes": "Bought at the March show",
    "location": "Shelf A",
    "tags": [
      "Trade binder"
    ],
    "productId": 50212,
    "game": "ygo",
    "finish": "Standard",
    "condition": "NM",
    "language": "en",
    "quantity": 3,
    "graded": null,
    "forSale": true,
    "listing": {
      "price": {
        "amount": 42.5,
        "currency": "EUR"
      }
    },
    "updatedAt": "2026-06-10T09:15:31.000Z"
  }
}

Inventory line updated.

Delete an inventory line

Set an inventory line's photos