Skip to navigation
API ReferencePurchase Orders

Create Purchase Order

Creates a new purchase order. Items can be included in the request body or added later via the items endpoints.

Requires scope: purchase_orders:write

Authentication

API_KEYstring
API Key authentication via header

Request

This endpoint expects an object.
orderNumberstringRequired
Order reference number. Required. Maximum 255 characters.
supplierIdUUIDOptional
ID of the supplier for this order.
locationIdUUIDOptional
ID of the destination location.
notestringOptional

Optional free-text note for the supplier.

dueDatedateOptional

Expected delivery date (ISO 8601 date, e.g. 2026-04-15).

itemslist of objectsOptional
Initial line items. Items can also be added after creation.

Response

This endpoint returns an object.
idUUID
Unique identifier for the purchase order.
itemCountinteger
Number of line items in this purchase order.
orderNumberstringOptional

Human-readable order reference number (e.g. PO-1042).

statusenumOptional
Current lifecycle status of the purchase order.
typestringOptional

Classification of the order: REPLENISHMENT, MATERIALS_ORDER or OTHER. Not settable through this API, so orders created here always report null.

totalCostdoubleOptional
Grand total cost of all items in USD.
subtotaldoubleOptional

Sum of the order’s line items: quantity * price for every item still on the order, with removed items excluded. Always computed from the items when the order is read, so it is correct no matter how the order was created. Excludes tax, shipping and discounts, which this API does not expose. It is 0 only on an order that has no items.

notestringOptional

Free-text note for the supplier.

supplierobjectOptional
Reference to the supplier for this order.
locationobjectOptional
Reference to the destination location.
dueDatedateOptional

ISO 8601 date when the order is expected (e.g. 2026-04-15).

receivedAtdatetimeOptional

ISO 8601 timestamp when the order was marked received. null if not yet received.

assignedUserIdslist of UUIDsOptional

IDs of users assigned to this purchase order. Returned by get-by-id, create and update; the list endpoint omits it to keep the payload light, so it is null on every row there and only there.

createdAtdatetimeOptional
ISO 8601 timestamp when the record was created.
updatedAtdatetimeOptional
ISO 8601 timestamp when the record was last updated.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Rate Limit Error