DataShift Logo
Back to schemas
INVInvoice

Invoice

Supplier billing document for ordered or shipped goods.

An Invoice requests payment for supplied goods or services and gives the buyer enough line, tax, freight, discount, payment, and reference detail to reconcile against purchase orders, shipment notices, and accounts payable controls.

View releasesView modelView exampleView guides

Lifecycle And Correlation

Lifecycle Position

Follows fulfilment and supports financial reconciliation, payment approval, and exception handling.

Correlation Guidance

Invoice lines should reference the original PO or ASN line with uniqueLineKey for automatic reconciliation. Header references identify the invoiced purchase orders and shipment notice; line references make quantity, price, tax, and credit/debit reconciliation precise.

Validation Notes

  • Require invoiceNumber, invoiceDate, purpose, supplier, billTo, lineItems, and invoiceSummary.
  • Validate purpose before applying credit memo, debit memo, or cancellation logic.
  • Keep line currency and summary currency explicit and consistent unless a documented multi-currency process applies.
  • Validate supplier tax identity through supplier.taxRegistrations and payment routing through remitTo.bankDetails when those controls are required.
  • Validate tax totals against taxBreakdown when a breakdown is supplied.

Mapping Notes

  • Map PO references at the header and preserve uniqueLineKey at the line level for automatic PO, POA, and ASN reconciliation.
  • Use asnReference only when the invoice is explicitly tied to a dispatched shipment; do not fabricate it when the source does not provide an ASN reference.
  • Represent line totals as grossAmount, taxAmount, and netAmount where practical; represent summary totals as grossAmount, taxAmount, shippingAmount, netAmount, and dueAmount.
  • Use documentReference for credit/debit memos or cancellations tied to a previous invoice.

Operational Notes

  • Use invoiceNumber with supplier identity for duplicate detection and accounts payable support.
  • Route line correlation gaps to review instead of reconciling by item description or line order.

Implementation Pitfalls

  • Keep tax, freight, and line totals explicit for reconciliation.
  • Do not rely only on invoice-level totals when line-level tax or credits are present.
  • Do not assume an invoice without uniqueLineKey can be safely matched by invoiceLineNumber, poLineReference, item id, description, quantity, or array position.

Endpoints

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

GET

Download Invoice schema

application/schema+jsonapplication/json
/contracts/releases/1.0.8/schemas/invoice.schema.json

Invoice JSON Schema

GET

Invoice

text/html
/schemas/invoice

Invoice 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

Invoice
5 fields5 required3 managed

Public canonical Invoice contract used to request payment for goods or services supplied against purchase orders and shipments.

docType
RequiredDataShift-managed system
object

Canonical document type. For invoices this value is INV.

INV
correlationId
RequiredDataShift-managed system
string (uuid)

Stable UUID used to trace this invoice through order, shipment, and payment workflows.

timestamp
RequiredDataShift-managed system
string (date-time)

UTC timestamp indicating when DataShift created the canonical invoice.

metadata
Required
data
Required

Metadata

InvoiceMetadata
4 fields3 required

Public source metadata retained for integration troubleshooting.

sourceLanguage
Required
enum
jsoncxml
sourceVersion
Required
object

Canonical schema version used to create this document

1.0.8
payloadId
string

Original cXML payload ID

userAgent
Required
object

DataShift Edge version that generated the canonical document

DataShift Edge v1

Data

InvoiceData
25 fields8 required

Business payload for the invoice.

invoiceNumber
Required
string

Supplier-generated invoice number.

poNumber
Required
string

Primary purchase order number this invoice bills against.

invoiceDate
Required
string (date-time)

Date and time the supplier issued the invoice.

dueDate
string (date-time)

Payment due date.

purpose
Required
enum

Invoice business purpose.

standardcreditMemodebitMemolineLevelCreditMemolineLevelDebitMemo
operation
enum

Whether this creates, updates, or deletes an invoice

newupdatedelete
invoiceOrigin
enum

Whether invoice was originated by supplier or buyer (ERS)

supplierbuyer
isInformationOnly
boolean

If true, invoice is for information only and no action required

isERS
boolean

Evaluated Receipt Settlement invoice

documentReference
object

Reference to previous invoice (for credit/debit memos or cancellations)

Object fieldsExpand
invoiceId
string
invoiceDate
string (date-time)
documentId
string
payloadId
string
poReferences
object[]

Purchase orders being invoiced.

Object fieldsExpand
poNumber
Required
string
poVersion
string
documentId
string
payloadId
string
orderDate
string (date-time)
asnReference
object

Shipment notice reference when invoicing against a dispatched shipment.

Object fieldsExpand
shipmentId
string
shipmentDate
string (date-time)
documentId
string
payloadId
string
supplier
Required
object

Supplier or seller issuing the invoice.

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

