Create consignment API

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 create consignment content.

An XSD can be downloaded from here.

Data driven changes

You can update a consignment once it has been created by sending an updated version of the consignment document.

Most aspects of the consignment can be updated, including consignment details, partners, consignment items, and containers.

However, changes to consignments are only possible before the consignment has been dispatched in eCargo. After the consignment is dispatched further changes can only be made manually by an administrator user in the eCargo application.

One exception to this rule are containers which can be updated even when the consignment has been dispatched or delivered. See containers documentation for more detail.

For further details of which fields can be updated consult the reference documentation for each section.

Getting started

In order to create and update consignments in eCargo, you’ll need to create a consignment XML file, then send it to us.

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.

The basic skeleton for the XML required is as follows.

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        ..Consignment information...
    </Body>
</Message>

The Header element contains information for authentication, along with the document type so eCargo knows what the document is for.

Authentication

The SenderId and APIKey elements are how eCargo authenticates consignment documents. You will be supplied the values you need for these elements by eCargo before you start using the API. If these values are incorrect, your document will be rejected by eCargo.

MessageType

This is just so that eCargo knows what type of document we are receiving, for your purposes this will always be consignment.

For further information on the header element and the associated elements, please see the message header documentation.

Message body

This is where the actual information for updating and creating consignments is placed.

<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        <Consignment>
            <ConsignmentNumber>ABCD123</ConsignmentNumber>
            <PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
            <DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
        </Consignment>
    </Body>
</Message>

Each Consignment element contains several other elements which together describe a consignment in eCargo, and should be in the Body element.

The three elements shown, ConsignmentNumber, PickupDueDate, and DeliverDueDate, must always be specified and describe fundamental information for the consignment.

For the full list of available elements, please see the consignment details documentation.

Partners

A partner is a business that plays a particular role in the delivery of the consignment.

A Partner element must include its Role and Code elements. The value given for the Role element is case sensitive.

The PICKUP_FROM and DELIVER_TO partners must always be included. You can add a CARRIER partner as well if required.

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        <Consignment>
            <ConsignmentNumber>ABCD123</ConsignmentNumber>
            <PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
            <DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
            <Partner>
                <Role>PICKUP_FROM</Role>
                <Code>PortA</Code>
            </Partner>
            <Partner>
                <Role>DELIVER_TO</Role>
                <Code>WarehouseB</Code>
            </Partner>
        </Consignment>
    </Body>
</Message>

For a full list of available elements and further details about consignment partners, please see the consignment partners documentation.

Now to specify what it’s actually transporting.

Consignment items

A consignment item is a group of different products which are summarised together. The products are summarized together in order to calculate rates correctly. A consignment can have more than one consignment item.

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        <Consignment>
            <ConsignmentNumber>ABCD123</ConsignmentNumber>
            <PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
            <DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
            <Partner>
                <Role>PICKUP_FROM</Role>
                <Code>PortA</Code>
            </Partner>
            <Partner>
                <Role>DELIVER_TO</Role>
                <Code>WarehouseB</Code>
            </Partner>
            <Items>
                <Item>
                    <Description>TEU</Description>
                    <Measure Type="WEIGHT">
                        <Value>20</Value>
                        <Unit>kg</Unit>
                    </Measure>
                    <Measure Type="VOLUME">
                        <Value>4</Value>
                        <Unit>m3</Unit>
                    </Measure>
                    <Measure>
                        <Value>40</Value>
                        <Unit>Pallets</Unit>
                    </Measure>
                </Item>
            </Items>
        </Consignment>
    </Body>
</Message>

A consignment item is represented by the Item element. Each item should always consist of a Description and at least one Measure element. You can of course also specify more than one Measure element. Each Measure element must in turn contain a Value and Unit field. There are two special cases, when the measure is Volume or Weight, then the Type attribute on the Measure element must be set. You can safely ignore this attribute otherwise.

All of the Item elements should be encapsulated by an Items element, regardless of how many there are.

For a more detailed explanation on consignment items, please see the consignment items documentation.

Order line items

