Create ShipmentAPI Documentation
The shipment sevice is used to prepare each shipment / parcel. It's typically called first from software in the customer terminal, as part of a daily job. Send the shipment addressess (sender / consingnee) and parcel details for customs. The service returns a shipping label, cost estimate and tracking number.
Request Message
shipment
Represents a single shipment
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| service | Specify the level of service for shipment | Text (50) | IN | |
| test | Specify 1 to indicate that this is a test shipment | boolean | Optional | 1 |
| reference | Customer reference code that uniquely idenfies this shipment. The value will be included in the shipping label and invoice data. Duplicate reference values will trigger an error. | Text (30) | 123-12345 | |
| costcentre | Additional billing reference for charge-backs | Text (50) | Optional | Project 123 |
| manifestnbr | A customer generated manifest number, used to group shipments together | Text (20) | Optional | 20210617-065628 |
| currency | Currency for shipment, item, and insured value. Use 3 character ISO 4217 Currency Code (ie USD, CAD, AUD, GBP, EUR) | Text (3) | CAD | |
| value | Total value of all items, in the specified currency | Decimal (2) | 10.99 | |
| weightunit | Unit of measure (LB or KG) | Text (2) | KG | |
| weight | Total weight of the shipment, in the specified weight units | Decimal (4) | 1.123 | |
| dimensionunit | Dimension Unit (IN = inches, CM = Centimeters) Defaults to CM if not specified | Text (2) | Optional | CM |
| labelformat | File format of the returned label. Valid values include ZPL or PDF. ZPL is used by default, if not specified. | Text (3) | Optional | |
| tradeterms | Indicates duty payment terms. Valid values include DDU (Delivery Duty Unpaid) or DDP (Delivery Duty Paid) | Text (3) | DDU | |
| exportype | Type of export, suggested values include "Permanent", "Temporary", "Return" | Text () |
shipper
Shipper Address
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| name | name of consignee, or company | Text (40) | ABC Company | |
| attention | 2nd, optional name / title / care of | Text (40) | Optional | Robert Dobolina |
| addr1 | Address line 1 | Text (40) | 123 Main Street | |
| addr2 | Address line 2 | Text (40) | Optional | Apartment 123 |
| addr3 | Address line 3 | Text (40) | Optional | |
| city | City | Text (40) | New York | |
| state | State / Province. Use standard postal abbreviations. Required for AU, US | Text (40) | Optional | NY |
| country | ISO 3166 Alpha 2 letter country code | Text (2) | US | |
| postal | Postal Code | Text (12) | 00123 | |
| phone | Local phone number | Text (20) | Optional | 212 788 1400 |
| email address, used for follow-up communication | Text (50) | Optional | support@deliverynet.ca |
consignee
Consignee Address
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| name | name of consignee, or company | Text (40) | ABC Company | |
| attention | 2nd, optional name / title / care of | Text (40) | Optional | Robert Dobolina |
| addr1 | Address line 1 | Text (40) | 123 Main Street | |
| addr2 | Address line 2 | Text (40) | Optional | Apartment 123 |
| addr3 | Address line 3 | Text (40) | Optional | |
| city | City | Text (40) | New York | |
| state | State / Province. Use standard postal abbreviations. Required for AU, US | Text (40) | Optional | NY |
| country | ISO 3166 Alpha 2 letter country code | Text (2) | US | |
| postal | Postal Code | Text (12) | 00123 | |
| phone | Local phone number | Text (20) | Optional | 212 788 1400 |
| email address, used for follow-up communication | Text (50) | Optional | support@deliverynet.ca |
item
Include 1 item objest for each item in the shipment.
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| item-code | Account Item identifier / SKU | Text (30) | Optional | SKU-123 |
| description | Description of the item | Text (80) | iPad Case | |
| qty | Quantity. The number of items, must be at least 1 | int | 5 | |
| unit | Type of item (box, pc, carton) | Text (25) | Optional | pc |
| value | Total value for all units (not the price of a single unit). If each unit costs 2.00, and quantiy=5, then indicate 10.00. Value must be in the same currency specified in the shipment | Decimal (2) | 10.00 | |
| hscode | Harmonized system code | Text (6) | HS123 | |
| origin | Country of origin. Specify the ISO 3166-1 Alpha 2 Letter code for the country of origin | Text (2) | Optional | CN |
| export-reason | Identifies why the item is being exported (Sale, Gift, etc.) | Text (15) | Optional | Sale |
package
Include 1 package object for each package in a shipment.
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| reference | Package descriptor, or bar-code value affixed to the actual package. | Text (50) | ||
| weight | Physical Weight, in the weight units specified | Decimal (3) | 0.258 | |
| length | Physical Length in the dimension units specified | Decimal (2) | 25.0 | |
| width | Physical Width, in the dimension units specified | Decimal (2) | 10.0 | |
| height | Physical Height, in the dimension units specified | Decimal (2) | 2.5 |
Sample request, with return to shipper indicated. Don't specify a return address in this case. createshipment_noreturn.json
{
"shipment": {
"service": "priority",
"test": true,
"account": "ABC",
"datetime": "2019-06-18T13:04:53.295Z",
"manifestnbr": "20210628-0228",
"reference": "123-12345",
"value": 10.00,
"currency": "USD",
"uom": "kg",
"weight": 0.82,
"originterminal": "YYZ",
"shipper": {
"name": "ABC Company",
"attention": "Samuel Shipper",
"addr1": "123 Main Street",
"addr2": "Apartment 123",
"city": "New York",
"state": "NY",
"country": "US",
"postal": "3195",
"phone": "212 234 1400",
"email": "support@openparcelgroup.com"
},
"consignee": {
"name": "Eiffel Tower",
"attention": "Connie Consignee",
"addr1": "Champ de Mars",
"addr2": "5 Avenue Anatole",
"city": "Paris",
"state": "",
"country": "FR",
"postal": "75007",
"phone": "212 234 1400",
"email": "support@openparcelgroup.com"
},
"item": [
{
"description": "iPad",
"qty": 5,
"unit": "pc",
"value": 10.00,
"origin": "CN"
}
]
}
}
Sample request, with return to shipper indicated. Don't specify a return address in this case. createshipment_noreturn.xml
<xml>
<shipment service="priority" test="1" account="ABC" datetime="2019-06-18T13:04:53.295Z" reference="123-12345" value="10" currency="USD" uom="kg" weight="0.82" originterminal="YYZ">
<shipper name="ABC Company" attention="Samuel Shipper" addr1="123 Main Street" addr2="Apartment 123" city="New York" state="NY" country="US" postal="3195" phone="212 234 1400" email="support@openparcelgroup.com" />
<consignee name="Eiffel Tower" attention="Connie Consignee" addr1="Champ de Mars" addr2="5 Avenue Anatole" city="Paris" state="" country="FR" postal="75007" phone="212 234 1400" email="support@openparcelgroup.com" />
<item description="iPad" qty="5" unit="pc" value="10.00" origin="CN" />
</shipment>
</xml>XSD / Schema - shipment.xsd Download shipment.xsd
<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="xml">
<xs:complexType>
<xs:sequence>
<xs:element name="shipment" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="shipper" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:attribute name="name" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="attention">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr1" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr2">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr3">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="city" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="state">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="country" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="2" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="postal" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="12" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="phone">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="email">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="consignee" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:attribute name="name" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="attention">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr1" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr2">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="addr3">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="city" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="state">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="40" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="country" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="2" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="postal" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="12" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="phone">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="email">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="item" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="item-code">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="30" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="description" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="80" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="qty" use="required" type="xs:string" />
<xs:attribute name="unit">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="25" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="value" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="hscode" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="6" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="origin">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="export-reason">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="15" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="package" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="reference" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="weight" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="3" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="length" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="width" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="height" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="service" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="test" type="xs:boolean" />
<xs:attribute name="reference" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="30" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="costcentre">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="manifestnbr">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="currency" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="3" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="value" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="weightunit" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="2" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="weight" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="4" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="dimensionunit">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="labelformat">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="3" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="tradeterms" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="3" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="exportype" use="required" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:sequence>
<xs:element name="error" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="code" use="required" type="xs:string" />
<xs:attribute name="description" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="500" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="context">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:sequence>
<xs:anyAttribute />
</xs:complexType>
</xs:element>
</xs:schema>Response Message
shipmentresponse
The shipment response is returned in response to the shipment request. Callers should first check for any error nodes before processing the response. The response contains a tracking number, cost estimate, and shipping label. Tracking is not available to all countries, tracking and trackingurl attributes will not be present if tracking is unavailable.
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| tracknbr | Tracking Number that can be used for all subsequent tracking requests. Tracking not available to all countries, and will not be present when no tracking is available. | Text (30) | Optional | 8675309 |
| labelformat | PDF or ZPL returned. ZPL is not base 64 encoded. PDF is based 64 encoded. | Text (3) | Optional | ZPL |
| label | Shipping Label in the specified label format | base64 | Base 64 File Content | |
| costestimate | Shipping cost based on data provided and current rates. | Decimal (2) | 10.23 | |
| costcurrency | Currency of cost estimate. ISO 4127 Currency Code, CAD, USD, EUR, AUD | Text (3) | CAD | |
| trackingurl | Full URL for tracking, suitable for consignee use. The tracking URL embeds the tracknbr field. Tracking not available to all countries, and will not be present when no tracking is available. | Text (100) | Optional |
error
| Name | Description | Type | Optional | Sample Value |
|---|---|---|---|---|
| code | Code value of the error | int | 100 | |
| description | Text description of the error message | Text (500) | Invalid XML | |
| context | Error context information | Text (50) | Optional | Error on line 1 |
Sample shipment response with ZPL label. createshipment_response.json
{
"shipmentresponse": {
"tracknbr": "1234567",
"label": "^XA^CF,0,0,0^PR12^MD30^PW800^POI^CI13^LH0,20\n^FO12...Value Truncated"
}
}Sample shipment response with ZPL label. createshipment_response.xml
<xml> <shipmentresponse tracknbr="1234567" label="^XA^CF,0,0,0^PR12^MD30^PW800^POI^CI13^LH0,20
^FO12...Value Truncated" /> </xml>
XSD / Schema - shipmentresponse.xsd Download shipmentresponse.xsd
<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="xml">
<xs:complexType>
<xs:sequence>
<xs:element name="shipmentresponse" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="error" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="code" use="required" type="xs:string" />
<xs:attribute name="description" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="500" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="context">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="tracknbr">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="30" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="labelformat">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="3" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="label" use="required" type="xs:string" />
<xs:attribute name="costestimate" use="required">
<xs:simpleType>
<xs:restriction base="xs:decimal">
<xs:fractionDigits value="2" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="costcurrency" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="3" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="trackingurl">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:sequence>
<xs:element name="error" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="code" use="required" type="xs:string" />
<xs:attribute name="description" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="500" />
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="context">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:sequence>
<xs:anyAttribute />
</xs:complexType>
</xs:element>
</xs:schema>