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