{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://docs.datashift.com.au/edi/schemas/v1/invoice.schema.json","title":"Invoice (INV) Canonical Schema","description":"Public canonical Invoice contract used to request payment for goods or services supplied against purchase orders and shipments.","version":"1.1.0","type":"object","required":["docType","correlationId","timestamp","metadata","data"],"properties":{"docType":{"description":"Canonical document type. For invoices this value is INV.","x-order":1},"correlationId":{"type":"string","format":"uuid","description":"Stable UUID used to trace this invoice through order, shipment, and payment workflows.","x-order":2},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp indicating when DataShift created the canonical invoice.","x-order":3},"metadata":{"type":"object","required":["sourceLanguage","sourceVersion"],"properties":{"sourceLanguage":{"type":"string","enum":["json","cxml"],"x-order":1},"sourceVersion":{"type":"string","x-order":2}},"additionalProperties":false,"description":"Public source metadata retained for integration troubleshooting.","x-order":4},"data":{"type":"object","required":["invoiceNumber","invoiceDate","purpose","supplier","billTo","lineItems","invoiceSummary"],"properties":{"invoiceNumber":{"type":"string","description":"Supplier-generated invoice number.","x-order":1},"invoiceDate":{"type":"string","format":"date-time","description":"Date and time the supplier issued the invoice.","x-order":2},"dueDate":{"type":"string","format":"date-time","description":"Payment due date.","x-order":3},"purpose":{"type":"string","enum":["standard","creditMemo","debitMemo","lineLevelCreditMemo","lineLevelDebitMemo"],"default":"standard","description":"Invoice business purpose.","x-enum-descriptions":{"standard":"Standard invoice requesting payment.","creditMemo":"Document reducing a previously invoiced amount.","debitMemo":"Document increasing a previously invoiced amount.","lineLevelCreditMemo":"Line-level credit against a previous invoice.","lineLevelDebitMemo":"Line-level debit against a previous invoice."},"x-order":4},"operation":{"type":"string","enum":["new","delete"],"default":"new","description":"Whether this creates a new invoice or cancels an existing one","x-order":5},"invoiceOrigin":{"type":"string","enum":["supplier","buyer"],"description":"Whether invoice was originated by supplier or buyer (ERS)","x-order":6},"isInformationOnly":{"type":"boolean","default":false,"description":"If true, invoice is for information only and no action required","x-order":7},"isERS":{"type":"boolean","default":false,"description":"Evaluated Receipt Settlement invoice","x-order":8},"documentReference":{"type":"object","description":"Reference to previous invoice (for credit/debit memos or cancellations)","properties":{"invoiceId":{"type":"string","x-order":1},"invoiceDate":{"type":"string","format":"date-time","x-order":2},"documentId":{"type":"string","x-order":3},"payloadId":{"type":"string","x-order":4}},"additionalProperties":false,"x-order":9},"poReferences":{"type":"array","description":"Purchase orders being invoiced.","items":{"type":"object","required":["poNumber"],"properties":{"poNumber":{"type":"string","x-order":1},"poVersion":{"type":"string","x-order":2},"documentId":{"type":"string","x-order":3},"payloadId":{"type":"string","x-order":4},"orderDate":{"type":"string","format":"date-time","x-order":5}},"additionalProperties":false},"x-order":10},"asnReference":{"type":"object","description":"Shipment notice reference when invoicing against a dispatched shipment.","properties":{"shipmentId":{"type":"string","x-order":1},"shipmentDate":{"type":"string","format":"date-time","x-order":2},"documentId":{"type":"string","x-order":3},"payloadId":{"type":"string","x-order":4}},"additionalProperties":false,"x-order":11},"supplier":{"type":"object","description":"Supplier or seller issuing the invoice.","properties":{"id":{"type":"string","x-order":1},"name":{"type":"string","x-order":2},"addressee":{"type":"string","x-order":3},"street1":{"type":"string","x-order":4},"street2":{"type":"string","x-order":5},"city":{"type":"string","x-order":6},"state":{"type":"string","x-order":7},"postalCode":{"type":"string","x-order":8},"country":{"type":"string","x-order":9},"taxRegistrations":{"type":"array","description":"Tax registration numbers (VAT, ABN, GST, etc.)","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["VAT","ABN","GST","TIN","EIN","NZBN","ACN"],"description":"Type of tax registration","x-order":1},"value":{"type":"string","x-order":2}},"additionalProperties":false},"x-order":10}},"additionalProperties":false,"x-order":12},"billTo":{"description":"Buyer billing party.","x-order":13},"soldTo":{"allOf":[{"description":"See public DataShift EDI documentation for allowed values."}],"description":"Sold-to party (may differ from bill-to)","x-order":14},"shipTo":{"description":"See public DataShift EDI documentation for allowed values.","x-order":15},"remitTo":{"type":"object","description":"Address where payment should be sent","properties":{"addressId":{"type":"string","x-order":1},"addressee":{"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":{"type":"string","x-order":8},"bankDetails":{"type":"object","properties":{"bankName":{"type":"string","x-order":1},"accountName":{"type":"string","x-order":2},"accountNumber":{"type":"string","x-order":3},"bsb":{"type":"string","x-order":4},"swift":{"type":"string","x-order":5},"iban":{"type":"string","x-order":6}},"additionalProperties":false,"x-order":9}},"additionalProperties":false,"x-order":16},"shippingDetails":{"type":"object","description":"Shipping information for the invoiced goods","properties":{"carrier":{"type":"string","x-order":1},"trackingNumber":{"type":"string","x-order":2},"shippingDate":{"type":"string","format":"date-time","x-order":3}},"additionalProperties":false,"x-order":17},"paymentTerms":{"type":"object","description":"Payment terms and conditions","properties":{"description":{"type":"string","description":"Human-readable payment terms (e.g., 'Net 30', '2/10 Net 30')","x-order":1},"netDays":{"type":"integer","description":"Number of days until payment is due","x-order":2},"discountTerms":{"type":"array","description":"Early payment discount tiers","items":{"type":"object","properties":{"discountPercent":{"type":"number","multipleOf":0.01,"description":"Discount percentage (e.g., 2 for 2%)","x-order":1},"discountDays":{"type":"integer","description":"Days within which discount applies","x-order":2},"discountDueDate":{"type":"string","format":"date","description":"Specific date by which discount applies","x-order":3}},"additionalProperties":false},"x-order":3}},"additionalProperties":false,"x-order":18},"contacts":{"type":"array","description":"Contact information for various roles","items":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["issuerOfInvoice","soldTo","billTo","remitTo","shipFrom","shipTo"],"x-order":1},"name":{"type":"string","x-order":2},"email":{"type":"string","format":"email","x-order":3},"phone":{"type":"string","x-order":4}},"additionalProperties":false},"x-order":19},"comments":{"type":"string","maxLength":2000,"description":"Invoice-level comments or notes","x-order":20},"lineItems":{"type":"array","minItems":1,"items":{"type":"object","required":["invoiceLineNumber","quantity","unitPrice","subtotal","currency"],"properties":{"invoiceLineNumber":{"type":"integer","description":"Supplier's line number for this invoice line.","x-order":1},"uniqueLineKey":{"type":"string","description":"Stable DataShift line key from the original purchase order.","x-order":2},"poLineReference":{"type":"integer","description":"Line number from the purchase order being invoiced.","x-order":3},"asnLineReference":{"type":"integer","description":"Line number from the ship notice","x-order":4},"supplierItemId":{"type":"string","description":"Supplier's part/item number","x-order":5},"buyerItemId":{"type":"string","description":"Buyer's part/item number","x-order":6},"description":{"type":"string","description":"Item description","x-order":7},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity invoiced.","x-order":8},"unitOfMeasure":{"description":"See public DataShift EDI documentation for allowed values.","x-order":9},"unitPrice":{"type":"number","multipleOf":0.0001,"description":"Unit price","x-order":10},"subtotal":{"type":"number","multipleOf":0.01,"description":"Line subtotal before tax and adjustments.","x-order":11},"taxAmount":{"type":"number","multipleOf":0.01,"description":"Tax amount for this line","x-order":12},"taxRate":{"type":"number","multipleOf":0.01,"description":"Tax rate as percentage (e.g., 10 for 10%)","x-order":13},"discountAmount":{"type":"number","multipleOf":0.01,"description":"Discount amount for this line","x-order":14},"shippingAmount":{"type":"number","multipleOf":0.01,"description":"Shipping charge for this line","x-order":15},"grossAmount":{"type":"number","multipleOf":0.01,"description":"Subtotal + tax + shipping before discounts","x-order":16},"netAmount":{"type":"number","multipleOf":0.01,"description":"Gross amount minus discounts","x-order":17},"currency":{"description":"ISO 4217 currency code for this line.","x-order":18},"manufacturerPartId":{"type":"string","description":"Manufacturer's part number","x-order":19},"manufacturerName":{"type":"string","description":"Manufacturer name","x-order":20},"countryOfOrigin":{"type":"string","description":"Country where item was manufactured","x-order":21},"serialNumbers":{"type":"array","items":{"type":"string"},"description":"Serial numbers for serialized items","x-order":22},"batchId":{"type":"string","description":"Lot/batch ID","x-order":23},"classification":{"type":"array","description":"Product classification codes","items":{"type":"object","properties":{"domain":{"type":"string","enum":["UNSPSC","HS","commodity"],"description":"Classification scheme","x-order":1},"code":{"type":"string","x-order":2}},"additionalProperties":false},"x-order":24},"comments":{"type":"string","maxLength":500,"description":"Line-level comments","x-order":25}},"additionalProperties":false},"description":"Invoice lines. Use uniqueLineKey when available to correlate back to PO and ASN lines.","x-order":21},"invoiceSummary":{"type":"object","required":["subtotal","taxAmount","dueAmount","currency"],"description":"Invoice totals, tax, discounts, and amount due.","properties":{"subtotal":{"type":"number","multipleOf":0.01,"description":"Sum of all line subtotals","x-order":1},"shippingAmount":{"type":"number","multipleOf":0.01,"description":"Total shipping charges","x-order":2},"specialHandlingAmount":{"type":"number","multipleOf":0.01,"description":"Special handling charges","x-order":3},"taxAmount":{"type":"number","multipleOf":0.01,"description":"Total tax amount","x-order":4},"taxBreakdown":{"type":"array","description":"Tax breakdown by type/jurisdiction","items":{"type":"object","properties":{"taxType":{"type":"string","enum":["GST","VAT","salesTax","excise","other"],"description":"Type of tax","x-order":1},"taxRate":{"type":"number","multipleOf":0.01,"description":"Tax rate as percentage","x-order":2},"taxableAmount":{"type":"number","multipleOf":0.01,"description":"Amount subject to this tax","x-order":3},"taxAmount":{"type":"number","multipleOf":0.01,"description":"Calculated tax amount","x-order":4},"jurisdiction":{"type":"string","description":"Tax jurisdiction (e.g., state, country)","x-order":5},"description":{"type":"string","x-order":6}},"additionalProperties":false},"x-order":5},"discountAmount":{"type":"number","multipleOf":0.01,"description":"Total discount amount","x-order":6},"grossAmount":{"type":"number","multipleOf":0.01,"description":"Subtotal + tax + shipping + handling before discounts","x-order":7},"netAmount":{"type":"number","multipleOf":0.01,"description":"Gross amount minus discounts","x-order":8},"depositAmount":{"type":"number","multipleOf":0.01,"description":"Prepayment/deposit already received","x-order":9},"dueAmount":{"type":"number","multipleOf":0.01,"description":"Amount due (net - deposits)","x-order":10},"currency":{"description":"See public DataShift EDI documentation for allowed values.","x-order":11}},"additionalProperties":false,"x-order":22},"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":23}},"additionalProperties":false,"description":"Business payload for the invoice.","x-order":5}},"additionalProperties":false,"examples":[{"docType":"INV","correlationId":"43e7580b-e592-46bb-a3d0-dbf8997758d9","timestamp":"2026-05-16T04:00:00Z","metadata":{"sourceLanguage":"cxml","sourceVersion":"1.2.067"},"data":{"invoiceNumber":"INV-10001","invoiceDate":"2026-05-16T04:00:00Z","dueDate":"2026-06-15T00:00:00Z","purpose":"standard","poReferences":[{"poNumber":"PO-10001","poVersion":"1"}],"supplier":{"id":"SUPPLIER-AU","name":"Example Supplier Pty Ltd","street1":"20 Supplier Street","city":"Adelaide","state":"SA","postalCode":"5000","country":"AU"},"billTo":{"name":"Example Buyer Accounts"},"lineItems":[{"invoiceLineNumber":1,"uniqueLineKey":"PO-10001-1","poLineReference":1,"supplierItemId":"SUP-001","buyerItemId":"BUY-001","description":"Example product","quantity":12,"unitOfMeasure":"EA","unitPrice":25,"subtotal":300,"taxAmount":30,"currency":"AUD"}],"invoiceSummary":{"subtotal":300,"taxAmount":30,"grossAmount":330,"netAmount":330,"dueAmount":330,"currency":"AUD"},"extrinsics":{"accountsReference":"AP-10001"}}}]}