An order line item is typically a single product or SKU. Each consignment can have zero or more order line items.

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        <Consignment>
            <ConsignmentNumber>ABCD123</ConsignmentNumber>
            <PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
            <DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
            <Partner>
                <Role>PICKUP_FROM</Role>
                <Code>PortA</Code>
            </Partner>
            <Partner>
                <Role>DELIVER_TO</Role>
                <Code>WarehouseB</Code>
            </Partner>
            <OrderItems>
                <OrderItem>
                    <Code>ABC123</Code>
                    <Description>Delicious Soup</Description>
                    <Measure Type="WEIGHT">
                        <Value>64.0000</Value>
                        <Unit>kg</Unit>
                    </Measure>
                    <Measure Type="VOLUME">
                        <Value>0.2050</Value>
                        <Unit>m3</Unit>
                    </Measure>
                    <Measure>
                        <Value>32.0000</Value>
                        <Unit>cartons</Unit>
                    </Measure>
                </OrderItem>
            </OrderItems>
        </Consignment>
    </Body>
</Message>

An order line item is represented by the OrderItem element. Each order line should always consist of a Code, a Description, and one or more Measure elements.

Each Measure element must in turn contain a Value and Unit field.

There are two special cases: when the measure is volume or weight, then the Type attribute on the Measure element must be set. You can safely ignore this attribute otherwise.

Weight measures must use kg and volume measures must use m3 as the unit.

All of the OrderItem elements must be encapsulated by an OrderItems element - regardless of how many OrderItem elements there are.

For a more detailed explanation on order line items, please see the order line items documentation.

Shipping containers

A container is intended to represent a physical shipping container that is transported as a part of the consignment.

In order to specify Container elements, the transportation mode must be set to Shipping. You must specify the container number and type for each Container. A Container like consignment items, must also be encapsulated in a Containers element, regardless of how many there are.

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
    </Header>
    <Body>
        <Consignment>
            <ConsignmentNumber>ABCD123</ConsignmentNumber>
            <PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
            <DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
            <TransportationMode>Shipping</TransportationMode>
            <Partner>
                <Role>PICKUP_FROM</Role>
                <Code>PortA</Code>
            </Partner>
            <Partner>
                <Role>DELIVER_TO</Role>
                <Code>WarehouseB</Code>
            </Partner>
            <Items>
                <Item>
                    <Description>TEU</Description>
                    <Measure Type="WEIGHT">
                        <Value>75000.00</Value>
                        <Unit>kg</Unit>
                    </Measure>
                    <Measure Type="VOLUME">
                        <Value>120</Value>
                        <Unit>m3</Unit>
                    </Measure>
                    <Measure>
                        <Value>3</Value>
                        <Unit>cntnrs</Unit>
                    </Measure>
                </Item>
            </Items>
            <Containers>
                <Container>
                    <ContainerNumber>MTSU0000113</ContainerNumber>
                    <Type>22G1</Type>
                </Container>
                <Container>
                    <ContainerNumber>MTSU0000114</ContainerNumber>
                    <Type>22G1</Type>
                </Container>
            </Containers>
        </Consignment>
    </Body>
</Message>

For a detailed explanation on containers, please see the containers documentation.

Sending the XML document

Now that you have an XML document, the only thing left to do is send it to eCargo. There are currently two ways to do that.

Drop the XML file into the FTPS folder using credentials and location provided by eCargo.
Send an HTTP POST request to a target endpoint with the XML as content.

If you take the latter option, note that there is a Test environment for your use. It is advisable to use the Test environment initially for your development. Once you are satisfied with your functionality, then it should progress to the live Production environment.

The endpoints are:

Environment	HTTP POST endpoint
Production	`https://www.ecargo.co.nz/interface/consignment`
Test	`https://test.ecargo.co.nz/interface/consignment`

Errors

When you send a consignment document to the API the consignment is always processed offline. When sending the consignment document via HTTP you may receive a HTTP response code such as a 200 which indicates that your document has been succesfully received for processing. It does not indicate that the consignment document has been successfully processed.

If errors do occur while processing the consignment you will be notified via email. The error message will be sent to any email addresses that you have already nominated to receive them.

Before you use the API eCargo support will ask you to nominate one or more email addresses that will receive error notifications from the API. Ensure that you are able to access the email addresses that you have nominated.

Documentation

Message header

The header section contains a combination of mandatory authentication information and optional diagnostic information.

