The consignment webhook automatically sends consignment related data from eCargo to your system.
It automatically sends the data based on a set of configurable rules e.g consignment has been assigned to a Carrier or consignment has been confirmed as dispatched. Contact eCargo regarding the setup of these rules.
When a carrier is removed from the consignment as the carrier then a withdrawn consignment webhook message is sent to the de-assigned carrier.
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.
When the request is posted to the subscriber’s destination endpoint, the webhook’s behaviour differs depending on the HTTP status code returned.
|Status code class||Behaviour|
|2xx success||Will complete request processsing. Marked as successfully sent in eCargo.|
|4xx client errors||Will not retry sending the request. Marked as failed to send in eCargo.|
|5xx server errors||Will retry sending the request up to a maximum of 13 attempts. Retransmissions are spaced out using a backoff algorithm. Once all attempts fail, the message is marked as failed to send in eCargo.|
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. In no way should it be used to comprehensively validate the consignment webhook 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.
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 the
Message section, which contains the major sections
<?xml version="1.0"?> <Message Version="1.0"> <Header> ... </Header> <Body> ... </Body> </Message>
The header section contains the sending and receiving party information. It also contains some diagnostic information.
|SenderID||Text||This field always has the value of
|RecipientID||Text||Code provided by eCargo to identify recipient of the message|
|Timestamp||Datetime||The date and time when this message was generated, in the format
|MessageID||Text||A unique identifier for this message|
|MessageType||Text||This field always has the value of
|MessageTypeVersion||Text||This field always has the value of
<Header> <SenderID>ECARGO</SenderID> <RecipientID>12345</RecipientID> <Timestamp>2017-11-05T07:04:08</Timestamp> <MessageID>1000000</MessageID> <MessageType>CONSIGNMENT</MessageType> <MessageTypeVersion>1.0</MessageTypeVersion> </Header>
Body section follows on from the
Header and includes one
Consignment field which contains:
- Consignment details in the form of multiple individual fields such as
Comments, see Consignment details.
- One or more
Partnerelements for each consignment partner, see Consignment partners.
Itemselement which contains
Itemelements for each consignment item, see Consignment items.
OrderItemselement which contains
OrderItemelements for each order line item, see Order items.
Chargeselement which contains
Chargeelements for each consignment charge, see Charges.
StatusChangesection which is obsolete, see Status change.
<Body> <Consignment> ... </Consignment> </Body>
|ConsignmentNumber||Text||Your consignment identifier|
|ConsignmentID||Integer||eCargo unique consignment identification number|
|ConsignmentStatus||Consignment status||Status of the consignment|
|ManifestNumber||Text||Used if the consignment is attached to a manifest|
|SalesOrderNo||Text||Your sales order number|
|PurchaseOrderNo||Text||Your purchase order number|
|Vehicle||Text||Name of the vehicle assigned to pick up the consignment|
|Protection||Protection type||Temperature requirements for the goods to be moved|
|HazardClass||Hazard class||Identifies which ERMA hazardous goods classification the consignment belongs to|
|HazardUNNo||Text||The 4 digit UN number for hazardous materials|
|Instructions||Text||Specific delivery instructions as passed from an ERP source|
|Comments||Text||Relevant comments against the job|
|IsDangerousGoods||Dangerous goods flag||Flags the consignment with dangerous goods|
|IsReturn||Return flag||Flags the consignment as a return|
|IsPriority||Priority flag||Flags the consignment as a priority job|
|PickupDueDate||Datetime||When the consignment is due to be picked up from the pickup point in the format
|DeliverDueDate||Datetime||When the consignment is due to be delivered to the delivery point in the format
|PickupActualDate||Datetime||When the consignment is actually picked up from the pickup point in the format
|DeliverActualDate||Datetime||When the consignment is actually delivered to the delivery point in the format
|BookingRef||Text||Your booking reference|
Note that some fields will still exist in the message if it is not set on the consignment. The XML element will have no content.
|OPEN||The consignment has not yet being offered to a carrier|
|OFFERED||A carrier has been assigned to the consignment|
|ASSIGNED||The carrier has allocated a pickup vehicle|
|DISPATCHED||Consignment is loaded onto the vehicle and actual pickup is confirmed|
|DELIVERED||Consignment has being physically delivered|
|WITHDRAWN||The consignment has been cancelled|
|Ambient||Freight is transported without temperature regulation|
|Chilled||Freight is transported chilled|
|Frozen||Freight is transported frozen|
Dangerous goods flag
|Y||The consignment contains dangerous goods|
|N||The consignment does not contain any dangerous goods|
|Y||The consignment is a return on an originating consignment|
|N||The consignment is not a return on an originating consignment|
|Y||Consignment has been flagged as a priority job|
|N||Consignment is not a priority job|
<Consignment> <ConsignmentNumber>12345</ConsignmentNumber> <ConsignmentID>87654</ConsignmentID> <ConsignmentStatus>ASSIGNED</ConsignmentStatus> <ManifestNumber/> <SalesOrderNo>45454</SalesOrderNo> <PurchaseOrderNo>55555</PurchaseOrderNo> <Vehicle>Truck001</Vehicle> <Protection>Chilled</Protection> <HazardClass/> <HazardUNNo/> <Instructions/> <Comments/> <IsDangerousGoods>N</IsDangerousGoods> <IsReturn>N</IsReturn> <IsPriority>N</IsPriority> <PickupDueDate>2017-11-05T00:00:00</PickupDueDate> <DeliverDueDate>2017-11-06T00:00:00</DeliverDueDate> <PickupActualDate/> <DeliverActualDate/> <BookingRef/> ... </Consignment>
A partner is a business or a resource that plays a particular role in the delivery of the consignment.
Each individual partner is represented in a partner element.
The basic partner element contains the role, a unique identifier and the business or resource name of the partner.
|Role||Partner role||The role that the partner plays in the delivery of the consignment|
|Code||Text||A unique value used to identify a partner|
|Name||Text||The partner business or resource name|
<Consignment> ... <Partner> <Role>OWNER</Role> <Code>0083054007</Code> <Name>Apollo Wholesale Limited</Name> </Partner> ... </Consignment>
The extended partner element contains address details in addition to the basic information.
This is applicable to pickup and delivery points which can be a mill or a DC, who uses eCargo to manage their inwards and outwards consignments.
<Consignment> ... <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> ... </Consignment>
Note that partner elements will only exist if the consignment contains a partner with the particular role.
|OWNER||The business that created the consignment in eCargo, normally the customer|
|PICKUP_FROM||The pickup location of the consignment|
|DELIVER_TO||The delivery location of the consignment|
|SOLD_TO||The business who ordered the products from the owner|
|CARRIER||The prime carrier assigned to transport the consignment|
|CREATED_BY||The business which created the consignment on behalf of the owner|
|SUBCONTRACTOR||The sub-contractor assigned to transport the consignment|
|LOGISTICS_PROVIDER||The business responsible for providing transportation services|
Each consignment contains a collection of one or more consignment items.
<Consignment> ... <Items> ... </Items> ... </Consignment>
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.
|Description||Text||A description of the product|
|Measure||Measure||The metric for the consignment item|
<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>
Each consignment may contain a collection of one or more order line items.
<Consignment> ... <OrderItems> ... </OrderItems> ... </Consignment>
An order item is a specific product that is delivered on the consignment.
These items describe individual products that would be summarised in a consignment item.
|OrderItemNumber||Text||Identifier for this product in your system|
|Code||Text||Code used to reference the order item e.g. SKU or material number|
|Description||Text||A description of the product|
|Measure||Measure||The metric for the order item|
|SalesOrderNumber||Text||Your sales order number|
|SalesOrderLineItemNumber||Text||The sales number of the item|
SalesOrderLineItemNumber identifies the item in the original order.
An order could consist of a large amount of items that requires multiple consignments to transport the goods to the delivery point.
These fields will be present if the value exists.
<OrderItem> <OrderItemNumber>9001</OrderItemNumber> <Code>00002125139</Code> <Description>LVL,R;HS,240X45,UT,A,3000</Description> <Measure Type="VOLUME"> <Value>32.4</Value> <Units>dm3</Units> </Measure> <Measure Type="WEIGHT"> <Value>19.764</Value> <Units>Kilogram</Units> </Measure> <Measure> <Value>1</Value> <Units>Piece</Units> </Measure> <Measure> <Value>3</Value> <Units>MaxLength</Units> </Measure> <SalesOrderNumber>45454</SalesOrderNumber> <SalesOrderLineItemNumber>0010</SalesOrderLineItemNumber> </OrderItem>
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.
|Value||Decimal||The quantity of the associated unit|
|Unit||Text||Unit of measure|
Each consignment item groups and summarises a product for rating. The type of product is specified by the
You can see a list of the products that are used by your business in eCargo, as described here.
Unit of measure codes are look up values specified on the target product in eCargo, as described here. This webhook uses the Premium codes.
Weight and volume
There are two special measures with the
Type attribute can have the value
<Measure Type="WEIGHT"> <Value>10845.9720</Value> <Unit>KG</Unit> </Measure>
The Serial Shipping Container Code is an 18 digit code which uniquely identifies a logistic unit such as a pallet.
A consignment may contain 0 or more pallets.
This information will only be present if the relevant SSCC data exists for the consignment.
<Consignment> ... <SsccCodes> <SsccCode>012345678902222281</SsccCode> <SsccCode>012345678902222282</SsccCode> <SsccCode>012345678902222283</SsccCode> </SsccCodes> ... </Consignment>
|SsccCode||Text||The 18 digit SSCC for a logistic unit e.g. pallet|
For more information on SSCC codes please refer to the following external links:
- GS1 New Zealand: https://www.gs1nz.org/standards/identify/sscc
- GS1 Global: https://www.gs1.org/standards/id-keys/sscc
Charges element contains the various charges for the associated consignment. This element always exists, even when there are no charges sent. Inside, there can be multiple
Charge elements, which define each charge for the consignment.
Charge information, when it exists, will be sent only when the recipient:
- is the carrier or owner for the consignment.
- is a logistics provider for the consignment.
<Charges> <Charge> <RateTableType>SUPPLIER</RateTableType> <ChargeCode>1046838</ChargeCode> <Supplier>Reindeer Express</Supplier> <Category>NZ_ROAD</Category> <ChargeType>C-NZ_ROAD</ChargeType> <MovementDate>2017-11-06T00:00:00</MovementDate> <FromZone>North Pole</FromZone> <ToZone>Auckland Central</ToZone> <NetValue>49.99</NetValue> <Extras> <Extra> <ExtraRate>-1.64</ExtraRate> <ExtraValue>-0.7727</ExtraValue> <ExtraName>Fuel Surcharge</ExtraName> </Extra> </Extras> <GrossValue>46.3472</GrossValue> <Currency>NZD</Currency> </Charge> </Charges>
|RateTableType||Text||The type of rate used. This field should always have the value
|ChargeCode||Text||A unique identifier for the customer/supplier used by the Logistics Provider’s accounts system.|
|Supplier||Text||The name of the service provider on the charge|
|Category||Text||The category that the charge falls under.|
|ChargeType||ChargeType||The type of charge calculation|
|MovementDate||DateTime||The date the consignment moved|
|FromZone||Text||The zone the consignment started from|
|ToZone||Text||The zone the consignment was delivered to|
|NetValue||Decimal||The base charge of the consignment|
|Extras||Extras||Any additional charges incurred|
|GrossValue||Decimal||The gross charge for the consignment, the sum of all base charges and extra charges.|
|Currency||Text||ISO 4217 currency code|
Zones are text descriptions of geographical areas that determine a route and what is charged.
FromZone is the zone that the consignment was moved from,
ToZone is the zone that the consignment was moved to. These zones are maintained by the carrier or logistics provider in eCargo. For further details, see this guide.
|C-NZ_ROAD||A charge for road freight in New Zealand|
|C-NZ_RAIL||A charge for rail freight in New Zealand|
Note: These are only the most common types, not an exhaustive list. If you receive another type, please contact eCargo support.
Extras element is a collection of additional charges that cannot be broken down to a typical charge.
|ExtraRate||Decimal||The rate of the additional charge|
|ExtraValue||Decimal||The value of what is being charged|
|ExtraName||Text||The name of the charge. This field should always have the value
Extra Rate and
Extra Value can be negative numbers.
This element exists as the final section of the
This element is obsolete. Do not use even if value is present for any or the child elements.
<Consignment> ... <StatusChange> <Action/> <Date/> <ChangedBy/> <Vehicle/> <Comments/> </StatusChange> </Consignment>
Text fields consists of alphanumeric characters and punctuation characters.
<Comments>Goods to be unloaded on site.</Comments>
Number fields are text fields which contains only numeric characters.
Integer values are whole numbers without the decimal component.
Decimal values are numeric values with a whole and optionally a decimal part separated by the
. decimal separator.
<Weight1>8000</Weight1> <Weight2>700.56</Weight2> <Weight3>24850.4045</Weight3> <Weight4>0.8795</Weight4>
The standard format is
Note that datetime in eCargo does not correspond to a particular timezone.
|-||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|