Listings

A listing is an inventory line published to the Marketplace at a per-card price. Listing operations move cards between your Collection and the Marketplace and set their price; they never change the product, condition, or other attributes of a line — that's what managing lines is for.

Two conditions apply to every listing write:

Your seller account must be active, or the call returns 403 SELLER_ACCOUNT_NOT_ACTIVE.
The price currency must match your seller currency, or the call returns 422 CURRENCY_MISMATCH.

{ "provided": "USD", "expected": "EUR" }

List a line

POST /v1/inventory/{inventoryId}/listing publishes a line to the Marketplace at a price. By default the whole line is listed.

curl -X POST https://public-api.cardnexus.com/v1/inventory/665f3a2b1c8d4e9f7a6b5c4d/listing \
  -H "Authorization: Bearer cnk_live_4f2d8c91e5b34a7f9e6c2d1a8b5f7e3c" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f8b1d40-6a9c-4e72-bd31-0c5e9a4f78b2" \
  -d '{
    "price": { "amount": 42.50, "currency": "EUR" },
    "quantity": 3
  }'

Listing part of a line

Pass quantity to list only some of the cards. The line splits: the listed cards move to their own line (returned as line), the rest stays in your Collection on the original line (returned as remainder). The split-off listed line inherits the original's comment but never its customId.

{
  "line": {
    "id": "665f3a2b1c8d4e9f7a6b5c52",
    "customId": null,
    "comment": "Pack fresh, straight into a toploader",
    "productId": 50212,
    "game": "ygo",
    "finish": "Standard",
    "condition": "NM",
    "language": "en",
    "quantity": 3,
    "graded": null,
    "forSale": true,
    "listing": { "price": { "amount": 42.50, "currency": "EUR" } },
    "updatedAt": "2026-06-10T09:15:31.000Z"
  },
  "remainder": {
    "id": "665f3a2b1c8d4e9f7a6b5c4d",
    "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
    "comment": "Pack fresh, straight into a toploader",
    "productId": 50212,
    "game": "ygo",
    "finish": "Standard",
    "condition": "NM",
    "language": "en",
    "quantity": 2,
    "graded": null,
    "forSale": false,
    "listing": null,
    "updatedAt": "2026-06-10T09:15:31.000Z"
  }
}

When the whole line is listed, remainder is null. If listing the whole line makes it identical to one of your existing listed lines (same product, finish, condition, language, grading, and price, neither line carrying a customId), the two merge and line is the surviving line.

A line that's already listed returns 409 ALREADY_LISTED; a quantity larger than the line holds returns 409 INSUFFICIENT_QUANTITY.

Change the price

PATCH /v1/inventory/{inventoryId}/listing changes the per-card price of a listed line. Price is the only thing this endpoint changes — how many cards are for sale is a property of the line: list more by listing again, or take some off sale by delisting.

curl -X PATCH https://public-api.cardnexus.com/v1/inventory/665f3a2b1c8d4e9f7a6b5c4d/listing \
  -H "Authorization: Bearer cnk_live_4f2d8c91e5b34a7f9e6c2d1a8b5f7e3c" \
  -H "Content-Type: application/json" \
  -d '{ "price": { "amount": 58.00, "currency": "EUR" } }'

The new price must use the listing's existing currency. The response is the updated line. If the new price makes the line identical to another of your listed lines (same product, finish, condition, language, grading, and price, neither line carrying a customId), the two merge and the surviving line is returned.

Delist

DELETE /v1/inventory/{inventoryId}/listing takes a listed line off the Marketplace. The cards stay in your inventory — they move back to your Collection. By default the whole listing is cancelled.

curl -X DELETE "https://public-api.cardnexus.com/v1/inventory/665f3a2b1c8d4e9f7a6b5c4d/listing" \
  -H "Authorization: Bearer cnk_live_4f2d8c91e5b34a7f9e6c2d1a8b5f7e3c"

Delisting part of a line

Pass quantity as a query parameter to take only some cards off sale. The delisted cards move back to your Collection, the rest stays for sale on the line, and the response is the line's new, reduced state.

curl -X DELETE "https://public-api.cardnexus.com/v1/inventory/665f3a2b1c8d4e9f7a6b5c4d/listing?quantity=2" \
  -H "Authorization: Bearer cnk_live_4f2d8c91e5b34a7f9e6c2d1a8b5f7e3c"

Delisted cards merge into an identical unlisted line of yours when one exists (same product, finish, condition, language, and grading, neither line carrying a customId). After a full delist that merges, the response is the surviving line. A quantity larger than the line holds returns 409 INSUFFICIENT_QUANTITY.

Get your listings

GET /v1/listings returns the lines you've published to the Marketplace, cursor-paginated and ordered by line id. It's GET /v1/inventory restricted to for-sale lines: every line has forSale: true and a listing price; Collection lines aren't included.

{
  "data": [
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4d",
      "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
      "comment": "Pack fresh, straight into a toploader",
      "productId": 50212,
      "game": "ygo",
      "finish": "Standard",
      "condition": "NM",
      "language": "en",
      "quantity": 5,
      "graded": null,
      "forSale": true,
      "listing": { "price": { "amount": 42.50, "currency": "EUR" } },
      "updatedAt": "2026-06-01T17:40:02.000Z"
    }
  ],
  "pagination": { "nextCursor": null }
}

Filter with any combination of game, productId (repeatable), condition, language, finish, graded, customId, customIdPrefix, customIdContains, and commentContains, combined with AND. Follow pagination.nextCursor until it comes back null. limit defaults to 50, maximum 100.

Inventory overview — Collection vs Marketplace, the line model
Managing lines — change a line's product, condition, or quantity
Bulk operations — list and reprice many lines at once
Webhooks — inventory.quantity.changed fires when a listing operation moves cards

Tags & locations

Bulk operations