Field	Required	Description
SenderID	Yes	Required for authentication (see below)
APIKey	Yes	Required for authentication (see below)
MessageType	Yes	Always has value `consignment`
Timestamp	No	A datetime in the format `yyyy-mm-ddThh:nn:ss`, see datetime
MessageID	No	A unique identifier

Authentication details

SenderID and APIKey must contain valid credentials for any processing to occur. eCargo will provide these values prior to you using the API.

Optional diagnostic fields

We strongly encourage you to add a field such as a timestamp or unique message identifier to assist in diagnosing issues when dealing with eCargo support.

Example

<?xml version="1.0" encoding="utf-8"?>
<Message>
    <Header>
        <SenderID>MyCompany</SenderID>
        <APIKey>MyApiKey</APIKey>
        <MessageType>CONSIGNMENT</MessageType>
        <TimeStamp>2017-03-17T09:30:08</TimeStamp>
        <MessageID>3668755826</MessageID>
    </Header>
    ...
</Message>

Consignment details

Field	Required	Format	Description
ConsignmentNumber	Yes	Free text (20)	Customer consignment identifier 1
PickupDueDate	Yes	Datetime	When the consignment is due to be picked up from the pickup point in the format `yyyy-MM-ddTHH:mm:ss`
DeliverDueDate	Yes	Datetime	When the consignment is due to be delivered to the delivery point in the format `yyyy-MM-ddTHH:mm:ss`
SalesOrderNo	No	Free text (50)	Customer sales order number 2
PurchaseOrderNo	No	Free text (50)	Customer purchase order number 2
BookingReferenceNo	No	Free text (1000)	Booking reference number 3
Protection	No	Protection type	Temperature requirements for the goods to be moved
HazardClass	No	Hazard class	Identifies which ERMA hazardous goods classification the consignment belongs to
HazardUNNo	No	Number (4)	If the consignment contains hazardous goods, use the correct 4 digit UN number for hazardous materials
Comments	No	Free text (500)	Relevant comments against the job
IsPriority	No	Priority flag	Flags the consignment as a priority job, by default the consignment is not prioritised
TransportationMode	No	Transportation mode	Identifies the mechanism to be used to transport the consignment, the default is Road
Instructions	No	Free text (500)	Instructions as passed from an ERP source

All consignment details can be updated before the consignment is dispatched.

Purchase and sales order number

The value will be adjusted down to the maximum length if it is greater than the maximum length.
If only the letter casing of the value has been changed, the value will not be updated.
If no value is provided or just blank spaces are provided, the existing value is not modified.

Booking reference number

The value will be adjusted down to the maximum length if it is greater than the maximum length.
If there has been merely a change in the letter casing, the value will still be updated.
If no value is provided or just blank spaces are provided, the existing value is not modified.

Consignment number prefixes

Customisation is available for consignment number prefixes. This means that the user of the API does not need to know about the prefix in order to create a consignment. Be aware, this also means the consignment number supplied will not always be the one that is persisted to the eCargo system. The prefix itself cannot be altered by the create consignment API. If you wish to create or change a prefix, please contact eCargo support.

Examples:

Consignment Number	Pre-defined Prefix	Consignment Number in eCargo
‘1234’	‘PREFIX’	‘PREFIX1234’
‘1234’	-None-	‘1234’

Auto-lead times

A business can define auto-lead time rules in eCargo that will automatically adjust the deliver-to due date based on the consignment’s:

pickup-from
deliver-to
pickup-from due date.

If a matching auto-lead time rule is found for a consignment then the deliver-to due date specified in the consignment message is replaced by the value calculated using the rule.

For information about auto-lead time rules see this article.

Hazard class

The supported hazard class values are:

Value	Description
1	Explosive
1.1	Explosive (Mass)
1.2	Explosive (Projectile)
2	Gas
2.1	Gas (Flammable)
2.2	Gas
2.3	Gas (Toxic)
3	Liquid (Flammable)
4	Solid (Flammable)
5	Oxidizing
6	Toxic
7	Radioactive
8	Corrosive
9	Dangerous

Priority flag

The supported priority flag values are:

Value	Description
Y	Consignment to be flagged as a priority
N	Removes the priority off a prioritised consignment

If the priority is specified for a new consignment the consignment will be flagged as a priority otherwise it will default to unprioritised.

