Add inventory lines
Adds new lines to your inventory — between 1 and 1000 per call.
Each line names a catalogue product (see GET /v1/products), a finish, a language, and a quantity, plus either a condition (raw cards) or graded details (graded cards). Optionally attach a customId (your own identifier, unique across your live lines), a comment (shown to buyers), private notes, a location, tags, or a listing to publish the line to the Marketplace right away.
location and tags are referenced by name and must already exist — create them first with POST /v1/inventory/locations and POST /v1/inventory/tags. A name that matches none of your labels rejects that line with LOCATION_NOT_FOUND or TAG_NOT_FOUND.
Lines are processed one by one: valid lines land in created, rejected lines are reported in errors with the position they had in your request. The response status is 200 even when some — or all — lines were rejected, so check both fields.
A new line without a customId that matches an existing line of yours exactly (same product, finish, condition, language, grading, and listing state) merges into it: the quantity is added to the existing line, and that line is returned in created.
When any line carries a listing, your seller account must be active and every listing price must use your seller currency.
Send an Idempotency-Key header to make retries safe: the same key returns the same response for 24 hours.
Requires the inventory:write scope.
- Type: array object[] 1…1000linesrequired
The lines to add — between 1 and 1000 per call.
- application/json
- application/json
- application/json
- application/json
- application/json
- application/json
- application/json
curl https://public-api.cardnexus.com/v1/inventory \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"lines": [
{
"productId": 50212,
"finish": "Standard",
"condition": "NM",
"graded": {
"grade": "",
"certification": "",
"gradingService": "PSA"
},
"language": "",
"quantity": 1,
"customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01",
"comment": "Slight edge wear on the back corner",
"notes": "",
"location": "",
"tags": [
"Trade binder"
],
"listing": {
"price": {
"amount": 14.99,
"currency": "USD"
}
}
}
]
}'
{
"created": [
{
"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": "Shelf A",
"tags": [
"Trade binder"
],
"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-10T09:15:31.000Z"
}
],
"errors": [
{
"index": 1,
"code": "INVALID_LANGUAGE",
"data": {
"productId": 50213,
"language": "jp"
}
}
]
}