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". |
| tiers | array | Quantity prices, up to 3: [{"from": 50, "price": "0.08"}, {"from": 200, "price": "0.06"}]. A buyer of at least from pays that price for every item in the line. Quantities go up (2 or more), prices go down (below price). [] removes them; left out, they stay. |
| status | string | active or hidden. |
| external_ref | string | Your own id for the listing, up to 64 characters. |
| made_by | string | Gear and books from business stores: lego (the default) or other for items made by a licensed company, as printed on the label. |
| manufacturer_name | string | With other: the company name. Also manufacturer_address (postal) and manufacturer_contact (email or website), all required. |
| eu_rep_name | string | A company outside the EU: its EU responsible person. Also eu_rep_address and eu_rep_contact. |
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."
}
}Hai ancora bisogno di aiuto? Contattaci: rispondiamo entro 2 giorni lavorativi.