When a consignment is flagged as a priority

The consignment is highlighted in eCargo with a priority icon.
The consignment is added to the priority category in the consignment summary screen.

When the consignment priority is modified

If the IsPriority value is Y and the consignment is not currently a priority it will be flagged as a priority.
If the IsPriority value is N and the consignment is currently a priority then the consignment is no longer flagged as a priority.

Priority notification

A business can opt in to receive an alert via eCargo when the priority on the consignment has been added or removed.

Protection type

The supported protection types are:

Value	Description
Ambient	Freight is transported without temperature regulation
Chilled	Freight is transported chilled
Frozen	Freight is transported frozen
Produce	Freight is transported at produce optimal temperature

These values are not case-sensitive.

Transportation mode

The supported transportation modes are:

Value	Description
Road	Consignment is delivered by road
Rail	Consignment is delivered by rail
Shipping	Consignment is delivered by ship

These values are not case-sensitive.

If the transportation mode is not specified for a new consignment it will default to Road.

Example

...
<Body>
    <Consignment>
        <ConsignmentNumber>12345</ConsignmentNumber>
        <SalesOrderNo>Sales000001</SalesOrderNo>
        <PurchaseOrderNo>Purchase001</PurchaseOrderNo>
        <BookingReferenceNo>BookingReference001</BookingReferenceNo>
        <Protection>Ambient</Protection>
        <HazardClass>1.2</HazardClass>
        <HazardUNNo>0398</HazardUNNo>
        <Comments>13/10. Not booked on earlier vessel as due into despatch.</Comments>
        <IsPriority>Y</IsPriority>
        <TransportationMode>Road</TransportationMode>
        <Instructions>Careful handling required, dangerous goods.</Instructions>
        <PickupDueDate>2017-09-19T05:30:00</PickupDueDate>
        <DeliverDueDate>2017-09-23T16:15:00</DeliverDueDate>
        ...
    </Consignment>
</Body>

Consignment partners

A partner is a business that plays a particular role in the delivery of the consignment.

Each individual partner is represented in a partner element.

<Partner>
    <Role></Role>
    <Code></Code>
</Partner>

Field	Required	Format	Description
Role	Yes	Role	The role that the partner plays in the delivery of the document
Code	Yes	Code	A unique value used to identify a partner

Notes

When specifying either the pickup-from and deliver-to partner the business name and address will automatically default to what is in eCargo.

To view these details in eCargo see maintaining business details.

To assign a different business name from what is stored in eCargo see specifying a different name for the pickup-from or deliver-to business.
To assign a different address from what is stored in eCargo see specifying a pickup-from or deliver-to address.

Role

The supported Role values are:

Value	Required
PICKUP_FROM	Yes
DELIVER_TO	Yes
OWNER	Only required if you are creating consignments on behalf of another business that owns the goods
CARRIER	No

Please note that the values for Role are case sensitive For further details see the sections on how to specify the various partners.

Code

The Code is a unique value used to identify a partner.

Please contact eCargo to discuss where you can source these codes from.

Changing consignment partners

To change a partner submit a document with the updated partner. The new partner will replace the previous value with the same role.

You may not change partners once the consignment has been dispatched in eCargo. Partners can still be adjusted manually after the consignment has been dispatched.

Specify a pickup-from or deliver-to partner that exists in eCargo

The site that the consignment is to be picked up from or delivered to. The address details will default to the address details stored in eCargo for that business. See maintaining business details.

<Partner>
    <Role>DELIVER_TO</Role>
    <Code>2399</Code>
</Partner>

To supply an address that is different from what is held in eCargo see specifying a pickup-from or deliver-to address.

To specify a different business name see specifying a different name for the pickup-from or deliver-to business.

Specify a pickup-from or deliver-to partner that does not exist in eCargo

To specify a business to pick up from or deliver to that does not exist in eCargo:

Assign a new partner Code that is not being used.
Assign a business Name.
Assign their address details.

Note that the address details that are specified when the new partner is created will become the default in eCargo. You cannot update the default address details via the API. You can still override the default address details for a consignment, see specifying a pickup-from or deliver-to address.

Example

The business New Horizon Limited does not exist in eCargo. To associate a code that references this new business submit a new code that is not already being used along with the business name and address details.

