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.
Search
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.