Create a listing
Read and write keySeller API v1 · Updated 7 November 2026
POSThttps://klodivo.com/api/v1/inventory
Lists an item from the catalog. The same rules apply as on the site: a used set needs a note, and a photo before it can be active (without one it is saved as hidden and warnings says so).
Authentication
API key in the header Authorization: Bearer kv_live_…. This call needs a Read and write key. Create keys under Your store → API.
Body application/json
| Field | Type | Description |
|---|---|---|
| item_type | string | set, minifig, part, gear or book, with item_no in klodivo numbers (6080-1, 3001). Or use bricklink_type (S, M, P, I, O, G, B) and bricklink_no. |
| color_id | integer | Parts: the colour. Or bricklink_color_id. |
| kind | string | Sets only: item, instructions or box. |
| state | string | new or used. |
| grade | string | Used items: like_new, good or acceptable. |
| completeness | string | Sets, instructions and boxes: sealed, complete or incomplete. |
| has_box | boolean | Comes with its box. |
| has_instructions | boolean | Comes with its instructions. |
| notes | string | Shown to buyers, up to 500 characters. Required for a used set. |
| quantity | integer | 0 to 99,999. 0 marks it sold out. |
| price | string | Price per unit in your store's currency, like "12.50". |
| status | string | active or hidden. |
| external_ref | string | Your own id for the listing, up to 64 characters. |
Responses
Created. The new listing, and warnings if it was saved as hidden. See the example response with the request examples.
Fields need a look; each one is in fields.
{
"error": {
"code": "invalid_listing",
"message": "Some fields need a look.",
"fields": {
"notes": "A used set needs a note describing its condition."
}
}
}Missing, unknown or revoked key.
{
"error": {
"code": "unauthorized",
"message": "This API key doesn't exist or was revoked."
}
}A Read only key, or the store is suspended or closed.
{
"error": {
"code": "read_only_key",
"message": "This is a read-only key. Create a read and write key to change anything."
}
}Too many requests. Wait the seconds in Retry-After.
{
"error": {
"code": "rate_limited",
"message": "Too many requests: up to 120 a minute per key. Try again in 12 s."
}
}Still stuck? Contact us; we reply within 2 business days.