Buyer billing party.

Object fieldsExpand
addressId
string
addressee
string
street1
Required
string
street2
string
city
Required
string
state
Required
string
postalCode
Required
string
country
Required
enum
AU
soldTo
composition

Sold-to party (may differ from bill-to)

shipTo
object

Standard address structure for DataShift canonical documents

Object fieldsExpand
addressId
string
addressee
string
street1
Required
string
street2
string
city
Required
string
state
Required
string
postalCode
Required
string
country
Required
enum
AU
remitTo
object

Address where payment should be sent

Object fieldsExpand
addressId
string
addressee
string
street1
string
street2
string
city
string
state
string
postalCode
string
country
enum
AU
bankDetails
object
shipping
object

Commercial freight charges and instructions for the invoice.

Object fieldsExpand
amount
number
currency
enum

ISO 4217 currency codes supported by DataShift canonical schemas

AUD
carrier
string
route
string
shippingInstructions
string
buyerAcctNumber
string
incoTerms
enum
cfrcifcipcptdafdapddpddudpudeqdesexwfasfcafob
shipmentDetails
object

Actual dispatch and tracking information for the invoiced goods

Object fieldsExpand
carrier
string
trackingNumber
string
shippingDate
string (date-time)
paymentTerms
object

Payment terms and conditions

Object fieldsExpand
description
string

Human-readable payment terms (e.g., 'Net 30', '2/10 Net 30')

netDays
integer

Number of days until payment is due

discountTerms
object[]

Early payment discount tiers

contacts
object[]

Contact information for various roles

Object fieldsExpand
role
Required
enum
issuerOfInvoicesoldTobillToremitToshipFromshipTo
name
string
email
string
phone
string
comments
string

Invoice-level comments or notes

lineItems
Required
InvoiceLineItem[]

Invoice lines. DataShift manages uniqueLineKey correlation back to PO and ASN lines where needed.

invoiceSummary
Required
extrinsics
object

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

Line Items

InvoiceLineItem
25 fields5 required1 managed
invoiceLineNumber
Required
integer

Supplier's line number for this invoice line.

uniqueLineKey
DataShift-managed system
string

DataShift-managed stable line key from the original purchase order.

poLineReference
integer

Line number from the purchase order being invoiced.

asnLineReference
integer

Line number from the ship notice

supplierItemId
string

Supplier's part/item number

buyerItemId
string

Buyer's part/item number

description
string

Item description

quantity
Required
number

Quantity invoiced.

unitOfMeasure
enum

UN/ECE Recommendation 20 unit of measure codes for DataShift canonical documents

AYBGBLBRBLLE2BOBXBJBEKACACGCTCQCSCMTCLCHMTQCYDAYDCDZNDREAFOTGRMHURCENINHJRKGMKMTKTLNLKLTRMTRTNEMLTMMTMONPKPDPLPRD97C62PGLBRRLROSASESETSTSOMTKU3MILTUWEE
unitPrice
Required
number

Unit price

subtotal
Required
number

Line subtotal before tax and adjustments.

taxAmount
number

Tax amount for this line

taxRate
number

Tax rate as percentage (e.g., 10 for 10%)

discountAmount
number

Discount amount for this line

shippingAmount
number

Shipping charge for this line

grossAmount
number

Subtotal + tax + shipping before discounts

netAmount
number

Gross amount minus discounts

currency
Required
enum

ISO 4217 currency code for this line.

AUD
manufacturerPartId
string

Manufacturer's part number

manufacturerName
string

Manufacturer name

countryOfOrigin
enum

Country where item was manufactured

AU
serialNumbers
string[]

Serial numbers for serialized items

batchId
string

Lot/batch ID

classification
object[]

Product classification codes

Object fieldsExpand
domain
enum

Classification scheme

UNSPSCHScommodity
code
string
comments
string

Line-level comments

Summary

InvoiceSummary
10 fields3 required

Invoice totals, tax, discounts, and amount due.

shippingAmount
number

Total shipping charges

specialHandlingAmount
number

Special handling charges

taxAmount
Required
number

Total tax amount

taxBreakdown
object[]

Tax breakdown by type/jurisdiction

Object fieldsExpand
taxType
enum

Type of tax

GSTVATsalesTaxexciseother
taxRate
number

Tax rate as percentage

taxableAmount
number

Amount subject to this tax

taxAmount
number

Calculated tax amount

jurisdiction
string

Tax jurisdiction (e.g., state, country)

description
string
discountAmount
number

Total discount amount

grossAmount
number

Subtotal + tax + shipping + handling before discounts

netAmount
number

Gross amount minus discounts

depositAmount
number

Prepayment/deposit already received

dueAmount
Required
number

Amount due (net - deposits)

currency
Required
enum

ISO 4217 currency codes supported by DataShift canonical schemas

AUD