POPurchaseOrder

Purchase Order

Buyer order request sent to a supplier.

A Purchase Order is the buyer's authoritative request for goods or services. It establishes the business order number, requested delivery timing, parties, ship-to and bill-to details, ordered lines, pricing, totals, and partner extension values that downstream acknowledgement, shipment, and invoice documents must preserve.

Download JSON Schema View Scalar Model

Lifecycle And Correlation

Lifecycle Position

Starts the order lifecycle and creates the references used by POA, ASN, and INV documents.

Correlation Guidance

Treat data.poNumber as the business reference and data.lineItems[].uniqueLineKey as the durable line reference. Downstream documents should carry the original uniqueLineKey when a line is acknowledged, shipped, packed, or invoiced.

Contract Shape

Envelope

Identifies the canonical document and provides cross-system traceability.

docType

Always PO for purchase order payloads.

correlationId

Stable UUID used to trace the order through downstream lifecycle events.

timestamp

UTC timestamp for when the canonical document was created.

Order Header

Captures the buyer's order identity, revision, intent, and requested delivery timing.

data.poNumber

Buyer-issued order number used for business support.

data.poVersion

Buyer-issued revision or version of the order.

data.requestType

Whether this creates a new order or changes one.

data.requestedDeliveryDate

Buyer-requested delivery date for the order.

Parties And Addresses

Names the buyer and supplier and separates billing from delivery destinations.

data.buyer

Party placing the order.

data.supplier

Party expected to fulfil the order.

data.billTo

Billing destination supplied by the buyer.

data.shipTo

Delivery destination for the ordered goods.

Lines And Totals

Defines ordered products, line correlation, pricing, tax, and order-level totals.

data.lineItems[]

Ordered product lines with quantities and pricing.

data.lineItems[].uniqueLineKey

DataShift stable line key for POA, ASN, and INV correlation.

data.orderTotals

Order subtotal, tax, total amount, and currency.

data.extrinsics

Partner-specific extension values outside the canonical core.

Validation Notes

Require buyer, supplier, billTo, shipTo, lineItems, and orderTotals before accepting the document.
Validate requestType against the supported new and change values.
Use ISO 4217 currency values consistently across line and order totals.
Keep date-time values timezone-aware so requested delivery timing is not shifted.

Mapping Notes

Map source order identifiers to data.poNumber and preserve the source revision in data.poVersion when present.
Create or preserve uniqueLineKey for each line before sending downstream documents.
Map ship-to address details even when the order is direct ship or dropship.
Place partner-only values in data.extrinsics instead of overloading canonical fields.

Operational Notes

Use correlationId and poNumber together in logs and support tickets.
When a changed order arrives, compare poVersion and line uniqueLineKey values before deciding whether downstream documents need updates.

Implementation Pitfalls

Do not use array position as a line identifier.
Do not infer the supplier from a trading connection alone; keep the supplier party explicit.
Do not collapse tax-inclusive and tax-exclusive amounts into a single value.