Update an inventory line

​

Changes a single inventory line — its quantity, condition, language, finish, grading, customId, comment, notes, location, or tags. Send only the fields you want to change.

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.

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: string ·
    max length:  
    2000    nullable

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

    Free-text note attached to this inventory line. Buyers see it when they view your listing.

  • condition
    Type: string · 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: string ·
    min length:  
    1
    max length:  
    255    nullable

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

    Your own stable identifier for this inventory line, unique across your live lines. CardNexus never modifies it.

  • finish
    Type: string enum

    New finish, e.g. Standard, Foil, Reverse Holo.

    values
    • Standard

      A standard, non-foil card.

    • Foil

      A foil card.

    • Rainbow
    • Gold
    • Rainbow Foil
  • graded
    Type: object nullable

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

  • language
    Type: string
    min length:  
    1

    New language, as a two-letter code, e.g. en.

  • location
    Type: string
    min length:  
    1
    max length:  
    100    nullable

    The location for this line, by name. Must match one of your existing locations. Pass null to move the line to no location.

    The label's name. Matched case-insensitively, with surrounding spaces ignored — Shelf A and shelf a are the same label.

  • notes
    Type: string
    max length:  
    2000    nullable

    Private note for the line, visible only to you. Pass null to remove it.

    Private free-text note attached to this inventory line, visible only to you. Never shown to buyers.

  • 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 string[] …50
      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
Request Example for 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"
    ]
  },
  "count": 1
}'

{
  "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.