Update rates

Update rates API

In order to update rates in eCargo, you will need to create an update rates XML file and then send it to us via an HTTP POST request to https://www.ecargo.co.nz/api.v3/UpdateRates or https://test.ecargo.co.nz/api.v3/UpdateRates.

Ensure that you have the correct authorisation scheme information in the request headers. See the authorisation section for details.

The file must be a well formed XML document and start with an XML declaration. The file should also conform to the other specifications mentioned in the XML specification. To indicate the absence of a value (i.e. null), omit the element entirely. Otherwise, an empty element will be taken to mean a string of length zero, or empty string.

Example

This is an example of a complete HTTP request including the required headers.

POST /api.v3/UpdateRates HTTP/1.1
Host: ecargo.co.nz
Content-Type: application/xml; charset=utf-8
Authorization: eCargoApiKey senderId=10000,senderApiKey=...

<UpdateRates>
    <Updates>
        <SetRateCards>
            <RateCard>
                <RateCardType>Customer</RateCardType>
                <ChargeTypeCode>SEA_FREIGHT</ChargeTypeCode>
                <Customer>Shipping customer</Customer>
                <Carrier>Shipping line</Carrier>
                <Supplier>Shipping line</Supplier>
                <FromZone>Auckland</FromZone>
                <ToZone>Sydney</ToZone>
                <CurrencyCode>USD</CurrencyCode>
                <ConsignmentRateProduct>40FT</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>1568</Rate>
                            </RateTier>
                        </RateTiers>
                    </RateTierSet>
                </RateTierSets>
            </RateCard>
            <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>
        </SetRateCards>
    </Updates>
</UpdateRates>

HTTP requests

In order to send documents to us, the documents must have a Content-Type header of application/xml. For example application/xml; charset=utf-8.

The Accept header is optional, but be aware that if supplied the only acceptable type is application/xml.

Authorisation

The authorisation scheme for the API is the eCargoApiKey authorisation scheme which is stored in the Authorization header.

eCargo will provide the value of the 2 required parameters for authorisation with the API:

  • senderId
  • senderApiKey

Example

POST /api.v3/UpdateRates HTTP/1.1
Host: ecargo.co.nz
Content-Type: application/xml; charset=utf-8
Authorization: eCargoApiKey senderId=10000,senderApiKey=...

HTTP responses

Responses will use standard HTTP response codes.

The response for a successful submission will be an HTTP 2xx, with no content.

You will never receive a 3xx response.

Error responses will be in the 4xx and 5xx ranges, with details in the response body:

<Error>
    <ErrorType>The broad category of the error.</ErrorType>
    <Reason>The reason for rejecting your request.</Reason>
    <PossibleSolution>A suggestion that may assist in rectifying the issue.</PossibleSolution>
    <ActivityId>An ID that will assist eCargo in diagnosing the cause of failure.</ActivityId>
</Error>

Authentication failures will return the standard, unauthorized HTTP status code of 401.

For security reasons, if eCargo is unable to automatically determine the cause of a failure, a generic error will be returned.

All responses will include an eCargo-ActivityId header. This is a unique identifier that you can quote to eCargo support and will assist us in diagnosing the cause of failure. Error responses will usually also include the ‘Activity ID’ in the XML body.

Note that, if any of the actions in a single request fail, they will be rolled back and no changes will be applied. It is safe to retry requests because the API is idempotent.

Also note that there is no X- prefix on the custom activity ID header because this practice has been deprecated by RFC 6648.

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

Updates

The basic structure consists of the XML declaration at the top followed by the UpdateRates element which contains a single child Updates element.

<UpdateRates>
    <Updates>
        ...
    </Updates>
</UpdateRates>

The Updates element specifies the updates to be applied to existing rate cards via the SetRateCard element.

<UpdateRates>
    <Updates>
        <SetRateCards>
            ...
        </SetRateCards>
    </Updates>
</UpdateRates>

Set rate cards

The SetRateCards element consists of a list of RateCard elements that specify rate card data.

<UpdateRates>
    <Updates>
        <SetRateCards>
            <RateCard>
                ...
            </RateCard>
            <RateCard>
                ...
            </RateCard>
            ...
        </SetRateCards>
    </Updates>
</UpdateRates>

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

Field Required Format Description
RateCardType Yes Rate card type The rate card type name
ChargeTypeCode Yes Free text (62) The code as seen when viewing charge types
Customer Yes Free text (128) The freight consignment owner
Carrier No Free text (128) The name of a carrier business
Supplier Yes Free text (128) The name of a supplier business
SoldTo No Free text (128) The name of the sold-to business. Currently ignored by the API.
FromZone Yes Free text (50) The name of the from-zone mapping
ToZone Yes Free text (50) The name of the to-zone mapping
CurrencyCode Yes Currency code ISO 4217 currency code
ConsignmentRateProduct Yes Free text (50) The name of the product
EffectiveFromLocalDateInclusive Yes Date The start date at which the rate card will apply
EffectiveToLocalDateInclusive No Date The expiry date of the rate card
RateTierSets Yes Rate tier sets The rate tier sets on the rate card

Rate card type

The supported rate card types are:

Value Description
Supplier This is a supplier rate card
Customer This is a customer rate card

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 a single rate tier set.

Field Required Format Description
RateTierSet Yes Rate tier set The rate tier set

Example

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

Field Required Format Description
UnitOfMeasureCode Yes Unit of measure Unit of measure code
ChargePerQuantity Yes Integer How the rate is charged per quantity of units, with a minimum of 1
RateTiers Yes Rate tiers Rate tiers to apply

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 a single rate tier.

Field Required Format Description
RateTier Yes Rate tier Rate tier to apply

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.

Field Required Format Description
TierFromInclusive Yes Decimal The lower limit of this tier, with a minimum of 0 if no lower limit should be set
Rate Yes Decimal The charge-per unit for quantities in this tier

Example

<RateTierSets>
    <RateTierSet>
        <UnitOfMeasure>container</UnitOfMeasure>
        <ChargePerQuantity>1</ChargePerQuantity>
        <RateTiers>
            <RateTier>
                <TierFromInclusive>0</TierFromInclusive>
                <Rate>1064</Rate>
            </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>, %, &, (, ), *, +, <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.

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

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