Skip to main content
POST
Restate a purchase order loaded from the previous system as fulfilled

Authorizations

Authorization
string
header
required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_ Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Path Parameters

id
string<uuid>
required

Body

application/json
reason
string
required

Why the purchase order is being restated (3 to 500 characters), recorded on its status history and its activity.

Required string length: 3 - 500
received_quantities
object[]

Optional. The received quantity per line; a line not named here takes its ordered quantity. Each quantity must be at least what the line already reads received and at most what was ordered.

Response

The restated purchase order, as GET /purchase-orders/{id} returns it.

A purchase order issued to a vendor.

id
string<uuid>
object
enum<string>
Available options:
purchase_order
entity_id
string<uuid>
read-only
po_number
string
read-only
vendor_id
string<uuid>
location_id
string<uuid> | null
status
enum<string>
read-only
Available options:
draft,
approved,
sent,
partially_received,
received,
closed,
cancelled
po_date
string<date-time>
expected_date
string<date-time> | null
subtotal
number
tax_total
number
shipping_total
number
po_total
number
currency
string
default:USD
notes
string | null
internal_notes
string | null
metadata
object | null
created_at
string<date-time>
read-only
updated_at
string<date-time>
read-only
approved_total
number | null
read-only

The order total as it stood when an approver approved this purchase order -- the basis they actually saw. NULL on every approval predating 2026-08-17 (no backfill) and NULL means "basis unknown", which is treated as fail-safe.

approval_stale
boolean
read-only

DERIVED, not stored. True when the order is approved AND its total has since risen above approved_total. The purchase order still receives normally; this is a non-blocking prompt to re-approve.

header_editability
object
read-only

Per-field verdicts for the header fields, from the same predicate the write handlers enforce. Keys: notes, internal_notes, due_date, expected_date, location_id, po_tracking_reference. Each is { allowed: boolean, reason: string|null } where reason is a token from the PoLineEditReason vocabulary.

billed_total
number
read-only

How much of this purchase order's GOODS a vendor bill has already taken over: the sum of the goods lines that count toward this purchase order on every bill in open, partial, paid or written_off, never a bill's header total and never a landed, freight or expense line on it. A line counts toward this purchase order when its po_item_id names one of its lines, or when it names none and the bill's po_id is this purchase order (one bill may bill several purchase orders, and each is billed only its own lines). 0 when no bill has been raised, never null.

unbilled_balance
number
read-only

What the purchase order STILL commits the buyer to, compared like with like: 0 once every ordered goods unit is billed (where the units can be seen; goods money otherwise), else max(order_total - billed_total, 0), cents-quantized. A bill line's units count under the product of the purchase-order line its po_item_id names, and under the bill line's own product only when it names none, so a keyed line with no product of its own still counts. Read this rather than balance_due, which on a purchase order is the ORIGINAL COMMITMENT the header was raised for and is never decremented when a bill is raised (the payable is the bill).

billed_by_bill
object[]
read-only

Per bill whose goods lines count toward this purchase order (the lines billed_total sums, here for every bill status): goods_on_po, the goods it bills on this purchase order, and goods_total, the goods it carries in all. A bill that also bills another purchase order shows goods_on_po below goods_total; on a bill of this purchase order alone the two are equal. Each entry carries the bill's status, so a reader that names the bills that billed these goods can leave a voided bill out. An empty array when no bill bills it, never null.

landed_bills
object[]
read-only

The landed bills that reach this purchase order (the Linked Documents card): a Case-A bill, a landed-only bill naming the PO, or a receipt-set bill on its receipts. Identity only (no amounts); the allocations are getPurchaseOrderLandedCostsV1's.