<Partner>
    <Role>PICKUP_FROM</Role>
    <Code>0088179469</Code>
    <Name>New Horizon Limited</Name>
    <Address1>23 Street Address</Address1>
    <Address2>Mairangi Bay</Address2>
    <City>Auckland</City>
    <PostCode>0630</PostCode>
    <Region>Auckland</Region>
</Partner>

Specifying a different name for the pickup-from or deliver-to business

If the name is not supplied for the pickup-from and deliver-to partner it will automatically default to what is held in eCargo. To change the business name that will appear on the consignment supply a value in the Name field.

Examples

Example 1. Change the pickup-from partner business name to Apollo Wholesale Limited rather than using the business name held in eCargo.

<Partner>
    <Role>PICKUP_FROM</Role>
    <Code>0083054007</Code>
    <Name>Apollo Wholesale Limited</Name>
</Partner>

Example 2. Change the deliver-to partner name to Omega International rather than using the business name held in eCargo.

<Partner>
    <Role>DELIVER_TO</Role>
    <Code>2399</Code>
    <Name>Omega International</Name>
</Partner>

Note Specifying a business name will not change the default name held in eCargo.

Specifying a pickup-from or deliver-to address

If the address details are not supplied for the pickup-from and deliver-to partner it will automatically default to what is held in eCargo. To view these details in eCargo see maintaining business details.

To specify an address that is different from the one held in eCargo the following fields are available.

Field	Format	Description
Address1	Free text (64)	Street address
Address2	Free text (64)	Suburb
City	Free text (32)	City
PostCode	Free text (16)	Postal code
Region	Free text (64)	Region

Note

When changing the address at least one of the following fields need to be populated:

Address1
Address2
City

If none of these fields are populated it will default to the address held in eCargo.

Examples

Example 1. Specify a new delivery address.

<Partner>
    <Role>DELIVER_TO</Role>
    <Code>2399</Code>
    <Address1>2 Street Address</Address1>
    <Address2>Mirimar</Address2>
    <City>Wellington</City>
    <PostCode>6022</PostCode>
    <Region>Wellington</Region>
</Partner>

Example 2. Change the pickup-from street address and leave all the other address fields blank.

<Partner>
    <Role>DELIVER_TO</Role>
    <Code>0083054007</Code>
    <Address1>2 Merry Lane</Address1>
</Partner>

Example 3. The following will default to the address held in eCargo as Address1, Address2 and City have been left blank.

<Partner>
    <Role>DELIVER_TO</Role>
    <Code>2399</Code>
    <Address1></Address1>
    <Address2></Address2>
    <City></City>
    <PostCode>6022</PostCode>
    <Region>Wellington</Region>
</Partner>

Note Specifying an address will not change the default address held in eCargo.

Specify consignment owner partner

The consignment owner partner is the business that owns the goods to be delivered. They will also be the business charged for the freight costs.

The OWNER partner is only required if the consignment is being created on behalf of another business.

If you are creating a consignment for your own business the OWNER partner is not required. The owner partner will automatically default to the business associated with the Sender ID.

Examples

In the following example the code 0083054007 is associated with the business Apollo Wholesale Limited.

Example 1. Assign the business Apollo Wholesale Limited as the owner of the goods.

<Partner>
    <Role>OWNER</Role>
    <Code>0083054007</Code>
</Partner>

Example 2. A business that is not Apollo Wholesale Limited is sending documents to create consignments on behalf of Apollo Wholesale Limited. In this case the OWNER partner is required.

<Message>
    <Header>
        <SenderID>ANOTHER_CO</SenderID>
        ...
    </Header>
    <Body>
        <Consignment>
            <Partner>
                <Role>OWNER</Role>
                <Code>0083054007</Code>
            </Partner>
            ...
        </Consignment>

Example 3. Apollo Wholesale Limited is sending documents to create consignmemts for its own business. In this case an OWNER partner is not required. The owner will automatically default to Apollo Wholesale Limited.

<Header>
    <SenderID>SENDER_0083054007</SenderID>
    ...
</Header>

Specify a carrier

The carrier is the business expected to transport the consignment. See also automatically assigning a carrier.

Example

Example 1. Assign the carrier business associated with the code 004775826

<Partner>
    <Role>CARRIER</Role>
    <Code>004775826</Code>
