# PurchaseOrder

object type

A purchase order: an org orders variants x quantities x receiving LFs from ONE enabled vendor (the OrgVendor enablement — IMMUTABLE at birth). Lines live in their OWN rows since and stay draft-editable wholesale (max 1000 — the NAMED assignment ceiling, raised from 48 with the rows; at most 90 line actions per CALL, so a big order grows through addPurchaseOrderLines; the same variant to N LFs = N lines,889); currency is the OrgVendor purchasingCurrency SNAPSHOT (every Money on the family matches it — NO FX, lean 5); received/closed_short are IMMUTABLE non-doomed history; cancelled is the ONE doomed terminal (lists filter it). Re-running the same verb RESUMES a stalled walk; on a healthy in-flight order it refuses CONFLICT/IN_PROGRESS naming the progress.

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (PO-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `PurchaseOrder` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: draft \| pending_approval \| issued \| acknowledged \| partially_received \| issuing \| cancelling \| closing \| received \| closed_short \| cancelled. |
| `parentId` | [ID](/types/#scalars) `ID!` | The parent BUYING Organization; for a PurchaseOrder parentId!== rootId. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/RefCaption/) `[RefCaption!]!` | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
| `orgVendorId` | [ID](/types/#scalars) `ID!` | The supplying OrgVendor enablement — IMMUTABLE at birth (re-vendor = cancel + new); ACTIVE-gated at create AND re-checked at issue. |
| `currency` | [String](/types/#scalars) `String!` | The PO currency — a SNAPSHOT of the OrgVendor purchasingCurrency at create. Every Money on the family (line costs, landed components, invoice amounts, credits) must match it; the rate framework is the named FX trigger. |
| `paymentTerms` | [String](/types/#scalars) | Optional canned payment terms — snapshot defaulted from the OrgVendor at create, per-PO overridable. |
| `incotermCode` | [String](/types/#scalars) | Optional canned Incoterms 2020 rule (the registry, e.g. FOB / DDP) — snapshot defaulted from the OrgVendor at create, per-PO overridable. |
| `vendorReference` | [String](/types/#scalars) | Optional vendor-side order/quote reference (their token — a bounded free string, max 64). |
| `notes` | [String](/types/#scalars) | Optional free-text notes (max 4096). |
| `lineCount` | [Int](/types/#scalars) `Int!` | Rollup: the LIVE line rows on this order (0..1000) — maintained in the SAME transaction as every line mutation. ALWAYS <= nextLineNo - 1: removed numbers are never reused. |
| `openLineCount` | [Int](/types/#scalars) `Int!` | Rollup: the lines still OUTSTANDING (receivedQty < quantity). The system:all_received edge fires when this reaches 0 — O(1), never a line walk. |
| `nextLineNo` | [Int](/types/#scalars) `Int!` | The MONOTONIC next lineNo this order will assign (born 1; +1 per minted line; a removed number is NEVER reused, so the poLineNo addressing on Receipt + VendorInvoice stays unambiguous forever). Ceiling 1000 + 1 = the assignment exhausted. |
| `merchandiseTotal` | [MoneyEntry](/types/MoneyEntry/) `MoneyEntry!` | Rollup: SIGMA (quantity x unitCost) over the live lines, in the PO snapshot currency — the vendor orderMinimum gate at issue reads THIS instead of summing lines. Landed components are NOT in it (they join at receipt post). |
| `receivingReceiptId` | [ID](/types/#scalars) | the ONE receipt mid-post against this order: set by a posting receipt’s first in-flight chunk, cleared by its last (the same transaction). A second receipt’s post refuses CONFLICT/IN_PROGRESS naming it, and close_short waits on it (policy:no_receipt_in_flight). Null when no receipt is walking. |
| `lines` | [PurchaseOrderLine](/types/PurchaseOrderLine/) `[PurchaseOrderLine!]!` | The WHOLE line set, read from the line ROWS in lineNo order and bounded by the 1000-line ceiling. To PAGE, FILTER or SORT them — or to read a big order without hydrating every line — use the purchaseOrderLines query. The receivedQty rollups mutate ONLY via receipt posts under the doc OCC. |
| `walk` | [PurchaseOrderWalk](/types/PurchaseOrderWalk/) | The IN-FLIGHT on-order walk: present EXACTLY while status is issuing / cancelling / closing — a large order whose stock stamps did not fit ONE transaction is written a chunk at a time, and this carries where it stands (kind · cursor = the next line to stamp, so cursor − 1 of lineCount landed · chunks so far · lineCount · startedAt · the machine executionArn once started · stalledAt + problem when a step failed past its retries). Null on every other status; cleared by the LAST chunk in the same transaction that lands the terminal. Re-run the same verb (issue / approve / cancel / close_short) to RESUME a stalled walk; on a healthy one it refuses CONFLICT/IN_PROGRESS naming the progress. |

## Used by

- [acknowledgePurchaseOrder](/reference/purchasing/acknowledgePurchaseOrder/)
- [addPurchaseOrderLines](/reference/purchasing/addPurchaseOrderLines/)
- [approvePurchaseOrder](/reference/document-approvals/approvePurchaseOrder/)
- [cancelPurchaseOrder](/reference/purchasing/cancelPurchaseOrder/)
- [closeShortPurchaseOrder](/reference/purchasing/closeShortPurchaseOrder/)
- [createPurchaseOrder](/reference/purchasing/createPurchaseOrder/)
- [issuePurchaseOrder](/reference/purchasing/issuePurchaseOrder/)
- [purchaseOrder](/reference/purchase-order/purchaseOrder/)
- [rejectPurchaseOrder](/reference/document-approvals/rejectPurchaseOrder/)
- [removePurchaseOrderLines](/reference/purchasing/removePurchaseOrderLines/)
- [submitPurchaseOrder](/reference/purchasing/submitPurchaseOrder/)
- [updatePurchaseOrder](/reference/purchase-order/updatePurchaseOrder/)
- [updatePurchaseOrderLine](/reference/purchasing/updatePurchaseOrderLine/)