Update a purchase order (only the fields sent; `items` replaces the line set); 200 unchanged when nothing differs

A line of items with an id keeps that line; a line without one is new; a stored line that is not sent is removed. A line cannot be removed, change product or go below what was received or shipped (409). A kept line sent with the quantity it has is accepted as it is, also a quantity of 0 (a product that was received without being ordered); a new line, or a quantity that changes, needs at least 1 (422). kind is refused on a product line and landedCost on a custom item (422); a kept custom line keeps its kind unless kind says otherwise, and a custom item that shipped or was received cannot become a charge (409). Every custom line sent is stored with its kind. A sent purchase order moves its incoming stock reservations to the new quantities, dates and warehouse in the same request, and notifyVendor: true emails the vendor the revision. balanceDueDate and shipNotBeforeDate follow the order date and the net days: when orderDate or paymentTerms changes, a date that was derived moves with it and a date the caller set is kept; sending one sets it, and sending null gives it back to the rule. An update of anything else leaves both dates as they are. Refused with 409 once the purchase order is received, cancelled or exported to accounting, and with 409 version_conflict when version is not the current one.

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
^(?:[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.

length between 1 and 100
length ≤ 100

The vendor's own order or proforma invoice number.

^(?:[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.

shipTo
object
billTo
object
Schema_aee7e11aee | null
Schema_aee7e11aee | null
Schema_aee7e11aee | null
Schema_aee7e11aee | null
Schema_aee7e11aee | null
Schema_1bc7dc02ee | null
length ≤ 255

Where the goods ship from ("Ningbo, China").

^[A-Za-z]{3}$

EXW, FOB, CIF, DDP, ...

string
^[A-Za-z]{3}$

ISO 4217 code (case-insensitive); default: the currency of the tenant internal channel.

paymentTerms
object
length ≤ 5000

Notes and instructions for the vendor (printed).

^(?:[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.

items
array of objects
length ≤ 1000
items
string
length between 1 and 32
boolean
boolean

true: calculate every product line's unit cost from its price and its share of the landed charges, also on a purchase order whose item costs were kept (itemCostsKept: set on the old page), which is calculated from then on. Needs no items.

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