Platitun · API · Auto-delivery stock · Refill the stock

Refill the stock

POST /api/v1/listings/{number}/stock

Key scope: stock · changes data, the Idempotency-Key header is required

Stock units are what the buyer receives: a code, a link, an email-and-password pair. They are encrypted on write and cannot be read back even by you.

Refilling stock is the most frequent action of a program, and a retry after a broken connection costs the most here: two thousand units instead of one thousand. The Idempotency-Key header is required, and a repeat with the same key returns the earlier response.

Request fields

Field	Type	What it is
`items` required	`array`	A list of strings — one per stock unit.

Response fields

Field	Type	What it is
`added`	`integer`	How many units were accepted.
`free`	`integer`	How many are free now.

Refusal reasons

A rule refusal arrives as {"error":"rejected","refusal":{"kind":"…"}} with status 409. Refusals common to all endpoints are in the rules section.

Code	What happened and what to do
`not_found`	The record does not exist or is not yours. The ownership condition is in the database query itself, so someone else’s record looks like a missing one.
`stock_empty`	The list of stock units is empty. An empty refill changes nothing, so it is refused rather than silently accepted.
`stock_too_many`	That many units are not accepted at once. Split the refill into parts.
`vault_off`	The marketplace vault is not configured, so there is nowhere to keep secrets. That is our problem, not yours: contact support.
`bad_request`	The request is malformed: a required field is missing or a value is of the wrong kind. The specifics are in the detail field.

Nearby in this section

GET /api/v1/listings/{number}/stock — What is in stock