{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://docs.datashift.com.au/edi/schemas/v1/purchase-order.schema.json","title":"Purchase Order (PO) Canonical Schema","description":"Public canonical Purchase Order contract used to represent a buyer's order before acknowledgement, shipment, and invoice events.","version":"1.0.0","type":"object","required":["docType","correlationId","timestamp","metadata","data"],"properties":{"docType":{"description":"Canonical document type. For purchase orders this value is PO.","x-order":1},"correlationId":{"type":"string","format":"uuid","description":"Stable UUID used to trace this purchase order through downstream acknowledgements, shipments, invoices, and support workflows.","x-order":2},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp indicating when DataShift created the canonical document.","x-order":3},"metadata":{"type":"object","description":"Public source metadata retained for integration troubleshooting without exposing tenant or credential details.","required":["sourceLanguage","sourceVersion"],"properties":{"sourceLanguage":{"type":"string","enum":["json","cxml"],"x-order":1},"sourceVersion":{"type":"string","x-order":2},"payloadId":{"type":"string","description":"Original cXML payload ID","x-order":3},"userAgent":{"type":"string","description":"System that generated the document","x-order":4}},"additionalProperties":false,"x-order":4},"data":{"type":"object","required":["poNumber","poVersion","requestType","orderDate","requestedDeliveryDate","buyer","supplier","billTo","shipTo","lineItems","orderTotals"],"properties":{"poNumber":{"type":"string","description":"Buyer-issued purchase order number. Use this as the primary business reference.","x-order":1},"poVersion":{"type":"string","description":"Buyer-issued version or revision for this purchase order.","x-order":2},"requestType":{"type":"string","enum":["new","change"],"description":"Indicates whether this order creates a new PO or changes an existing one.","x-enum-descriptions":{"new":"Creates a new purchase order.","change":"Changes a previously issued purchase order."},"x-order":3},"orderType":{"type":"string","enum":["regular","blanket","release","standing"],"description":"Type of purchase order","x-order":4},"orderDate":{"type":"string","format":"date-time","description":"Date and time the buyer issued the order.","x-order":5},"requestedDeliveryDate":{"type":"string","format":"date-time","description":"Buyer-requested delivery date for the order.","x-order":6},"comments":{"type":"string","description":"General order comments or instructions","x-order":7},"dropship":{"type":"boolean","description":"Indicates if this is a direct ship/dropship order. When true, shipping address should be included in outbound mappings (e.g., NetSuite sales orders).","x-order":8},"buyer":{"type":"object","required":["id","name","taxId"],"properties":{"id":{"type":"string","x-order":1},"name":{"type":"string","x-order":2},"taxId":{"type":"string","x-order":3},"contact":{"type":"object","properties":{"name":{"type":"string","x-order":1},"phone":{"type":"string","x-order":2},"email":{"type":"string","x-order":3},"role":{"type":"string","description":"Contact role (buyer, technical, etc)","x-order":4}},"additionalProperties":false,"x-order":4}},"additionalProperties":false,"description":"Party placing the order.","x-order":9},"supplier":{"type":"object","required":["id","name","taxId"],"properties":{"id":{"type":"string","x-order":1},"name":{"type":"string","x-order":2},"taxId":{"type":"string","x-order":3},"contact":{"type":"object","properties":{"name":{"type":"string","x-order":1},"phone":{"type":"string","x-order":2},"email":{"type":"string","x-order":3}},"additionalProperties":false,"x-order":4},"address":{"type":"object","description":"Supplier's business address","properties":{"street1":{"type":"string","x-order":1},"street2":{"type":"string","x-order":2},"city":{"type":"string","x-order":3},"state":{"type":"string","x-order":4},"postalCode":{"type":"string","x-order":5},"country":{"description":"See public DataShift EDI documentation for allowed values.","x-order":6}},"additionalProperties":false,"x-order":5}},"additionalProperties":false,"description":"Party expected to fulfil the order.","x-order":10},"billTo":{"type":"object","required":["address","street1","city","state","postalCode","country"],"properties":{"address":{"type":"string","x-order":1},"street1":{"type":"string","x-order":2},"street2":{"type":"string","x-order":3},"city":{"type":"string","x-order":4},"state":{"type":"string","x-order":5},"postalCode":{"type":"string","x-order":6},"country":{"description":"See public DataShift EDI documentation for allowed values.","x-order":7},"phone":{"type":"string","x-order":8},"email":{"type":"string","x-order":9}},"additionalProperties":false,"description":"Billing destination supplied by the buyer.","x-order":11},"shipTo":{"type":"object","required":["address","street1","city","state","postalCode","country"],"properties":{"addressId":{"type":"string","x-order":1},"address":{"type":"string","x-order":2},"street1":{"type":"string","x-order":3},"street2":{"type":"string","x-order":4},"city":{"type":"string","x-order":5},"state":{"type":"string","x-order":6},"postalCode":{"type":"string","x-order":7},"country":{"description":"See public DataShift EDI documentation for allowed values.","x-order":8},"phone":{"type":"string","x-order":9},"email":{"type":"string","x-order":10},"contact":{"type":"object","description":"Ship-to location contact","properties":{"name":{"type":"string","x-order":1},"phone":{"type":"string","x-order":2},"email":{"type":"string","x-order":3}},"additionalProperties":false,"x-order":11}},"additionalProperties":false,"description":"Delivery destination for the ordered goods.","x-order":12},"shipping":{"type":"object","properties":{"carrier":{"type":"string","x-order":1},"charges":{"type":"number","x-order":2},"buyerAcctNumber":{"type":"string","x-order":3},"route":{"type":"string","description":"Shipping route method","x-order":4},"shippingInstructions":{"type":"string","description":"Detailed shipping instructions","x-order":5}},"additionalProperties":false,"x-order":13},"lineItems":{"type":"array","minItems":1,"items":{"type":"object","required":["lineNumber","supplierItemId","buyerItemId","quantity","unitOfMeasure","unitPrice","currency","lineAmountExTax","lineAmountInclTax"],"properties":{"lineNumber":{"type":"integer","description":"Buyer line number from the purchase order.","x-order":1},"uniqueLineKey":{"type":"string","description":"DataShift-generated stable line key used to correlate PO, POA, ASN, and INV lines.","x-order":2},"supplierItemId":{"type":"string","x-order":3},"supplierItemAuxiliaryId":{"type":"string","description":"Supplier's alternate/auxiliary part ID","x-order":4},"buyerItemId":{"type":"string","x-order":5},"description":{"type":"string","x-order":6},"quantity":{"type":"number","multipleOf":0.01,"description":"Ordered quantity for this line.","x-order":7},"unitOfMeasure":{"description":"Unit of measure code for the ordered quantity.","x-order":8},"unitPrice":{"type":"number","x-order":9},"currency":{"description":"ISO 4217 currency code for line pricing.","x-order":10},"lineAmountExTax":{"type":"number","x-order":11},"lineAmountInclTax":{"type":"number","x-order":12},"requestedDeliveryDate":{"type":"string","format":"date-time","x-order":13},"priceBasisQuantityQuantity":{"type":"number","description":"Price basis quantity","x-order":14},"priceBasisQuantityConversionFactor":{"type":"number","description":"Price basis conversion factor","x-order":15},"priceBasisQuantityUnitOfMeasure":{"type":"string","description":"Price basis unit of measure","x-order":16},"classificationDomain":{"type":"string","description":"Product classification domain","x-order":17},"classificationCode":{"type":"string","description":"Product classification code","x-order":18},"comments":{"type":"string","description":"Line item specific comments","x-order":19}},"additionalProperties":false},"description":"Ordered product lines. Use uniqueLineKey for cross-document line correlation when present.","x-order":14},"orderTotals":{"type":"object","required":["subtotal","taxAmount","totalAmount","currency"],"properties":{"subtotal":{"type":"number","x-order":1},"taxAmount":{"type":"number","x-order":2},"totalAmount":{"type":"number","x-order":3},"currency":{"description":"See public DataShift EDI documentation for allowed values.","x-order":4}},"additionalProperties":false,"description":"Order-level subtotal, tax, and total amounts.","x-order":15},"extrinsics":{"type":"object","description":"Partner-specific extension fields that are not part of the canonical core contract.","additionalProperties":{"x-additionalPropertiesName":"extensionField","description":"Partner-specific extension value."},"x-order":16}},"additionalProperties":false,"description":"Business payload for the purchase order.","x-order":5}},"additionalProperties":false,"examples":[{"docType":"PO","correlationId":"8d359a0f-3e5a-4d36-a87c-f2748b1d6b43","timestamp":"2026-05-16T00:00:00Z","metadata":{"sourceLanguage":"cxml","sourceVersion":"1.2.067","payloadId":"po-example-10001"},"data":{"poNumber":"PO-10001","poVersion":"1","requestType":"new","orderDate":"2026-05-16T00:00:00Z","requestedDeliveryDate":"2026-05-23T00:00:00Z","buyer":{"id":"BUYER-AU","name":"Example Buyer Pty Ltd","taxId":"AU123456789"},"supplier":{"id":"SUPPLIER-AU","name":"Example Supplier Pty Ltd","taxId":"AU987654321"},"billTo":{"address":"Example Buyer Accounts","street1":"1 Market Street","city":"Sydney","state":"NSW","postalCode":"2000","country":"AU"},"shipTo":{"address":"Example Distribution Centre","street1":"10 Warehouse Road","city":"Melbourne","state":"VIC","postalCode":"3000","country":"AU"},"lineItems":[{"lineNumber":1,"uniqueLineKey":"PO-10001-1","supplierItemId":"SUP-001","buyerItemId":"BUY-001","description":"Example product","quantity":12,"unitOfMeasure":"EA","unitPrice":25,"currency":"AUD","lineAmountExTax":300,"lineAmountInclTax":330}],"orderTotals":{"subtotal":300,"taxAmount":30,"totalAmount":330,"currency":"AUD"},"extrinsics":{"department":"Operations"}}}]}