AlmondTill/G3N API

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

FieldTypeNotes
idID ID!The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it.
sysIdString String!The group-scoped human-facing system id (PO-…).
typeString String!The kind of record — always PurchaseOrder here.
captionString String!The record’s display name — what people see it called.
statusString String!The FSM state: draft | pending_approval | issued | acknowledged | partially_received | issuing | cancelling | closing | received | closed_short | cancelled.
parentIdID ID!The parent BUYING Organization; for a PurchaseOrder parentId!== rootId.
rootIdID ID!The org-group family root.
createdAtString String!When the record was created, as a UTC timestamp.
updatedAtString String!When the record last changed, as a UTC timestamp.
revisionNumInt Int!How many times this record has been edited; the first save is 0.
revisionID ID!The OCC revision token — supply it on every mutation of this record; rotates on every write.
refCaptionsRefCaption [RefCaption!]!The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption.
orgVendorIdID ID!The supplying OrgVendor enablement — IMMUTABLE at birth (re-vendor = cancel + new); ACTIVE-gated at create AND re-checked at issue.
currencyString 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.
paymentTermsStringOptional canned payment terms — snapshot defaulted from the OrgVendor at create, per-PO overridable.
incotermCodeStringOptional canned Incoterms 2020 rule (the registry, e.g. FOB / DDP) — snapshot defaulted from the OrgVendor at create, per-PO overridable.
vendorReferenceStringOptional vendor-side order/quote reference (their token — a bounded free string, max 64).
notesStringOptional free-text notes (max 4096).
lineCountInt 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.
openLineCountInt Int!Rollup: the lines still OUTSTANDING (receivedQty < quantity). The system:all_received edge fires when this reaches 0 — O(1), never a line walk.
nextLineNoInt 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.
merchandiseTotalMoneyEntry 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).
receivingReceiptIdIDthe 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.
linesPurchaseOrderLine [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.
walkPurchaseOrderWalkThe 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