Receive units of a purchase order into locations; the `Idempotency-Key` header is required

For a purchase order that was sent (also one that is already received: receiving more than ordered is allowed). Each item names its line (lineId), its product (productId) or both; a product is counted on its line of the purchase order (among several: the line with the received lot, then a line that is not full yet), and a product that is on no line is added as a new line with quantity 0 and price 0. A product needs locationId, a bin, a virtual location, a ship station or a pick station (422). A product that always has lot numbers needs lotId (or a lot on its line), and a lot must belong to the product (422). A custom item (a line of kind item) is received by lineId and quantity alone: locationId, lotId or productId on it is 422; no stock is counted and nothing is reserved for it, and each of its receipts is kept on its line (receipts of the purchase order). In one request: stock is received into the locations with the purchase order and the vendor on the stock ledger, the incoming stock reserved for the received units is released, the lines count what was received, and the purchase order becomes received when every ordered line that ships (product lines and custom items) is in full, else partly received. A purchase order that was closed short is no longer closed short after a receipt: it owes its total again. The request must carry an Idempotency-Key (400 without one): the key is also kept on the purchase order, and a request whose key the purchase order already carries answers 200 unchanged and moves no stock.

Scope: outgoing-purchase-orders:write, channel:write or admin. A permission group made before the Channel API scopes existed grants it as inventory:manage or supply-chain:manage.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.

Path Params
string
required
length between 1 and 64

The purchase order's uuid or 24-hex id.

Body Params
items
array of objects
required
length between 1 and 500
items*
string
^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or the record's 24-hex id.

string
^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or the record's 24-hex id.

integer
required
1 to 1000000
string
^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or the record's 24-hex id.

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or the record's 24-hex id.

string
length ≤ 500
Headers
string
length between 7 and 50

Any string of 7 to 50 characters that identifies this request (an order number, a webhook id). A retry with the same key and the same body answers the first result with Idempotent-Replayed: true; the same key with a different body is 422 idempotency_key_reused; a concurrent request with the same key is 409 in_progress with Retry-After. Recommended on every write.

Responses

Language
Credentials
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json