</Partner>

Automatically assigning a carrier

eCargo has a feature that will automatically assign a carrier to a consignment. If this feature is enabled, a CARRIER partner is not required.

To override the auto assigned carrier specify a carrier partner. See specify a carrier.

See setting up auto carriers.

Consignment items

Summary

Each consignment contains a collection of one or more consignment items.

<Items>
    <Item>
        <Description>Timber</Description>
        <Measure Type="WEIGHT">
            <Value>10845.9720</Value>
            <Unit>kg</Unit>
        </Measure>
        <Measure Type="VOLUME">
            <Value>24.3050</Value>
            <Unit>m3</Unit>
        </Measure>
    </Item>
    <Item>
        <Description>Packaging</Description>
        <Measure Type="WEIGHT">
            <Value>10845.9720</Value>
            <Unit>kg</Unit>
        </Measure>
        <Measure Type="VOLUME">
            <Value>24.3050</Value>
            <Unit>m3</Unit>
        </Measure>
    </Item>
</Items>

Consignment item

A consignment item is used for summarising product groups for the carrier and for rating, so a consignment item typically groups together different products which are summarised and rated together.

<Item>
    <Description>Palleted Goods</Description>
    <Measure Type="WEIGHT">
        <Value>10845.9720</Value>
        <Unit>kg</Unit>
    </Measure>
    <Measure Type="VOLUME">
        <Value>24.3050</Value>
        <Unit>m3</Unit>
    </Measure>
    <Measure>
        <Value></Value>
        <Unit>lifts</Unit>
    </Measure>
    <Measure>
        <Value>25.0000</Value>
        <Unit>pallets</Unit>
    </Measure>
    <Measure>
        <Value>4233.0000</Value>
        <Unit>cartons</Unit>
    </Measure>
    <Measure>
        <Value>25.0000</Value>
        <Unit>chep plts</Unit>
    </Measure>
    <Measure>
        <Value></Value>
        <Unit>loscam plts</Unit>
    </Measure>
</Item>

Field	Required	Format	Description
Description	Yes	Description	A description of the product
Measure	Yes	Measure	The metric for the consignment

Notes

You can update consignment items by specifying updated consignment items in the update document. Any previous consignment items will be removed completely and replaced by the new consignment items.

You can only update consignment items before the consignment has been dispatched in eCargo. After the consignment has been dispatched, consignment items can still be updated manually.

Description

This field is required when specifying a consignment item. The value of this field should be the same as the product description maintained in eCargo. This value is not case-sensitive. To see where it is maintained in eCargo, look here.

Products

Each consignment item groups and summarises a product for rating. The type of product is specified by the Description field. The product determines which units of measure we can specify quantities for and can also specify whether those are quantities are required or optional.

You can see a list of the products that are used by your business in eCargo, here.

Measure

Each consignment item contains one or more measures depending on the product specified in the Description field. A measure contains a decimal Value field and a Unit field which contains a unit of measure code. Some measures with particular units of measure can be set to be mandatory in eCargo, forcing you to attach them to certain consignments.

<Measure Type="WEIGHT">
    <Value>10845.9720</Value>
    <Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
    <Value>24.3050</Value>
    <Unit>m3</Unit>
</Measure>
<Measure>
    <Value>10</Value>
    <Unit>cartons</Unit>
</Measure>
<Measure>
    <Value>2</Value>
    <Unit>lifts</Unit>
</Measure>

Field	Required	Format	Description
Value	Yes	Decimal	The quantity of the associated unit, this field may be left blank
Unit	Yes	Unit	Unit of measure

Unit

Unit of measure codes are look up values specified on the target product in eCargo, see here . These values are not case-sensitive. You can find the unit of measure codes that you need to send us on the units of measure page. This API uses the Legacy APIs codes.

Weight and volume

There are two special measures WEIGHT and VOLUME which must be specified with the Type attribute. The values are case sensitive. Other measures do not require this attribute. The weight and volume columns are shown separately from other units of measure when viewing the product.

<Measure Type="WEIGHT">
    <Value>10845.9720</Value>
    <Unit>kg</Unit>
</Measure>

Order line item

Summary

Each consignment contains a collection of zero or more order line item items. Each order line item is typically a single product or SKU.

