Searching listings

POST /v1/listings/search searches the live Marketplace listings across every product. Each result is one seller's listing, with the product it is for, so a single call answers questions such as the cheapest Near Mint copy of a card that ships to France, or every listing priced at least 20 percent below its market price.

To read every listing of one product, use GET /v1/products/{productId}/listings. It takes the same sort options and returns the same listing fields.

curl -X POST https://public-api.cardnexus.com/v1/listings/search \
  -H "Authorization: Bearer cnk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Charizard ex",
    "gameFilters": { "game": "pokemon" },
    "expansionIds": [512],
    "deliveryCountry": "FR",
    "condition": ["NM"],
    "language": ["en"],
    "price": { "max": { "amount": 15, "currency": "EUR" } },
    "sortBy": "price",
    "limit": 8
  }'
{
  "data": [
    {
      "listingId": "6650f1c2a4b3e2d1c0b9a8f7",
      "product": {
        "id": 64321,
        "name": "Charizard ex",
        "gameId": "pokemon",
        "expansion": {
          "id": 512,
          "name": "Obsidian Flames",
          "code": "OBF",
          "slug": "obsidian-flames"
        },
        "printNumber": "125",
        "productType": "card",
        "rarity": "Double Rare",
        "imageUrl": "https://img.cardnexus.com/products/64321.jpg/p1200.png",
        "imageCensored": false
      },
      "price": { "amount": 13.9, "currency": "EUR" },
      "quantity": 1,
      "condition": "NM",
      "language": "en",
      "finish": "Standard",
      "graded": null,
      "comment": null,
      "photos": [],
      "marketPrice": { "amount": 15.87, "currency": "EUR", "region": "eu" },
      "priceVsMarketPercent": -12.4,
      "listedAt": "2026-10-20T14:03:11.000Z",
      "seller": {
        "id": "665f3a2b1c8d4e9f7a6b5c4d",
        "username": "north_arena_tcg",
        "country": "DE",
        "type": "pro",
        "rating": { "average": 4.9, "count": 812 },
        "verifiedSalesCount": 1534,
        "shipping": { "amount": 3.5, "currency": "EUR" }
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJ2IjoxLCJoIjoiOWYyYzFhNGU3YjhkM2E2MCIsInMiOlsxMzkwLCI2NjUwZjFjMmE0YjNlMmQxYzBiOWE4ZjciXSwiaSI6MTc2MTE0NjU5MH0",
    "total": 37,
    "totalIsLowerBound": false
  }
}

price is in the seller's own currency. To buy a listing, pass its listingId to POST /v1/cart/items. A listing can sell to someone else before you add it, and the final price, with fees, is computed in your cart.

Filters

Field Effect
name, gameFilters, productType, productIds, expansionIds Choose the products. name matches as in product search, print numbers and expansion codes included, but results keep the order of sortBy, so a broad name can match several products. To keep exactly one, pass its id in productIds.
deliveryCountry Keep only sellers who ship to this country, under the same rule checkout applies. Each listing then carries the seller's shipping charge in seller.shipping; without it, seller.shipping is null.
region Keep only sellers in eu or na.
price A min and max unit price in EUR or USD, both in the same currency. Listings are compared at the daily exchange rate, without any margin, so a bound can differ slightly from the price shown in another currency.
priceVsMarket A minPercent and maxPercent for how far the price is from the listing's market price. { "maxPercent": -20 } keeps listings priced at least 20 percent below it.
condition, language, finish Keep only listings with any of the values. condition applies to raw cards and cannot be combined with graded: true.
graded, gradingService, minGrade graded: true keeps graded cards, false keeps raw cards and sealed products. gradingService and minGrade need graded: true.
sellerUsername, sellerCountry, sellerType Keep only one seller's listings, sellers in these countries, or pro or individual sellers.
minQuantity Keep only listings with at least this many units.

A request that combines fields the endpoint cannot satisfy together returns 400 BAD_REQUEST, with the offending fields in data.issues: gradingService or minGrade without graded: true, condition with graded: true, price bounds in different currencies, and priceVsMarket or sortBy: "priceVsMarket" without deliveryCountry or region.

Market price

Each listing carries marketPrice, the market price of its finish adjusted for its condition, and priceVsMarketPercent, how far price is from it: -12.4 is 12.4 percent below. For a graded card or a sealed product, marketPrice is the market price of the finish, so the grade is not taken into account. Both are null when the finish has no market price.

The market price is quoted for the region of deliveryCountry, otherwise of region, otherwise of the seller's own region. priceVsMarket and sortBy: "priceVsMarket" use the same region, which is why they need deliveryCountry or region, and they leave out listings with no market price in it.

Sorting

sortBy takes price, priceVsMarket or newest. price is the default and compares prices in euros, whatever currency each seller lists in. It does not include the VAT that checkout adds to some professional sellers' prices. sortDirection defaults to asc, and to desc for newest.

Pages

Pass pagination.nextCursor back as cursor, with the same filters and sort, until it is null. limit defaults to 50, maximum 100. The first page also returns pagination.total, counted up to 10,000; above that, totalIsLowerBound is true.

A page can hold fewer than limit listings when some sold, or their seller became unavailable, since the search was indexed. The next cursor still continues without skipping or repeating a listing. A cursor sent with other filters or another sort returns 400 CURSOR_MISMATCH, and one that cannot be read or is too old returns 400 INVALID_CURSOR. Cursors issued by GET /v1/products/{productId}/listings before this change return INVALID_CURSOR.

Errors

Code Status When
BAD_REQUEST 400 The fields above that cannot be combined.
SELLER_NOT_FOUND 404 No seller has the sellerUsername.
COUNTRY_NOT_SUPPORTED 422 CardNexus does not deliver orders to the deliveryCountry.
INVALID_CURSOR 400 The cursor cannot be read or is too old.
CURSOR_MISMATCH 400 The cursor was returned for other filters or another sort.
SEARCH_UNAVAILABLE 503 The search timed out or could not be completed. Narrow the filters or retry. A search never returns a partial page.

Rate limit

Requests count against the listing-search bucket: 600 requests per hour. See Rate limits.