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.

View releases View model View example View guides

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 must carry the original uniqueLineKey when a line is acknowledged, shipped, packed, or invoiced; automatic line matching does not fall back to display line numbers, item identifiers, descriptions, quantities, or array position.

Validation Notes

Require buyer, supplier, billTo, shipTo, lineItems, and orderTotals before accepting the document.
Validate operation against the supported new, update, and delete 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; do not rely on lineNumber, item id, description, quantity, or array index as an automatic match key.
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.

Endpoints

Use the schema endpoint for machine validation and the document page for implementation guidance.

GET

Download Purchase Order schema

application/schema+jsonapplication/json

/contracts/releases/1.0.7/schemas/purchase-order.schema.json

Purchase Order JSON Schema

GET

Purchase Order

text/html

/schemas/purchase-order

Purchase Order documentation page

Model

The contract is shown in reading order. The envelope identifies the document, metadata captures source context, and data contains the business payload and nested line structures.

DataShift-managed systemManaged fields

DataShift populates, preserves, or recalculates these values for correlation, lifecycle matching, validation, and auditability. They are visible in the model so implementers know which fields are controlled by the platform instead of manual partner mappings.

Envelope

PurchaseOrder

5 fields5 required3 managed

Public canonical Purchase Order contract used to represent a buyer's order before acknowledgement, shipment, and invoice events.

docType

RequiredDataShift-managed system

object

Canonical document type. For purchase orders this value is PO.

PO

correlationId

RequiredDataShift-managed system

string (uuid)

Stable UUID used to trace this purchase order through downstream acknowledgements, shipments, invoices, and support workflows.

timestamp

RequiredDataShift-managed system

string (date-time)

UTC timestamp indicating when DataShift created the canonical document.

metadata

Required

PurchaseOrderMetadata

data

Required

PurchaseOrderData

Metadata

PurchaseOrderMetadata

4 fields3 required

Public source metadata retained for integration troubleshooting without exposing tenant or credential details.

sourceLanguage

Required

enum

jsoncxml

sourceVersion

Required

object

Canonical schema version used to create this document

1.0.7

payloadId

string

Original cXML payload ID

userAgent

Required

object

DataShift Edge version that generated the canonical document

DataShift Edge v1

Data

PurchaseOrderData

16 fields11 required

Business payload for the purchase order.

poNumber

Required

string

Buyer-issued purchase order number. Use this as the primary business reference.

poVersion

Required

string

Buyer-issued version or revision for this purchase order.

operation

Required

enum

Standard document operation. Legacy PO change requests map to update.

newupdatedelete

orderType

enum

Type of purchase order

regularblanketreleasestanding

orderDate

Required

string (date-time)

Date and time the buyer issued the order.

requestedDeliveryDate

Required

string (date-time)

Buyer-requested delivery date for the order.

comments

string

General order comments or instructions

dropship

boolean

Indicates if this is a direct ship/dropship order. When true, shipping address should be included in outbound mappings (e.g., NetSuite sales orders).

buyer

Required

object

Party placing the order.

Object fieldsExpand

id

Required

string

name

Required

string

taxRegistrations

object

Australian tax registrations for the party

contact

object

address

object

Standard address structure for DataShift canonical documents

supplier

Required

object

Party expected to fulfil the order.

Object fieldsExpand

id

Required

string

name

Required

string

taxRegistrations

object

Australian tax registrations for the party

contact

object

address

object

Standard address structure for DataShift canonical documents

billTo

Required

object

Billing destination supplied by the buyer.

Object fieldsExpand

addressId

string

addressee

string

street1

Required

string

street2

string

city

Required

string

state

Required

string

postalCode

Required

string

country

Required

enum

AU

shipTo

Required

object

Delivery destination for the ordered goods.

Object fieldsExpand

addressId

string

addressee

string

street1

Required

string

street2

string

city

Required

string

state

Required

string

postalCode

Required

string

country

Required

enum

AU

shipping

object

Commercial freight charges and instructions.

Object fieldsExpand

amount

number

currency

enum

ISO 4217 currency codes supported by DataShift canonical schemas

AUD

carrier

string

route

string

Shipping route method

shippingInstructions

string

Detailed shipping instructions

buyerAcctNumber

string

incoTerms

enum

cfrcifcipcptdafdapddpddudpudeqdesexwfasfcafob

lineItems

Required

PurchaseOrderLineItem[]

Ordered product lines. DataShift manages uniqueLineKey for cross-document line correlation where needed.

orderTotals

Required

PurchaseOrderTotals

extrinsics

object

Partner-specific extension fields that are not part of the canonical core contract.

Line Items

PurchaseOrderLineItem

19 fields9 required1 managed

lineNumber

Required

integer

Buyer line number from the purchase order.

uniqueLineKey

DataShift-managed system

string

DataShift-managed stable line key used by DataShift connectors to correlate PO, POA, ASN, and INV lines.

supplierItemId

Required

string

supplierItemAuxiliaryId

string

Supplier's alternate/auxiliary part ID

buyerItemId

Required

string

description

string

quantity

Required

number

Ordered quantity for this line.

unitOfMeasure

Required

enum

Unit of measure code for the ordered quantity.

AYBGBLBRBLLE2BOBXBJBEKACACGCTCQCSCMTCLCHMTQCYDAYDCDZNDREAFOTGRMHURCENINHJRKGMKMTKTLNLKLTRMTRTNEMLTMMTMONPKPDPLPRD97C62PGLBRRLROSASESETSTSOMTKU3MILTUWEE

unitPrice

Required

number

currency

Required

enum

ISO 4217 currency code for line pricing.

AUD

lineAmountExTax

Required

number

lineAmountInclTax

Required

number

requestedDeliveryDate

string (date-time)

priceBasisQuantityQuantity

number

Price basis quantity

priceBasisQuantityConversionFactor

number

Price basis conversion factor

priceBasisQuantityUnitOfMeasure

string

Price basis unit of measure

classificationDomain

string

Product classification domain

classificationCode

string

Product classification code

comments

string

Line item specific comments

Totals

PurchaseOrderTotals

4 fields4 required

Order-level subtotal, tax, and total amounts.

subtotal

Required

number

taxAmount

Required

number

totalAmount

Required

number

currency

Required

enum

ISO 4217 currency codes supported by DataShift canonical schemas

AUD