<OrderItems>
    <OrderItem>
        <Code>ABC123</Code>
        <Description>Delicious Soup</Description>
        <Measure Type="WEIGHT">
            <Value>64.0000</Value>
            <Unit>kg</Unit>
        </Measure>
        <Measure Type="VOLUME">
            <Value>0.2050</Value>
            <Unit>m3</Unit>
        </Measure>
        <Measure>
            <Value>32.0000</Value>
            <Unit>cartons</Unit>
        </Measure>
    </OrderItem>
</OrderItems>

Field	Required	Format	Description
Code	Yes	Code	A code/SKU for the item. Maximum length of 200 characters.
Description	Yes	Description	A description of the item. Maximum length of 64 characters.
Measure	Yes	Measure	The measures for the item

Code

This field is required when specifying an order line item.

Description

This field is required when specifying an order line item.

Measure

Each order line item can contain zero or more measures. A measure contains a decimal Value field and a Unit field which contains a unit of measure code.

<Measure Type="WEIGHT">
    <Value>64.0000</Value>
    <Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
    <Value>0.2050</Value>
    <Unit>m3</Unit>
</Measure>
<Measure>
    <Value>32.0000</Value>
    <Unit>cartons</Unit>
</Measure>

Field	Required	Format	Description
Value	Yes	Decimal	The quantity of the associated unit. This field may be left blank
Unit	Yes	Unit	Unit of measure

Unit

Unit of measure codes are look up 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 Legacy APIs codes.

Weight and volume

<Measure Type="WEIGHT">
    <Value>64.0000</Value>
    <Unit>kg</Unit>
</Measure>

Containers

The <Containers> section contains a collection of shipping containers and their details.

<Containers>
    <Container>
        <ContainerNumber>TCNU8840179</ContainerNumber>
        <Type>42G1</Type>
    </Container>
</Containers>

Note that container information can be updated by submitting an updated XML document even when the consignment has been dispatched or delivered.

Container

A container specifies the details for a single physical shipping container. Currently the only required fields are the ContainerNumber and the Type.

Field	Required	Format	Description
ContainerNumber	Yes	Container number	ISO 6436 container number
Type	Yes	Container type code	ISO 6436 container type

Container number

Container numbers should follow the ISO 6346 standard for container numbers.

Container numbers have a three character owner code prefix then a single character category identifier followed by a six-digit serial number and end in a single check digit. For example, TCNU8840179 is a valid container number.

Container type code

Container type codes are four character alphanumeric codes that represent the specific container type. Container type codes are case sensitive.

Container type codes in eCargo are sourced from the ISO 6346 standard for container type codes.

The container type codes below are supported by the API:

Value	Description
22G1	20 Foot General Purpose
42G1	40 Foot General Purpose
45G1	40 Foot High Cube

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

<Comments>Goods to be unloaded on site.</Comments>

Number

Number fields are text fields where only numeric characters are allowed.

Example

<HazardUNNo>1106</HazardUNNo>

Integer

Integer values are whole numbers without the decimal component.

The allowed characters for this value are the numeric characters.

Example

<Packet>25</Packet>

Decimal

Decimal values are numeric values with a total of 18 digits, the decimal part of the value can be a maximum of 4 digits which are counted towards the total number of digits.

The allowed characters for this value are the numeric characters and the . decimal separator.

Order line item values with greater precision than four decimal places will be rejected; other values with greater precision will simply be rounded to four decimal places. Order line item values greater than 92,000,000,000 will also be rejected.

Example

<Weight1>8000</Weight1>
<Weight2>700.56</Weight2>
<Weight3>24850.4045</Weight3>
<Weight4>0.8795</Weight4>

Datetime

The standard format is yyyy-MM-ddTHH:mm:ss.

Note that datetime in eCargo does not correspond to a particular timezone, please ensure that the datetime value 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
:	Literal character ‘:’, used as a separator within the time 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
T	Literal character T, used as a separator for the date and time parts
HH	The hour using a 24 hour clock from 00 through to 23
mm	The minute of the hour from 00 through to 59
ss	The second of the minute from 00 through to 59

Example

<PickupDueDate>2017-09-11T08:00:10</PickupDueDate>
<DeliverDueDate>2017-09-20T13:30:00</DeliverDueDate>