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.

Response codes

When the request is posted to the subscriber’s destination endpoint, the webhook’s behaviour differs depending on the HTTP status code returned.

Messages will be sent sequentially to the endpoint to preserve the order of events. This means that continued 5xx errors will prevent further messages from being sent until the error is resolved or the retry limit is reached.

XML schema definition

The intention of this file is to allow third parties to conveniently generate code based on this schema. Do not use it to validate the consignment webhook content.

In the future additional 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.

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.

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.

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.

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.

Example

<InvoiceStatus>Approved</InvoiceStatus>

Charge type

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

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.

Example

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

Tax rate type name

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.

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.

Example

<TotalAmountIncludingTax>
    <Value>121.11</Value>
    <Currency>NZD</Currency>
</TotalAmountIncludingTax>