The invoice webhook automatically sends invoice related data from eCargo to your system.
It automatically sends the data based on a set of configurable rules e.g. when an invoice for a specific customer is approved.
To subscribe to this webhook please contact eCargo support.
Authorisation and security
You will need to provide us with your HTTPS URL and credentials. Webhooks support basic authentication, so you will need to respond to unauthenticated requests with a
WWW-Authenticate: Basic header.
XML schema definition
The intention of this file is to allow third parties to conveniently generate code based on this schema. In no way should it be used to comprehensively validate the invoice webhook content.
In the future additional optional elements may be added and any new additions should not be treated as a breaking change.
An XSD can be downloaded from here.
The invoice webhook message is a well formed XML document. It conforms to the specifications mentioned in the XML specification.
The basic structure of the message consists of the XML declaration at the top, followed by the
Invoice section, which contains three major sections:
<?xml version="1.0"?> <Invoice> <InvoiceHeader> ... </InvoiceHeader> <InvoiceLines> ... </InvoiceLines> <InvoiceTotals> ... </InvoiceTotals> </Invoice>
The invoice header element contains general information about the invoice.
|InvoiceIssueDate||Invoice date||The date the invoice is issued|
|Supplier||Text||The issuer of the invoice|
|Recipient||Text||The recipient of the invoice|
|InvoiceType||Invoice type||The catergory of invoice|
|InvoiceStatus||Invoice status||The state the invoice is in|
|ChargeCode||Text||Optional value specified by supplier|
|ExternalReference||Text||Optional value specified by supplier|
<Invoice> <InvoiceHeader> <InvoiceNumber>12345</InvoiceNumber> <InvoiceIssueDate>2020-10-01</InvoiceIssueDate> <Supplier> <Name>ABC</Name> </Supplier> <Recipient> <Name>XYZ</Name> </Recipient> <InvoiceType>Credit note</InvoiceType> <InvoiceStatus>Approved</InvoiceStatus> <ChargeCode>RoadFreight</ChargeCode> <ExternalReference>JKL1234</ExternalReference> </InvoiceHeader> ... </Invoice>
The invoice lines element contains one or more
InvoiceLine elements that detail individual charges on the invoice.
An invoice line element contains details about a specific charge on the invoice.
Note 1: The
ConsignmentDetails section is optional. In the future eCargo will support line items for charges that are not associated with a consignment.
|ChargeType||Charge type||Charge type information for this invoice line.|
|ConsignmentDetails||Consignment details||Optional information about the invoiced consignment|
|TaxRateTypeName||Tax rate type name||A description of the tax rate type|
|RatePercent||Decimal(4)||Tax rate as a percentage|
|AmountExcludingTax||Money||Amount invoiced before tax is added|
<Invoice> ... <InvoiceLines> <InvoiceLine> <ChargeType> <ChargeTypeCode>A charge type code</ChargeTypeCode> <CategoryCode>A category code</CategoryCode> </ChargeType> <ConsignmentDetails> <ConsignmentId>987654321</ConsignmentId> <ConsignmentNumber>CONSIGNMENT1234</ConsignmentNumber> </ConsignmentDetails> <TaxRate> <TaxRateTypeName>GST New Zealand</TaxRateTypeName> <RatePercent>15.0000</RatePercent> </TaxRate> <AmountExcludingTax> <Value>10</Value> <Currency>NZD</Currency> </AmountExcludingTax> </InvoiceLine> </InvoiceLines> ...
Contains a breakdown of the invoice totals.
|TotalAmountExcludingTax||Money||Total invoice amount before tax is added|
|TotalTaxAmount||Money||Total amount of tax|
|TotalAmountIncludingTax||Money||Total invoice amount with tax|
<Invoice> ... <InvoiceTotals> <TotalAmountExcludingTax> <Value>110.10</Value> <Currency>NZD</Currency> </TotalAmountExcludingTax> <TotalTaxAmount> <Value>11.01</Value> <Currency>NZD</Currency> </TotalTaxAmount> <TotalAmountIncludingTax> <Value>121.11</Value> <Currency>NZD</Currency> </TotalAmountIncludingTax> </InvoiceTotals> </Invoice>
There are three different invoice types in eCargo: invoice, credit note and debit note.
There are two common scenarios where credit and/or debit notes are used in eCargo:
- A credit note may be issued when a customer returns the goods they purchased.
- An adjustment was made to the invoice. In this case a credit is issued and then the adjustment is issued as a debit note.
|Invoice||A goods or services invoice|
|Credit note||A credit for the recipient|
|Debit note||A debit for the recipient|
There are two different invoice statuses exposed by the invoice webhook: approved and paid. There are other invoice statuses visible in eCargo but these are not supported by the invoice webhook.
|Approved||The invoice has been approved by the sender and issued to the recipient but not yet paid.|
|Paid||The invoice has been issued and paid by the recipient.|
Contains information about the charge type associated with a single invoice line.
|ChargeTypeCode||Text||The charge type code.|
|CategoryCode||Text||Category that the charge type belongs to.|
<ChargeType> <ChargeTypeCode>A charge type code</ChargeTypeCode> <CategoryCode>A category code</CategoryCode> </ChargeType>
Contains information about the consignment associated with a single invoice line.
|ConsignmentId||Integer||Unique numeric invoiced consignment identifier|
|ConsignmentNumber||Text||Alphanumeric invoiced consignment identifier, this number is not guaranteed to be unique in eCargo|
<ConsignmentDetails> <ConsignmentNumber>ABC1234</ConsignmentNumber> <ConsignmentId>987654321</ConsignmentId> </ConsignmentDetails>
Tax rate type name
|Zero rated||New Zealand exempt from GST|
|GST New Zealand||New Zealand goods and services tax|
|GST Australia||Australian goods and services tax|
<TaxRateTypeName>GST New Zealand</TaxRateTypeName>
Text fields consists of alphanumeric characters and punctuation characters.
This is the date on the invoice and has no time zone associated with it.
The standard format is
|-||Literal character ‘-’, used as a separator within the date text|
|yyyy||The year as a 4 digit number|
|MM||The month of the year from 01 through to 12|
|dd||The day of the month from 01 through to 31|
Decimal values are numeric values with a whole and the specified number of decimal digits separated by the
. decimal separator.
<Value>8000.00</Value> <Value>700.56</Value> <Value>0.87</Value>
<Value>8000.0000</Value> <Value>700.5632</Value> <Value>0.8700</Value>
Integer values are whole numbers without the decimal component.
Money fields consists of a decimal
Value field and two decimal places and a
Currency field which contains an ISO 4217 currency code.
Note: This describes a pattern associated with Money rather than a type. Subsequently a parent element named
Money surrounding these fields is not outputted.
|Currency||Text||ISO 4217 currency code|
<TotalAmountIncludingTax> <Value>121.11</Value> <Currency>NZD</Currency> </TotalAmountIncludingTax>
Webhook processing behaviour
When the request is posted to the subscriber’s destination endpoint, the webhook’s behaviour differs depending on the HTTP status code returned.
|Status code class||Behaviour|
|2xx success||Will complete request processsing.|
|4xx client errors||Will not retry sending the request.|
|5xx server errors||Will retry sending the request up to a maximum of 13 attempts. Retransmissions are spaced out using a backoff algorithm.|