shipment
Structure of the /shipment/ node
The /shipment/ is the main part of the /event/ node. It contains one or more packages connected with the event. Each shipment contains the @id attribute with the event's internal number. Additionally, the courier of the shipment is specified in the obligatory @courier attribute, and obligatory @sequence attribute (the subsequent shipment number - “1” for the first shipment) e.g.:\ <shipment id="7220" sequence="1" courier="PL-UPS">\
or\ <shipment id="2345" sequence="2" courier="DE-DHL">\
For a comprehensive list of couriers visit the Attachments section at the end of this document.
Each /shipment/ in the file is divided into several nodes:
1. **/tracking\_number/** (obligatory)\
The shipment tracking number will be assigned by the courier and returned in the ISF reply. If the customer is allowed to generate shipment tracking numbers from a range assigned by the courier, then it is possible to put the tracking number here. There are two scenarios to use both the shipment and the package tracking number:
1. If the courier uses only package tracking numbers, the number for a particular package will be written into both /shipment/tracking\_number/ and /shipment/package/tracking\_number/.
2. If the courier uses both shipment and package tracking numbers, the numbers for particular packages will be written into /shipment/package/tracking\_number/ and the number for the shipment will be written into /shipment/tracking\_number/.
2. **/tracking\_url/** (obligatory)\
The /tracking\_url/ node holds the direct URL for tracking purposes. Usually it is returned in the ISF reply. However, if the user generates tracking numbers from a predefined range and knows the link structure for a particular courier then a link may be included in the ISF request (and returned automatically without changes).
3. **/package/** (obligatory)\
The node /package/ contains the detailed package description and its tracking number. Multiple packages are possible for each shipment included as separate /package/ nodes within the /shipment/ node. Each /package/ node requires the @sequence attribute with the subsequent number of the package (“1” for the first one). There are two nodes within the /package/ node:
1. **/tracking\_number/** (obligatory) for the unique package tracking number
2. **/description/** (obligatory) for the package parameters:
1. **/packaging/** (obligatory) - defines the shape and material of the packaging.\
Possible values are:\
• "bag" (made of plastic),\
• "envelope" (made of paper),\
• "box" (made of cardboard),\
• "tube" (made of plastic or cardboard),\
• "pallet" (made of wood or plastic),\
• "other" (packaging of any irregular or non-standard type)
2. **/weight/** (obligatory) for the package weight (including the @unit attribute)
3. **/dimensions/** (optional) for the package dimensions (including the @unit attribute):\
• /length/\
• /width/\
• /height/
4. **/content\_description/** (optional) for couriers who require a detailed description of the package contents
5. **/reference/** (optional) for reference or references held in this node, which will be divided/separated according to the requirements of specific couriers by the courier or broker. /Reference/ node may occur many times.
4. **/label/** (optional)\
This node is designed for labels associated with the shipment. Multiple instances of this node are allowed. The following nodes contain details about the label expected in the XML reply. If nothing is defined, a standard A4 PDF is assumed. The label itself will be returned within the /base64/ node, encoded to BASE64. The following nodes may be used to define the expected label:
1. /type/ (optional) - a “standard” or “thermal” label might be chosen
2. /format/ (optional) - the expected format of the returned label, possible values are:PDF,
1. A6P,
2. DPL,
3. EPL,
4. ZPL.
3. /size/ (optional) - the size of the expected label may be described using the following value types:
1. standard sizes (e.g. A4),
2. dimensions (with /height/ and /width/) in units defined in /size\@unit (e.g. mm),
4. resolution using units defined in /size\@unit (e.g. Dpi),
5. /labels\_per\_page/ (optional) - number of labels included on the returned page,
6. /base64/ (obligatory) - placeholder for the label returned in the XML reply.
5. **/service/** (obligatory)\
This node describes how the package should be delivered. It contains the customer's decisions about priority and time to enable mapping to the couriers specific products in the following nodes:
1. /priority/ (obligatory) - defines the service type to be chosen from the couriers products: “same day”, “express”, “standard”,
2. /time\_definite/ (optional) - defines the latest time of day for the delivery as guaranteed by the courier. If no time is specified - until the end of day is assumed. A particular time should be given in 4 digits, in the 24-hour format (e.g. 0900, 1030, 1200, 1500). The XML reply may contain the time specific for the courier in this node.
3. /time\_range/ (optional) - defines the preferred delivery time or range, as chosen by the customer. It's not mandatory for the courier and/or it may require additional fees for the customer.
4. /shipment\_date/ (optional) - defines if the package should be sent on a specific date (in the future). If it is sent empty, the XML reply may contain the actual shipment date.
6. **/additional\_services/** (optional)\
This node contains choices about most common services that can be added to the shipment (all nodes are optional):
1. /insurance/ - If the package is to be insured, this node must be present. If the courier accepts or requires the value for insurance purposes it will be given in the node together with the @currency in the ISO 4217 format.
2. /value/ - defines the value of the package (together with the @currency in the ISO 4217 format) to meet courier requirements,
3. /nonstandard/ - contains the value "yes" if the package is not possible to be sorted automatically or has got unusual shape or elements.
4. /fragile/ - enables to send packages that need careful handling because of contents that get broken easily.
5. /bring\_up/ - contains the value "yes" for heavy or big packages that need to be brought into higher floors.
6. /carbon\_neutral/ - contains the value "yes" when the customer wants to neutralise the influence of the package on the climate.
7. /dutiable/ - contains information required for international shipments. The value of the shipment is given in the /customs\_value/ node together with the @currency in the ISO 4217 format.
7. **/pickup/** (optional)\
This node contains details of services connected with the pickup of the shipment (all nodes are optional)
1. /cod/ - contains details about the service cash on delivery (the payment for the ordered good occurs at the moment of delivery or later) with the following subnodes:
1. /amount/ - contains the amount of money due together with the @currency in the ISO 4217 format.
2. /reference/ - contains the reference to be included with the transfer of the money
3. /account\_type/ - enables to choose between a traditional wire transfer (“transfer”) or a Paypal payment (“paypal”)
4. /paypal\_account\_id/ - paypal id for Paypal
5. /transfer\_account\_id/ - bank account number for the wire transfer
6. /priority/ - describes how quickly the customer wants to get his money back. Possible values are “standard”, “express” and “fastest”.
2. /rod/ - contains details about the return on delivery service (also knows as return of documents) with the following nodes:
1. /reference/ - the reference for the ROD shipment
2. /receiver\_id/ - user ID of the receiver in the courier system
3. /tracking\_number/ - The ROD tracking number will be assigned by the courier after delivery - it will not be returned in the XML reply. However, when the customer is able to generate tracking numbers from a range assigned by the courier, then it is possible to put the tracking number here.
3. /confirmation/ - defines the kind of confirmation that is required. Possible values are:
1. no\_signature (no signature of the customer will be obtained),signature (a signature of any person will be obtained),
2. personal (a personal signature of the recipient will be obtained),
3. adult (a signature of an adult will be obtained),
4. telephone (a courier representative will confirm the delivery over the phone).
4. /self\_pickup/ - defines whether the customer in picks the package up from the courier warehouse or courier pickup point network/ courier pickup point (with “yes” or “no” as possible values)
8. **/cost/** (obligatory)\
This node defines the cost of the shipment that the shop owner pays to the courier (together with the @currency in the ISO 4217 format) with the following nodes:
1. /net/ - net value (in case of no refund, 0.00 value may be used)
2. /vat\_percent/ - VAT rate as percentage (equals 0 for both the 0% and the exempt rate)
3. /gross/ - gross value (in case of no refund, 0.00 value may be used)
9. **/dispatch\_point/** (optional)\
This node defines the place where the shipment is dispatched. Indication of the dispatch point may be required by some carriers, such as Poczta Polska (all nodes are optional):
1. /id/ - dispatch point ID
2. /name/ - dispatch point name
3. /address/ - includes the dispatch point address data, including the following nodes:
1. /postcode/ - the postal code
2. /city/ - the name of the city
3. /country/ - the name of the country in the ISO 3166-1 alpha-2 format (e.g. PL, US, DE)
**Example code for one one-package shipment**
```Text xml
<shipment id="7220" sequence="1" courier="PL-UPS">
<tracking_number>tn000324551</tracking_number>
<tracking_url>https://tracking-service.com/package/tn000324551</tracking_url>
<package sequence="1">
<tracking_number>tn000324551</tracking_number>
<description>
<weight unit="g">15000</weight>
<reference>ref 1</reference>
<reference>ref 2</reference>
<reference>ref 3</reference>
<packaging>box</packaging>
<dimensions unit="cm">
<height>30</height>
<width>30</width>
<length>120</length>
</dimensions>
<content_description>Gift. Order no.31642</content_description>
</description>
</package>
<label>
<type>standard</type>
<base64>base64</base64>
</label>
<service>
<priority>standard</priority>
</service>
<cost currency="PLN">
<net>10.00</net>
<vat_percent>23</vat_percent>
<gross>12.30</gross>
</cost>
</shipment>
```Updated 5 months ago
Did this page help you?