Rates webhook

The rates webhook automatically sends rates related data from eCargo to your system when changes are made to the rates in eCargo. Changes could be made by a user making changes in the eCargo application or by calling the update-rates API.

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 consignment 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 a single RatesChanged element, some details about the change that triggered the webhook, and the rate cards that were affected.

<?xml version="1.0" encoding="utf-8"?>
<RatesChanged xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://ecargo.co.nz/Info/static/xsd/RatesWebhook.xsd">
    <ChangeMadeAt>2017-11-05T07:04:08Z</ChangeMadeAt>
    <ActivityId>5d5f3494-7d08-437b-a838-152439c4d585</ActivityId>
    <Added>
        ... zero or more rate cards
    </Added>
    <Deleted>
        ... zero or more rate cards
    </Deleted>
</RatesChanged>

Header fields

The header section contains details about the change that triggered this webhook and the eCargo activity ID related to this change.

Rate change descriptions

Rates are immutable in eCargo to preserve the history of the rate and ensure that rates used in existing freight calculations are not changed. This means that there are only two operations possible for rates: add and delete. Deleting a rate that has already been used in a freight calculation will prevent future freight calculations from using the rate, but will not remove it from existing calculations.

There will always be a section called Added, and another called Deleted, and these sections will contain zero or more rate cards. The rate cards sent by this webhook follow the same structure as the update-rates API, and are detailed below.

Below is an example where a single rate card was added:

<?xml version="1.0" encoding="utf-8"?>
<RatesChanged xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://ecargo.co.nz/Info/static/xsd/RatesWebhook.xsd">
    <ChangeMadeAt>2017-11-05T07:04:08Z</ChangeMadeAt>
    <ActivityId>5d5f3494-7d08-437b-a838-152439c4d585</ActivityId>
    <Added>
        <RateCard>
            <RateCardType>Supplier</RateCardType>
            <ChargeTypeCode>SEA_FREIGHT</ChargeTypeCode>
            <Customer>Shipping customer</Customer>
            <Carrier>Shipping line</Carrier>
            <Supplier>Shipping line</Supplier>
            <SoldTo>Sold-to party</SoldTo>
            <FromZone>Lyttelton</FromZone>
            <ToZone>Sydney</ToZone>
            <CurrencyCode>USD</CurrencyCode>
            <ConsignmentRateProduct>TEU</ConsignmentRateProduct>
            <EffectiveFromLocalDateInclusive>2020-08-01</EffectiveFromLocalDateInclusive>
            <EffectiveToLocalDateInclusive>2020-08-31</EffectiveToLocalDateInclusive>
            <RateTierSets>
                <RateTierSet>
                    <UnitOfMeasure>container</UnitOfMeasure>
                    <ChargePerQuantity>1</ChargePerQuantity>
                    <RateTiers>
                        <RateTier>
                            <TierFromInclusive>0</TierFromInclusive>
                            <Rate>1064</Rate>
                        </RateTier>
                    </RateTiers>
                </RateTierSet>
            </RateTierSets>
        </RateCard>
    </Added>
    <Deleted>
    </Deleted>
</RatesChanged>

The RateCard type

Below is a description of the RateCard type.

Rate card details

The RateCard element describes the rate card to be updated and consists of information to identify the rate card and the updates to be applied.

A rate card is uniquely identified by a combination of field values:

• RateCardType
• ChargeTypeCode
• Customer
• Carrier
• FromZone
• ToZone
• ConsignmentRateProduct

For a more detailed explanation on rate cards, please see the rate card documentation.

Documentation

Rate card

Rate card type

The supported rate card types are:

Charge type code

The code of the charge type when viewed through the charge types administration page.

Example

• SEA_FREIGHT (Export shipping sea freight charges)
• SF_DOCUMENTATION_FEE (Export shipping documentation fee)
• COASTAL (Coastal shipping)

Currency code

The currency code must be a standard 3 letter alphabetic currency codes defined by the ISO 4217 standard.

Example

• NZD (New Zealand Dollar)
• USD (United States Dollar)
• AUD (Australian Dollar)

Effective dates

The effective dates indicate when the rates on the rate card will take effect and consist of a range specified by the 2 date values.

EffectiveFromLocalDateInclusive

The rates will take effect at midnight in the morning of the date specified by this date.

EffectiveToLocalDateInclusive

The rates will no longer apply after midnight of the date specified by this date. If this date does not have a value then the rate card will never expire.

Rate tier sets

The rate tier sets consists of one or more tier sets.

Example

<RateTierSets>
    <RateTierSet>
        ...
    </RateTierSet>
    <RateTierSet>
        ...
    </RateTierSet>
</RateTierSets>

Rate tier set

The rate tier set includes charge-per-unit information and the rate tiers to apply when the rate card takes effect.

Example

To set a rate tier set which will be applied per container.

<RateTierSets>
    <RateTierSet>
        <UnitOfMeasure>container</UnitOfMeasure>
        <ChargePerQuantity>1</ChargePerQuantity>
        <RateTiers>
            ...
        </RateTiers>
    </RateTierSet>
</RateTierSets>

Unit of measure

Unit of measure codes are lookup values specified by eCargo.

You can find the unit of measure codes that you need to send us on the unit of measure page.

This API uses the New APIs codes.

Rate tiers

The rate tiers consist of one or more tiers.

Example

<RateTierSets>
    <RateTierSet>
        <UnitOfMeasure>container</UnitOfMeasure>
        <ChargePerQuantity>1</ChargePerQuantity>
        <RateTiers>
            <RateTier>
                ...
            </RateTier>
        </RateTiers>
    </RateTierSet>
</RateTierSets>

Rate tier

The rate tier contains the conditions under which the rate will apply, along with the rate itself.

Example

<RateTierSets>
    <RateTierSet>
        <UnitOfMeasure>container</UnitOfMeasure>
        <ChargePerQuantity>1</ChargePerQuantity>
        <RateTiers>
            <RateTier>
                <TierFromInclusive>0</TierFromInclusive>
                <Rate>1064</Rate>
                <Minimum>5000</Minimum>
            </RateTier>
        </RateTiers>
    </RateTierSet>
</RateTierSets>

Data types

Free text

Free text values allow only ASCII alphanumeric characters and some punctuation characters.

The following punctuation characters are supported by the API:

<space>, %, & (&amp;), (, ), *, +, <comma>, -, ., /, :, _

Example

<ChargeTypeCode>SEA_FREIGHT</ChargeTypeCode>

Date

The standard format is yyyy-MM-dd.

Note that datetime in eCargo does not correspond to a particular timezone, please ensure that the datetime values being passed into eCargo from your system via the API are internally consistent to your system.

Example

<EffectiveFromLocalDateInclusive>2020-10-08</EffectiveFromLocalDateInclusive>

Integer

Integer values are whole numbers without the decimal component.

The allowed characters for this value are the numeric characters.

Example

<ChargePerQuantity>1</ChargePerQuantity>

Decimal

Decimal values are non-negative values with up to 4 decimal places and a maximum allowable value of 99,999,999.9999.

The allowed characters for this value are the numeric characters and the . decimal separator. No thousands separator is supported.

Example

<Rate>8000</Rate>
<Rate>700.56</Rate>
<Rate>24850.4045</Rate>
<Rate>0.8795</Rate>