Create a draft purchase order for a vendor; `send: true` creates and sends it

Defaults: the PO number is the generated PO id, the currency is the one of the internal channel, the ship-to address is the warehouse's, the bill-to address is the company's, the payment terms are the vendor's (net 30 without any). Two dates follow the order date unless the request sets them: balanceDueDate (the order date plus the net days; none when due on receipt) and shipNotBeforeDate (the order date). A draft has no order date yet (unless orderDate is sent), so both count from the day it is created until it is sent. A line names a product (productId) or is a custom line (name): a custom item (goods that are not in the catalog: they ship and are received by quantity, no stock is counted) or a charge (freight, duty, pallets), as kind says (without it a quantity above 1 is an item; a line that sends landedCost is a charge). Every custom line is stored with its kind. Landed charges are spread over the product units as landed unit cost; a custom item carries none and is in goodsTotal. With send: true the purchase order needs a ship-to warehouse with a queue location and at least one line: incoming stock is reserved there and the vendor is emailed unless notifyVendor is false (then nobody is emailed and nobody is saved, whatever recipients says). recipients is taken only with send: true (400 otherwise). The email goes To recipients (one address once, in the order given; absent on a send: the vendor contacts who get purchase orders), CC the user who sends it unless they are a recipient, and reply-to that user (the purchase order's creator when the caller is an API key). A recipient with saveAsContact: true needs a name and is saved to the vendor in the same request: a new contact who gets purchase orders, or the vendor's contact with that address switched to get them (and named when it has no name); 422 when the purchase order has no vendor. emailed answers who the email was addressed to and how many contacts were saved; it is absent when nobody was emailed.

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.

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
boolean
boolean
recipients
array of objects
length ≤ 20

Who the purchase order is emailed to, its PDF attached. Absent: the vendor contacts who get purchase orders by email. [] emails nobody. The person sending it is copied and gets the replies. Not read when notifyVendor is false.

recipients
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