Invoice webhook

Invoice webhook

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.

Basic structure

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: InvoiceHeader, InvoiceLines and InvoiceTotals.

<?xml version="1.0"?>
<Invoice>
    <InvoiceHeader>
        ...
    </InvoiceHeader>
    <InvoiceLines>
        ...
    </InvoiceLines>
    <InvoiceTotals>
        ...
    </InvoiceTotals>
</Invoice>

Invoice header

The invoice header element contains general information about the invoice.

Field Format Description
InvoiceNumber Text Invoice identifier
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

Example

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

Invoice lines

The invoice lines element contains one or more InvoiceLine elements that detail individual charges on the invoice.

Invoice line

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.

Field Format Description
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

Example

<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>
  ...

Invoice totals

Contains a breakdown of the invoice totals.

Field Format Description
TotalAmountExcludingTax Money Total invoice amount before tax is added
TotalTaxAmount Money Total amount of tax
TotalAmountIncludingTax Money Total invoice amount with tax

Example

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

Invoice type

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.
Value Description
Invoice A goods or services invoice
Credit note A credit for the recipient
Debit note A debit for the recipient

Example

<InvoiceType>Invoice</InvoiceType>

Invoice status

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.

Value Description
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.

Example

<InvoiceStatus>Approved</InvoiceStatus>

Charge type

Contains information about the charge type associated with a single invoice line.

Field Format Description
ChargeTypeCode Text The charge type code.
CategoryCode Text Category that the charge type belongs to.

Example

<ChargeType>
    <ChargeTypeCode>A charge type code</ChargeTypeCode>
    <CategoryCode>A category code</CategoryCode>
</ChargeType>

Consignment details

Contains information about the consignment associated with a single invoice line.

Field Format Description
ConsignmentId Integer Unique numeric invoiced consignment identifier
ConsignmentNumber Text Alphanumeric invoiced consignment identifier, this number is not guaranteed to be unique in eCargo

Example

<ConsignmentDetails>
    <ConsignmentNumber>ABC1234</ConsignmentNumber>
    <ConsignmentId>987654321</ConsignmentId>
</ConsignmentDetails>

Tax rate type name

Value Description
Zero rated New Zealand exempt from GST
GST New Zealand New Zealand goods and services tax
GST Australia Australian goods and services tax

Example

<TaxRateTypeName>GST New Zealand</TaxRateTypeName>

Data types

Text

Text fields consists of alphanumeric characters and punctuation characters.

Example

<ChargeCode>Our customer</ChargeCode>

Invoice date

This is the date on the invoice and has no time zone associated with it.

The standard format is yyyy-MM-dd.

Section Description
- 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

Example

<InvoiceIssueDate>2020-11-18</InvoiceIssueDate>

Decimal

Decimal values are numeric values with a whole and the specified number of decimal digits separated by the . decimal separator.

Example

Decimal(2)

<Value>8000.00</Value>
<Value>700.56</Value>
<Value>0.87</Value>

Decimal(4)

<Value>8000.0000</Value>
<Value>700.5632</Value>
<Value>0.8700</Value>

Integer

Integer values are whole numbers without the decimal component.

Example

<ConsignmentId>987654321</Consignment>

Money

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.

Field Format Description
Value Decimal(2) Money amount
Currency Text ISO 4217 currency code

Example

<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.