INVCanonical document

Invoice

Root model

Invoice

Schema version

1.1.0

Sections

5 contract parts

Overview

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

Endpoints

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

GET

Download Invoice schema

application/schema+jsonapplication/json

/schemas/v1/invoice.schema.json

Invoice JSON Schema

GET

Invoice

text/html

/schemas/invoice

Invoice documentation page

Payload Structure

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.

Envelope

Invoice

5 fields5 required

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

docType

Required

object

Canonical document type. For invoices this value is INV.

correlationId

Required

string (uuid)

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

timestamp

Required

string (date-time)

UTC timestamp indicating when DataShift created the canonical invoice.

metadata

Required

InvoiceMetadata

data

Required

InvoiceData

Metadata

InvoiceMetadata

2 fields2 required

Public source metadata retained for integration troubleshooting.

sourceLanguage

Required

enum

jsoncxml

sourceVersion

Required

string

Data

InvoiceData

23 fields7 required

Business payload for the invoice.

invoiceNumber

Required

string

Supplier-generated invoice number.

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 a new invoice or cancels an existing one

newdelete

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)

poReferences

object[]

Purchase orders being invoiced.

asnReference

object

Shipment notice reference when invoicing against a dispatched shipment.

supplier

Required

object

Supplier or seller issuing the invoice.

billTo

Required

object

Buyer billing party.

soldTo

composition

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

shipTo

object

See public DataShift EDI documentation for allowed values.

remitTo

object

Address where payment should be sent

shippingDetails

object

Shipping information for the invoiced goods

paymentTerms

object

Payment terms and conditions

contacts

object[]

Contact information for various roles

comments

string

Invoice-level comments or notes

lineItems

Required

InvoiceLineItem[]

Invoice lines. Use uniqueLineKey when available to correlate back to PO and ASN lines.

invoiceSummary

Required

InvoiceSummary

extrinsics

object

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

Line Items

InvoiceLineItem

25 fields5 required

invoiceLineNumber

Required

integer

Supplier's line number for this invoice line.

uniqueLineKey

string

Stable DataShift 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

object

See public DataShift EDI documentation for allowed values.

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

object

ISO 4217 currency code for this line.

manufacturerPartId

string

Manufacturer's part number

manufacturerName

string

Manufacturer name

countryOfOrigin

string

Country where item was manufactured

serialNumbers

string[]

Serial numbers for serialized items

batchId

string

Lot/batch ID

classification

object[]

Product classification codes

comments

string

Line-level comments

Summary

InvoiceSummary

11 fields4 required

Invoice totals, tax, discounts, and amount due.

subtotal

Required

number

Sum of all line subtotals

shippingAmount

number

Total shipping charges

specialHandlingAmount

number

Special handling charges

taxAmount

Required

number

Total tax amount

taxBreakdown

object[]

Tax breakdown by type/jurisdiction

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

object

See public DataShift EDI documentation for allowed values.