Search your inventory

Searches your inventory lines. Returns a paginated list of lines matching the body, with total for the filtered set.

Filter fields (all combined with AND):

name — free-text search against the product name, ranked by relevance.
tags, location — match by label name. { "op": "or", "values": ["to-verify", "reserved"] } returns lines carrying either tag; "op": "and" requires both. Pass null as a value to match lines with no tag (or no location) — { "op": "or", "values": [null] } returns untagged lines.
customId, customIdPrefix, customIdContains — match your own line identifiers, case-insensitively. commentContains matches your buyer-facing comments word by word.
productIds, expansionId — direct catalogue lookups.
condition, language, finish, graded, forSale, quantity, listingPrice — line attributes.
productType, productCategory — restrict to cards or sealed.
gameFilters — pick a game (e.g. { "game": "mtg" }), and optionally that game's own attribute filters in the same object.

Pagination + sort:

limit defaults to 50, max 200. offset defaults to 0 and pages up to the first 10,000 matches — for a complete walk of your inventory use GET /v1/inventory or POST /v1/inventory/bulk/export.
sortBy, sortDirection — sort the results. When name is set, results are ranked by relevance unless you sort explicitly.

This endpoint is for finding lines: relevance ranking, label and text matching, jump-to-page pagination. Results can lag your latest changes by a few seconds. To walk your whole inventory — always up to date, in a stable order, with no depth limit — use GET /v1/inventory; both return the same line shape.

POST /v1/inventory/bulk/export accepts the same filters, so a search can be turned into an export unchanged.

This endpoint has its own rate-limit bucket (inventory-search).

Requires the inventory:read scope.

Body

required

application/json

commentContains
Type: string
min length:
1

Return lines whose comment contains this text, matched word by word — binder 2 matches a comment containing those words in that order, not arbitrary substrings inside a word.
condition
Type: object

Return only lines in these conditions — { "op": "or", "values": ["NM", "LP"] }.
customId
Type: string
min length:
1

Return the line whose customId equals this value, matched case-insensitively.
customIdContains
Type: string
min length:
1

Return lines whose customId contains this value, case-insensitively.
customIdPrefix
Type: string
min length:
1

Return lines whose customId starts with this value, matched case-insensitively.
expansionId

Return only lines from this expansion. Returned by GET /v1/games/{gameId}/expansions.
Type: number

Return only lines from this expansion. Returned by GET /v1/games/{gameId}/expansions.
finish
Type: object

Return only lines with these finishes — { "op": "or", "values": ["Foil"] }.
forSale
Type: boolean

true returns only lines published to the Marketplace; false returns only lines in your Collection. Omit to return both.
gameFilters

Restrict to a single game, and optionally filter on that game's own attributes (rarity, color, …). Pass { "game": "mtg" } for any MTG line, or add filters: { rarity: { op: "or", values: ["mythic"] } } to narrow further.
Restrict to a single game, and optionally filter on that game's own attributes (rarity, color, …). Pass { "game": "mtg" } for any MTG line, or add filters: { rarity: { op: "or", values: ["mythic"] } } to narrow further.
game
const:
sorcery
required
filters
Type: object
graded
Type: boolean

true returns only graded cards; false returns only raw cards. Omit to return both.
language
Type: object

Return only lines in these languages, as two-letter codes — { "op": "or", "values": ["en", "de"] }.
limit
Type: integer
min:
1
max:
200

Integer numbers.

Responses

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

post/inventory/search

curl https://public-api.cardnexus.com/v1/inventory/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "offset": 0,
  "limit": 50,
  "name": "",
  "customId": "",
  "customIdPrefix": "",
  "customIdContains": "",
  "commentContains": "",
  "productIds": [
    1
  ],
  "expansionId": 42,
  "tags": {
    "op": "and",
    "values": [
      "Trade binder"
    ]
  },
  "location": {
    "op": "and",
    "values": [
      "Trade binder"
    ]
  },
  "condition": {
    "op": "and",
    "values": [
      "NM"
    ]
  },
  "language": {
    "op": "and",
    "values": [
      ""
    ]
  },
  "finish": {
    "op": "and",
    "values": [
      "Standard"
    ]
  },
  "productType": {
    "op": "and",
    "values": [
      "card"
    ]
  },
  "productCategory": "",
  "graded": true,
  "forSale": true,
  "quantity": {
    "min": 0,
    "max": 0
  },
  "listingPrice": {
    "min": 0,
    "max": 0
  },
  "gameFilters": {
    "game": "sorcery",
    "filters": {}
  },
  "sortBy": "name",
  "sortDirection": "asc"
}'

Show Schema

{
  "data": [
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4d",
      "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
      "comment": "From a sealed box, sleeved straight away",
      "notes": "Bought at the March show",
      "location": "Store A",
      "tags": [
        "to-verify",
        "reserved"
      ],
      "productId": 50212,
      "game": "ygo",
      "finish": "Standard",
      "condition": "NM",
      "language": "en",
      "quantity": 5,
      "graded": null,
      "forSale": true,
      "listing": {
        "price": {
          "amount": 42.5,
          "currency": "EUR"
        }
      },
      "updatedAt": "2026-06-01T17:40:02.000Z"
    },
    {
      "id": "665f3a2b1c8d4e9f7a6b5c50",
      "customId": null,
      "comment": null,
      "notes": null,
      "location": "Store A",
      "tags": [],
      "productId": 50213,
      "game": "mtg",
      "finish": "Foil",
      "condition": "LP",
      "language": "en",
      "quantity": 2,
      "graded": null,
      "forSale": false,
      "listing": null,
      "updatedAt": "2026-05-22T08:11:47.000Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 37,
    "hasMore": false
  }
}

Matching lines returned.