Shipping API This page provides documentation, examples and a testing framework
Overview
The API allows you to send requests and receive responses for the methods defined below.
Using the API
Use the following URL for requests:
http://api.noviship.net/v1
Your request should be sent in the body of the request (an HTTP POST verb) and can be either XML or JSON. You must use the Content-Type HTTP Header to indicate the format. Use text/xml for XML requests and application/json for JSON requsts.
Primitives
All parameters for methods and all structure properties can be either one of the three primitives or a structure defined below.
int
The int primitive represents an integer (negative or positive) and must contain only numeric characters with an optional leading minus sign. A null is represented with a zero or an empty string.
float
The float primitive represents a floating point number (IEEE double precision). A null is represented with a zero or an empty string.
string
The string primitive represents a text string encoded with UTF-8. A null is represented with an empty string. It is recommended that you use only ASCII characters as in many cases non-ASCII characters will be transliterated to their ASCII 7-bit equivilent. For example Montréal will become Montreal.
Methods
VerifyAddress
This method is used to validate the address provided and possibly identify alternatives.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| card | Card | Address to verify |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| alternatives | Card[] | If valid alternative addresses are available they will be presented here |
Examples
This example contains a valid address
Request
<VerifyAddress>
<key>YOUR-KEY-HERE</key>
<card>
<attn>JO SMITH</attn>
<country>CA</country>
<city>MONTREAL-OUEST</city>
<postalcode>H4X1L4</postalcode>
<province>QC</province>
</card>
</VerifyAddress>Response
<?xml version="1.0"?> <response><result>0</result><messages><Message><text></text><originator>courier</originator><code>0</code></Message></messages><alternatives/></response>
Request
{
"VerifyAddress": {
"key": "YOUR-KEY-HERE",
"card": {
"attn": "JO SMITH",
"country": "CA",
"city": "MONTREAL-OUEST",
"postalcode": "H4X1L4",
"province": "QC"
}
}
}Response
{"result":0,"messages":[{"text":null,"code":0,"originator":"courier"}],"alternatives":[]}This address has a city name which differs from the official name
Request
<VerifyAddress>
<key>YOUR-KEY-HERE</key>
<card>
<attn>JO SMITH</attn>
<country>CA</country>
<city>MONTREAL</city>
<postalcode>H4X1L4</postalcode>
<province>QC</province>
</card>
</VerifyAddress>Response
<?xml version="1.0"?> <response><result>-103</result><messages><Message><text>Suggested address is supplied</text><originator>courier</originator><code>-103</code></Message></messages><alternatives><Card><attn>JO SMITH</attn><street1></street1><street2></street2><street3></street3><orgname></orgname><city>MONTREAL-OUEST</city><province>QC</province><postalcode>H4X1L4</postalcode><country>CA</country><tel></tel><email></email><residential>0</residential><tax_id></tax_id><ext></ext></Card></alternatives></response>
Request
{
"VerifyAddress": {
"key": "YOUR-KEY-HERE",
"card": {
"attn": "JO SMITH",
"country": "CA",
"city": "MONTREAL",
"postalcode": "H4X1L4",
"province": "QC"
}
}
}Response
{"result":-103,"messages":[{"text":"Suggested address is supplied","code":-103,"originator":"courier"}],"alternatives":[{"attn":"JO SMITH","country":"CA","city":"MONTREAL-OUEST","postalcode":"H4X1L4","province":"QC"}]}GetQuotes
This method combines CreateShipment, QuoteShipment and DeleteShipment into a single operation, returning only the Quote structures.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| shipment | Shipment | This is the shipment data to submit for quoting |
| username | string | The user account in which the shipment should be created. This property should be left blank unless you have permission to create shipments on behalf of the named user. |
| flags | Param[] | A list of control flags that affect the quoting process
|
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| quotes | Quote[] | These are the quotes generated by the appropriate carriers and priced according to your account |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Examples
This example contains a partially valid request for a quote from Canada to the US for a light non-documents shipment. FedEx and DHL can produce quotes but CanPar cannot because the quote does not have a valid customer name in the shipper/pickup address.
Request
<GetQuotes>
<key>YOUR-KEY-HERE</key>
<shipment>
<shipper>
<attn>JOE SMITH</attn>
<country>CA</country>
<city>MONTREAL-OUEST</city>
<postalcode>H4X1L4</postalcode>
<province>QC</province>
</shipper>
<destination>
<attn>JAY SMITH</attn>
<country>US</country>
<city>Champlain</city>
<postalcode>12919</postalcode>
<province>NY</province>
</destination>
<dimensionunit>IN</dimensionunit>
<weightunit>LB</weightunit>
<shipmentdate>2015-03-06</shipmentdate>
<currency>CAD</currency>
<pkgtype>CUST</pkgtype>
<documentsonly>0</documentsonly>
<packages>
<Package>
<qty>1</qty>
<description>BOX</description>
<weight>1.0</weight>
<width>5</width>
<height>5</height>
<length>10</length>
</Package>
</packages>
</shipment>
</GetQuotes>Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>0</result>
<quotes>
<Quote>
<id />
<carrier>dhl</carrier>
<serviceid>Q</serviceid>
<baseprice>18.77</baseprice>
<breakdown>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.09</amount>
</Charge>
</breakdown>
<netprice>18.86</netprice>
<grossprice>18.86</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Medical Express</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:31</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>DHL</carriername>
</Quote>
<Quote>
<id />
<carrier>dhl</carrier>
<serviceid>P</serviceid>
<baseprice>12.26</baseprice>
<breakdown>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.06</amount>
</Charge>
</breakdown>
<netprice>12.32</netprice>
<grossprice>12.32</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Express WorldWide</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:31</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>DHL</carriername>
</Quote>
<Quote>
<id />
<carrier>dhl</carrier>
<serviceid>H</serviceid>
<baseprice>12.26</baseprice>
<breakdown>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.06</amount>
</Charge>
</breakdown>
<netprice>12.32</netprice>
<grossprice>12.32</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Economy Select</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:31</timestamp>
<deliverydate>2015-03-11</deliverydate>
<carriername>DHL</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_FIRST</serviceid>
<baseprice>158.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>2.38</amount>
</Charge>
</breakdown>
<netprice>161.08</netprice>
<grossprice>161.08</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International First</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:32</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_PRIORITY</serviceid>
<baseprice>20.19</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.3</amount>
</Charge>
</breakdown>
<netprice>20.49</netprice>
<grossprice>20.49</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Priority</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:32</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_ECONOMY</serviceid>
<baseprice>19.07</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.29</amount>
</Charge>
</breakdown>
<netprice>19.36</netprice>
<grossprice>19.36</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Economy</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:32</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>FEDEX_GROUND</serviceid>
<baseprice>15.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>extendedarea</type>
<description>Delivery Area Surcharge Commercial</description>
<amount>1.25</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.77</amount>
</Charge>
</breakdown>
<netprice>17.72</netprice>
<grossprice>17.72</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Ground</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:32</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_FIRST</serviceid>
<baseprice>158.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>2.38</amount>
</Charge>
</breakdown>
<netprice>161.08</netprice>
<grossprice>161.08</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International First</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:35</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_PRIORITY</serviceid>
<baseprice>20.19</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.3</amount>
</Charge>
</breakdown>
<netprice>20.49</netprice>
<grossprice>20.49</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Priority</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:35</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_ECONOMY</serviceid>
<baseprice>19.07</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.29</amount>
</Charge>
</breakdown>
<netprice>19.36</netprice>
<grossprice>19.36</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Economy</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:35</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>FEDEX_GROUND</serviceid>
<baseprice>15.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>extendedarea</type>
<description>Delivery Area Surcharge Commercial</description>
<amount>1.25</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.77</amount>
</Charge>
</breakdown>
<netprice>17.72</netprice>
<grossprice>17.72</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Ground</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:35</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_FIRST</serviceid>
<baseprice>158.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>2.38</amount>
</Charge>
</breakdown>
<netprice>161.08</netprice>
<grossprice>161.08</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International First</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:36</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_PRIORITY</serviceid>
<baseprice>20.19</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.3</amount>
</Charge>
</breakdown>
<netprice>20.49</netprice>
<grossprice>20.49</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Priority</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:36</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>INTERNATIONAL_ECONOMY</serviceid>
<baseprice>19.07</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.29</amount>
</Charge>
</breakdown>
<netprice>19.36</netprice>
<grossprice>19.36</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>International Economy</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:36</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>fedex</carrier>
<serviceid>FEDEX_GROUND</serviceid>
<baseprice>15.7</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>extendedarea</type>
<description>Delivery Area Surcharge Commercial</description>
<amount>1.25</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.77</amount>
</Charge>
</breakdown>
<netprice>17.72</netprice>
<grossprice>17.72</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Ground</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:36</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>07</serviceid>
<baseprice>71.25</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>71.25</netprice>
<grossprice>71.25</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Express</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>UPS</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>08</serviceid>
<baseprice>57.27</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>57.27</netprice>
<grossprice>57.27</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Worldwide Expedited&trade;</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>1969-12-31</deliverydate>
<carriername>UPS</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>54</serviceid>
<baseprice>159.83</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>159.83</netprice>
<grossprice>159.83</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Worldwide Express Plus&trade;</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>UPS</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>65</serviceid>
<baseprice>67.78</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>67.78</netprice>
<grossprice>67.78</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Saver&trade;</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>2015-03-09</deliverydate>
<carriername>UPS</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>11</serviceid>
<baseprice>24.08</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>24.08</netprice>
<grossprice>24.08</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Standard</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>1969-12-31</deliverydate>
<carriername>UPS</carriername>
</Quote>
<Quote>
<id />
<carrier>ups</carrier>
<serviceid>12</serviceid>
<baseprice>52.63</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>ServiceOptionsCharges</type>
<description>Service Option Charges</description>
<amount>0</amount>
</Charge>
</breakdown>
<netprice>52.63</netprice>
<grossprice>52.63</grossprice>
<tax1amount>0</tax1amount>
<tax2amount>0</tax2amount>
<tax1name />
<tax2name />
<servicename>Three-Day Select&reg;</servicename>
<currency>CAD</currency>
<timestamp>2015-03-06 03:34:37</timestamp>
<deliverydate>1969-12-31</deliverydate>
<carriername>UPS</carriername>
</Quote>
</quotes>
<messages>
<Message>
<text>Canpar: Pickup address: Address name required</text>
<originator>Canpar</originator>
<code>-105</code>
</Message>
<Message>
<text>Canpar: Pickup address: Address name required</text>
<originator>Canpar</originator>
<code>-105</code>
</Message>
</messages>
</response>Request
{
"GetQuotes": {
"key": "YOUR-KEY-HERE",
"shipment": {
"shipper": {
"attn": "JOE SMITH",
"country": "CA",
"city": "MONTREAL-OUEST",
"postalcode": "H4X1L4",
"province": "QC"
},
"destination": {
"attn": "JAY SMITH",
"country": "US",
"city": "Champlain",
"postalcode": "12919",
"province": "NY"
},
"dimensionunit": "IN",
"weightunit": "LB",
"shipmentdate": "2017-10-20",
"currency": "CAD",
"pkgtype": "CUST",
"documentsonly": "0",
"packages": [
{
"qty": "1",
"description": "BOX",
"weight": "1.0",
"width": "5",
"height": "5",
"length": "10"
}
]
}
}
}CreateShipment
This method creates a new shipment and returns a shipment reference. Non-modifiable properties can be set to empty strings or zeros.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| shipment | Shipment | This is the shipment data |
| username | string | The user account in which the shipment should be created. This property should be left blank unless you have permission to create shipments on behalf of the named user. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| id | string | This is a unique identifier for the newly created shipment and will be used to refer to this shipment in other method calls |
Examples
Constructing a simple shipment from Canada to the USA.
Request
<CreateShipment>
<key>YOUR-KEY-HERE</key>
<shipment>
<shipper>
<attn>Test Administrator</attn>
<street1>999 Test Street</street1>
<street2/>
<street3/>
<orgname>Test Corp</orgname>
<city>Montreal</city>
<province>QC</province>
<postalcode>H2Y2V5</postalcode>
<country>CA</country>
<tel>1234-456-7890</tel>
<email>info@example.com</email>
<residential>0</residential>
<tax_id/>
<ext/>
</shipper>
<destination>
<attn>JAY SMITH</attn>
<street1>2660 Locust Street</street1>
<street2/>
<street3/>
<orgname>JAYCO</orgname>
<city>Champlain</city>
<province>NY</province>
<postalcode>12919</postalcode>
<country>US</country>
<tel/>
<email/>
<residential>0</residential>
<tax_id/>
<ext/>
</destination>
<shipmentdate>2015-03-11</shipmentdate>
<dimensionunit>IN</dimensionunit>
<weightunit>LB</weightunit>
<currency>CAD</currency>
<tracking/>
<trackingnumber/>
<pkgtype>CUST</pkgtype>
<documentsonly>0</documentsonly>
<custrefcode>MYREFERENCECODE</custrefcode>
<options>
<Option>
<code>signature_required</code>
<params>
<Param>
<name>option</name>
<value>1</value>
</Param>
</params>
</Option>
</options>
<commodities>
<Commodity>
<marks>None</marks>
<description>Used Jacket</description>
<unitofmeasure/>
<unitprice>15.00</unitprice>
<qty>1</qty>
<hscode>0.0.0.0</hscode>
<origin>CA</origin>
<weight>4.5</weight>
</Commodity>
</commodities>
<packages>
<Package>
<id>59615</id>
<qty>1</qty>
<description>BOX</description>
<weight>5</weight>
<width>7</width>
<length>6</length>
<height>6</height>
<insvalue>0</insvalue>
</Package>
</packages>
</shipment>
</CreateShipment>Response
<?xml version="1.0"?> <response> <result>0</result> <messages/> <id>440515724</id> </response>
Request
{
"CreateShipment": {
"key": "YOUR-KEY-HERE",
"shipment": {
"shipper": {
"attn": "Test Administrator",
"street1": "999 Test Street",
"street2": "",
"street3": "",
"orgname": "Test Corp",
"city": "Montreal",
"province": "QC",
"postalcode": "H2Y2V5",
"country": "CA",
"tel": "1234-456-7890",
"email": "info@example.com",
"residential": 0,
"tax_id": "",
"ext": ""
},
"destination": {
"attn": "JAY SMITH",
"street1": "2660 Locust Street",
"street2": "",
"street3": "",
"orgname": "JAYCO",
"city": "Champlain",
"province": "NY",
"postalcode": "12919",
"country": "US",
"tel": "",
"email": "",
"residential": 0,
"tax_id": "",
"ext": ""
},
"shipmentdate": "2015-03-11",
"dimensionunit": "IN",
"weightunit": "LB",
"currency": "CAD",
"pkgtype": "CUST",
"documentsonly": "0",
"custrefcode": "MYREFERENCECODE",
"options": [
{
"code": "signature_required",
"params": [
{
"name": "option",
"value": "1"
}
]
}
],
"commodities": [
{
"marks": "None",
"description": "Used Jacket",
"unitofmeasure": "EA",
"unitprice": 1.5,
"qty": 1,
"hscode": "0.0.0.0.0",
"origin": "CA",
"weight": 4.5
}
],
"packages": [
{
"qty": "1",
"description": "BOX",
"weight": "5",
"width": "7",
"length": "6",
"height": "6",
"insvalue": "0"
}
]
}
}
}ModifyShipment
This method provides a means to modify an existing shipment. Most properties can be modified until the shipment is submitted. Non-modifiable properties are ignored. Array properties generally contain elements that have an ID property which must not be modified. The ID property is used to determine if the elements are new or should be deleted (through their absence). For new elements set the ID to zero.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
| shipment | Shipment | This is a full shipment structure containing changes. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Examples
Modification of a shipment by sending the structure returned from a previous ReadShipment request with minor changes.
Request
<ModifyShipment>
<key>YOUR-KEY-HERE</key>
<id>440507771</id>
<shipment>
<shipper>
<attn>Test Administrator</attn>
<street1>999 Test Street</street1>
<street2/>
<street3/>
<orgname>Test Corp</orgname>
<city>Montreal</city>
<province>QC</province>
<postalcode>H2Y2V5</postalcode>
<country>CA</country>
<tel>1234-456-7890</tel>
<email>info@example.com</email>
<residential>0</residential>
<tax_id/>
<ext/>
</shipper>
<destination>
<attn>JAY SMITH</attn>
<street1>2660 Locust Street</street1>
<street2/>
<street3/>
<orgname>JAYCO</orgname>
<city>Champlain</city>
<province>NY</province>
<postalcode>12919</postalcode>
<country>CA</country>
<tel/>
<email/>
<residential/>
<tax_id/>
<ext/>
</destination>
<userid>7365</userid>
<custid>7486</custid>
<creationdate>2015-03-11 12:14:33</creationdate>
<shipmentdate>2015-03-11</shipmentdate>
<statustext/>
<statuscode>0</statuscode>
<selectedquote/>
<dimensionunit>IN</dimensionunit>
<weightunit>LB</weightunit>
<currency>CAD</currency>
<pickuprefcode/>
<pickuprequired>1</pickuprequired>
<pickuprequested>0</pickuprequested>
<tracking/>
<trackingnumber/>
<pkgtype>CUST</pkgtype>
<weight>0</weight>
<documentsonly>0</documentsonly>
<reconciled>0</reconciled>
<custrefcode>440507771</custrefcode>
<options/>
<commodities/>
<customs/>
<packages>
<Package>
<id>59615</id>
<qty>1</qty>
<description>BOX</description>
<weight>5</weight>
<width>7</width>
<length>6</length>
<height>6</height>
<insvalue>0</insvalue>
<pkgtrackingid/>
</Package>
</packages>
<quotes/>
<documents/>
</shipment>
</ModifyShipment>Response
<?xml version="1.0"?> <response> <result>0</result> <messages/> </response>
DeleteShipment
This method removes a shipment prior to submission. After this call the shipment reference is invalid.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Examples
Successfully deleting a shipment in the correct state.
Request
<DeleteShipment> <key>YOUR-KEY-HERE</key> <id>440515724</id> </DeleteShipment>
Response
<?xml version="1.0"?> <response> <result>0</result> <messages/> </response>
An attempt to delete a shipment that has already been deleted results in an access error. The system does not indicate whether the shipment exists or that you do not have access to it.
Request
<DeleteShipment> <key>YOUR-KEY-HERE</key> <id>440515724</id> </DeleteShipment>
Response
<?xml version="1.0"?>
<response>
<result>-27</result>
<messages>
<Message>
<text>This shipment is not available to you</text>
<originator>system</originator>
<code>-27</code>
</Message>
</messages>
</response>ReadShipment
This method retrieves data regarding a shipment. When modifying a shipment one should modify the structure returned by this call and submit the modified structure to ModifyShipment.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
| refresh | int | Trigger a slow courier poll prior to data retrieval |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| shipment | Shipment | This structure contains all the available shipment data. It is possible to return data for shipments whether or not they were created through the API. |
Examples
Request for a valid and submitted shipment
Request
<ReadShipment> <key>YOUR-KEY-HERE</key> <id>440881023</id> </ReadShipment>
Response
<?xml version="1.0"?>
<response>
<result>0</result>
<messages/>
<shipment>
<id>440881023</id>
<shipper>
<attn>John Smith</attn>
<street1>9955 Chemin Fontarabie</street1>
<street2/>
<street3/>
<orgname>La Boutique</orgname>
<city>La Prairie</city>
<province>QC</province>
<postalcode>J5R0K3</postalcode>
<country>CA</country>
<tel>5556599868</tel>
<email/>
<residential>0</residential>
<tax_id/>
<ext/>
</shipper>
<destination>
<attn>John Doe</attn>
<street1>15 1st Avenue</street1>
<street2/>
<street3/>
<orgname/>
<city>Montreal</city>
<province>QC</province>
<postalcode>H2T1G2</postalcode>
<country>CA</country>
<tel>5554651292</tel>
<email/>
<residential>0</residential>
<tax_id/>
<ext/>
</destination>
<userid>7361</userid>
<custid>7482</custid>
<creationdate>2015-06-22 12:30:25</creationdate>
<shipmentdate>2015-06-23</shipmentdate>
<statustext/>
<statuscode>3</statuscode>
<selectedquote>281881</selectedquote>
<dimensionunit>IN</dimensionunit>
<weightunit>LB</weightunit>
<currency>CAD</currency>
<pickuprefcode/>
<pickuprequired>1</pickuprequired>
<pickuprequested>0</pickuprequested>
<tracking/>
<trackingnumber>794642310354</trackingnumber>
<pkgtype>CUST</pkgtype>
<weight>3.08</weight>
<documentsonly>0</documentsonly>
<reconciled>0</reconciled>
<custrefcode>440881023</custrefcode>
<options/>
<commodities/>
<customs/>
<packages>
<Package>
<id>108708</id>
<qty>1</qty>
<description>Box</description>
<weight>3.08</weight>
<width>3.54</width>
<length>3.54</length>
<height>5.91</height>
<insvalue>0</insvalue>
<pkgtrackingid>794642310354</pkgtrackingid>
</Package>
</packages>
<quotes>
<Quote>
<id>281881</id>
<carrier>fedex</carrier>
<serviceid>FIRST_OVERNIGHT</serviceid>
<baseprice>41.93</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>1.25</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>2.16</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>4.31</amount>
</Charge>
</breakdown>
<netprice>43.18</netprice>
<grossprice>49.65</grossprice>
<tax1amount>1.69</tax1amount>
<tax2amount>3.37</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>First Overnight</servicename>
<currency>CAD</currency>
<timestamp>2015-06-22 12:30:26</timestamp>
<deliverydate>2015-06-25</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>281882</id>
<carrier>fedex</carrier>
<serviceid>PRIORITY_OVERNIGHT</serviceid>
<baseprice>25.05</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.76</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.29</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.57</amount>
</Charge>
</breakdown>
<netprice>25.81</netprice>
<grossprice>29.67</grossprice>
<tax1amount>1.01</tax1amount>
<tax2amount>2.01</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Priority Overnight</servicename>
<currency>CAD</currency>
<timestamp>2015-06-22 12:30:26</timestamp>
<deliverydate>2015-06-25</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>281883</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_2_DAY</serviceid>
<baseprice>23.85</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.72</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.23</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.45</amount>
</Charge>
</breakdown>
<netprice>24.57</netprice>
<grossprice>28.25</grossprice>
<tax1amount>0.96</tax1amount>
<tax2amount>1.91</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>2 Day</servicename>
<currency>CAD</currency>
<timestamp>2015-06-22 12:30:26</timestamp>
<deliverydate>2015-06-25</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>281884</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_EXPRESS_SAVER</serviceid>
<baseprice>23.85</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.72</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.23</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.45</amount>
</Charge>
</breakdown>
<netprice>24.57</netprice>
<grossprice>28.25</grossprice>
<tax1amount>0.96</tax1amount>
<tax2amount>1.91</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Express Saver</servicename>
<currency>CAD</currency>
<timestamp>2015-06-22 12:30:26</timestamp>
<deliverydate>2015-06-25</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>281885</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_GROUND</serviceid>
<baseprice>9.15</baseprice>
<breakdown>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.37</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>0.48</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>0.95</amount>
</Charge>
</breakdown>
<netprice>9.52</netprice>
<grossprice>10.95</grossprice>
<tax1amount>0.48</tax1amount>
<tax2amount>0.95</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Ground</servicename>
<currency>CAD</currency>
<timestamp>2015-06-22 12:30:26</timestamp>
<deliverydate>2015-06-24</deliverydate>
<carriername>FedEx</carriername>
</Quote>
</quotes>
<documents>
<Document>
<id>28984</id>
<type>1</type>
<packageid>108708</packageid>
<mimetype>application/pdf</mimetype>
<formid/>
<url>https://noviship-documents.s3.amazonaws.com/78b3412ae4356d7d4a0b819300b3a27d15cf7de0</url>
</Document>
</documents>
</shipment>
</response>Request for a valid shipment prior to submission
Request
<ReadShipment> <key>YOUR-KEY-HERE</key> <id>440504119</id> </ReadShipment>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>0</result>
<messages />
<shipment>
<id>440504119</id>
<shipper>
<attn>Test Administrator</attn>
<street1>999 Saint-Suplice</street1>
<street2 />
<street3 />
<orgname>TEST</orgname>
<city>Montreal</city>
<province>QC</province>
<postalcode>H2Y2V5</postalcode>
<country>CA</country>
<tel>514-123-4567</tel>
<email>info@example.com</email>
<residential>0</residential>
<tax_id />
<ext />
</shipper>
<destination>
<attn>TEST</attn>
<street1>1 MAIN STREET</street1>
<street2 />
<street3 />
<orgname>TEST COMPANY</orgname>
<city>MONTREAL-OUEST</city>
<province>QC</province>
<postalcode>H4X1L4</postalcode>
<country>CA</country>
<tel>514-123-4567</tel>
<email />
<residential />
<tax_id />
<ext />
</destination>
<userid>7365</userid>
<custid>7486</custid>
<creationdate />
<shipmentdate>2015-03-09</shipmentdate>
<statustext />
<statuscode>2</statuscode>
<selectedquote />
<dimensionunit>IN</dimensionunit>
<weightunit>LB</weightunit>
<currency>CAD</currency>
<pickuprefcode />
<pickuprequired>1</pickuprequired>
<pickuprequested>0</pickuprequested>
<tracking />
<trackingnumber />
<pkgtype>CUST</pkgtype>
<weight>5</weight>
<documentsonly>0</documentsonly>
<reconciled />
<custrefcode>440504119</custrefcode>
<options />
<commodities>
<Commodity>
<id>13994</id>
<marks />
<description />
<unitofmeasure />
<unitprice />
<qty />
<hscode />
<origin />
<weight />
<ext />
</Commodity>
</commodities>
<customs />
<packages>
<Package>
<id />
<qty>1</qty>
<description>BOX</description>
<weight>5</weight>
<width>4</width>
<length>4</length>
<height>8</height>
<insvalue>0</insvalue>
<pkgtrackingid />
</Package>
</packages>
<quotes>
<Quote>
<id>177504</id>
<carrier>fedex</carrier>
<serviceid>FIRST_OVERNIGHT</serviceid>
<baseprice>43.07</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>1.08</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>2.21</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>4.4</amount>
</Charge>
</breakdown>
<netprice>44.15</netprice>
<grossprice>50.76</grossprice>
<tax1amount>1.68</tax1amount>
<tax2amount>3.35</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>First Overnight</servicename>
<currency>CAD</currency>
<timestamp>2015-03-09 04:08:06</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>177505</id>
<carrier>fedex</carrier>
<serviceid>PRIORITY_OVERNIGHT</serviceid>
<baseprice>25.73</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.64</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.32</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.63</amount>
</Charge>
</breakdown>
<netprice>26.37</netprice>
<grossprice>30.32</grossprice>
<tax1amount>1</tax1amount>
<tax2amount>2</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Priority Overnight</servicename>
<currency>CAD</currency>
<timestamp>2015-03-09 04:08:06</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>177506</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_2_DAY</serviceid>
<baseprice>24.49</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.62</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.26</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.5</amount>
</Charge>
</breakdown>
<netprice>25.11</netprice>
<grossprice>28.87</grossprice>
<tax1amount>0.96</tax1amount>
<tax2amount>1.91</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>2 Day</servicename>
<currency>CAD</currency>
<timestamp>2015-03-09 04:08:06</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>177507</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_EXPRESS_SAVER</serviceid>
<baseprice>24.49</baseprice>
<breakdown>
<Charge>
<class>surcharge</class>
<type>pickup</type>
<description>On call pickup</description>
<amount>0</amount>
</Charge>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.62</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>1.26</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>2.5</amount>
</Charge>
</breakdown>
<netprice>25.11</netprice>
<grossprice>28.87</grossprice>
<tax1amount>0.96</tax1amount>
<tax2amount>1.91</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Express Saver</servicename>
<currency>CAD</currency>
<timestamp>2015-03-09 04:08:06</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
<Quote>
<id>177508</id>
<carrier>fedex</carrier>
<serviceid>FEDEX_GROUND</serviceid>
<baseprice>7.2</baseprice>
<breakdown>
<Charge>
<class>fuel</class>
<type>FUEL</type>
<description>Fuel Surcharge</description>
<amount>0.32</amount>
</Charge>
<Charge>
<class>tax</class>
<type>GST</type>
<description>GST @ 5%</description>
<amount>0.38</amount>
</Charge>
<Charge>
<class>tax</class>
<type>QST</type>
<description>QST @ 9.975%</description>
<amount>0.75</amount>
</Charge>
</breakdown>
<netprice>7.52</netprice>
<grossprice>8.65</grossprice>
<tax1amount>0.38</tax1amount>
<tax2amount>0.75</tax2amount>
<tax1name>GST</tax1name>
<tax2name>QST</tax2name>
<servicename>Ground</servicename>
<currency>CAD</currency>
<timestamp>2015-03-09 04:08:06</timestamp>
<deliverydate>2015-03-10</deliverydate>
<carriername>FedEx</carriername>
</Quote>
</quotes>
<documents />
</shipment>
</response>Request
{
"ReadShipment": {
"key": "YOUR-KEY-HERE",
"id": "440504119"
}
}Response
{
"result":0,
"messages":[
],
"shipment":{
"id":440504119,
"shipper":{
"city":"Montreal",
"country":"CA",
"postalcode":"H2Y2V5",
"province":"QC",
"residential":0,
"street1":"999 Saint-Suplice",
"street2":"",
"street3":"",
"tel":"514-394-1690",
"ext":"",
"province_disp":"Quebec",
"country_disp":"Canada",
"attn":"Test Administrator",
"orgname":"TEST",
"email":"info@example.com"
},
"destination":{
"country":"CA",
"country_disp":"Canada",
"orgname":"TEST COMPANY",
"attn":"TEST",
"postalcode":"H4X1L4",
"province":"QC",
"province_disp":"QUEBEC",
"city":"MONTREAL-OUEST",
"street1":"1 MAIN STREET",
"tel":"514-123-4567",
"street3":""
},
"userid":"7365",
"custid":"7486",
"creationdate":null,
"shipmentdate":"2015-03-09",
"statustext":null,
"statuscode":"2",
"selectedquote":null,
"dimensionunit":"IN",
"weightunit":"LB",
"currency":"CAD",
"pickuprefcode":null,
"pickuprequired":"1",
"pickuprequested":"0",
"trackingnumber":null,
"pkgtype":"CUST",
"weight":"5",
"documentsonly":0,
"reconciled":null,
"custrefcode":"440504119",
"tracking":[
],
"options":[
],
"commodities":[
{
"id":"13994",
"marks":"",
"description":"",
"unitofmeasure":"",
"unitprice":"",
"qty":"",
"hscode":"",
"origin":"",
"weight":""
}
],
"customs":[
],
"packages":[
{
"id":null,
"qty":"1",
"description":"BOX",
"weight":"5",
"width":"4",
"length":"4",
"height":"8",
"insvalue":"0",
"pkgtrackingid":""
}
],
"quotes":[
{
"id":"177504",
"carrier":"fedex",
"serviceid":"FIRST_OVERNIGHT",
"baseprice":"43.07",
"breakdown":[
{
"class":"surcharge",
"type":"pickup",
"amount":0,
"description":"On call pickup"
},
{
"class":"fuel",
"type":"FUEL",
"amount":1.08,
"description":"Fuel Surcharge"
},
{
"class":"tax",
"type":"GST",
"amount":2.21,
"description":"GST @ 5%"
},
{
"class":"tax",
"type":"QST",
"amount":4.4,
"description":"QST @ 9.975%"
}
],
"netprice":"44.15",
"grossprice":"50.76",
"tax1amount":"1.68",
"tax2amount":"3.35",
"tax1name":"GST",
"tax2name":"QST",
"servicename":"First Overnight",
"currency":"CAD",
"timestamp":"2015-03-09 04:08:06",
"deliverydate":"2015-03-10",
"carriername":"FedEx"
},
{
"id":"177505",
"carrier":"fedex",
"serviceid":"PRIORITY_OVERNIGHT",
"baseprice":"25.73",
"breakdown":[
{
"class":"surcharge",
"type":"pickup",
"amount":0,
"description":"On call pickup"
},
{
"class":"fuel",
"type":"FUEL",
"amount":0.64,
"description":"Fuel Surcharge"
},
{
"class":"tax",
"type":"GST",
"amount":1.32,
"description":"GST @ 5%"
},
{
"class":"tax",
"type":"QST",
"amount":2.63,
"description":"QST @ 9.975%"
}
],
"netprice":"26.37",
"grossprice":"30.32",
"tax1amount":"1",
"tax2amount":"2",
"tax1name":"GST",
"tax2name":"QST",
"servicename":"Priority Overnight",
"currency":"CAD",
"timestamp":"2015-03-09 04:08:06",
"deliverydate":"2015-03-10",
"carriername":"FedEx"
},
{
"id":"177506",
"carrier":"fedex",
"serviceid":"FEDEX_2_DAY",
"baseprice":"24.49",
"breakdown":[
{
"class":"surcharge",
"type":"pickup",
"amount":0,
"description":"On call pickup"
},
{
"class":"fuel",
"type":"FUEL",
"amount":0.62,
"description":"Fuel Surcharge"
},
{
"class":"tax",
"type":"GST",
"amount":1.26,
"description":"GST @ 5%"
},
{
"class":"tax",
"type":"QST",
"amount":2.5,
"description":"QST @ 9.975%"
}
],
"netprice":"25.11",
"grossprice":"28.87",
"tax1amount":"0.96",
"tax2amount":"1.91",
"tax1name":"GST",
"tax2name":"QST",
"servicename":"2 Day",
"currency":"CAD",
"timestamp":"2015-03-09 04:08:06",
"deliverydate":"2015-03-10",
"carriername":"FedEx"
},
{
"id":"177507",
"carrier":"fedex",
"serviceid":"FEDEX_EXPRESS_SAVER",
"baseprice":"24.49",
"breakdown":[
{
"class":"surcharge",
"type":"pickup",
"amount":0,
"description":"On call pickup"
},
{
"class":"fuel",
"type":"FUEL",
"amount":0.62,
"description":"Fuel Surcharge"
},
{
"class":"tax",
"type":"GST",
"amount":1.26,
"description":"GST @ 5%"
},
{
"class":"tax",
"type":"QST",
"amount":2.5,
"description":"QST @ 9.975%"
}
],
"netprice":"25.11",
"grossprice":"28.87",
"tax1amount":"0.96",
"tax2amount":"1.91",
"tax1name":"GST",
"tax2name":"QST",
"servicename":"Express Saver",
"currency":"CAD",
"timestamp":"2015-03-09 04:08:06",
"deliverydate":"2015-03-10",
"carriername":"FedEx"
},
{
"id":"177508",
"carrier":"fedex",
"serviceid":"FEDEX_GROUND",
"baseprice":"7.2",
"breakdown":[
{
"class":"fuel",
"type":"FUEL",
"amount":0.32,
"description":"Fuel Surcharge"
},
{
"class":"tax",
"type":"GST",
"amount":0.38,
"description":"GST @ 5%"
},
{
"class":"tax",
"type":"QST",
"amount":0.75,
"description":"QST @ 9.975%"
}
],
"netprice":"7.52",
"grossprice":"8.65",
"tax1amount":"0.38",
"tax2amount":"0.75",
"tax1name":"GST",
"tax2name":"QST",
"servicename":"Ground",
"currency":"CAD",
"timestamp":"2015-03-09 04:08:06",
"deliverydate":"2015-03-10",
"carriername":"FedEx"
}
]
}
}QuoteShipment
This method requests that a previously created shipment be quoted. In this process Quote structures are created and returned in this call and subsequent ReadShipment calls.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| quotes | Quote[] | This is a list of quote structures from which a user can choose. |
Examples
Request for quotes on a shipment that fails carrier validation. The carrier message is included in the response. Note that there is no error because the quoting process functioned correctly.
Request
<QuoteShipment> <key>YOUR-KEY-HERE</key> <id>440507771</id> </QuoteShipment>
Response
<?xml version="1.0"?>
<response>
<result>0</result>
<messages>
<Message>
<text>Destination postal code missing or invalid.</text>
<originator>FedEx</originator>
<code>521</code>
</Message>
</messages>
<quotes/>
</response>SubmitShipment
This method submits shipment information to a carrier and generates waybills and other documents. After this call the shipment can no longer be modified or deleted.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
| quoteid | int | The quote identifier returned in QuoteShipment or taken from one of the Quote structures within the Shipment structure. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| documents | Document[] | List of documents produced for the shipment |
| trackingnumber | string | The master tracking number assigned to this shipment |
Examples
Successfully submit a shipment to the carrier.
Request
<SubmitShipment> <key>YOUR-KEY-HERE</key> <id>440880935</id> <quoteid>281830</quoteid> </SubmitShipment>
Response
<?xml version="1.0"?>
<response>
<result>0</result>
<messages>
<Message>
<text/>
<originator>carrier</originator>
<code>0</code>
</Message>
</messages>
<documents/>
</response>VoidShipment
This method indicates to the carrier that the shipment is to be cancelled. If this is successful, financial transactions for the shipment are reversed. Note that this does not guarantee that there will be no fees for the shipment as a voided shipment can still physically be given to a carrier.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | string | The shipment identifier returned in CreateShipment. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Examples
An attempt to void a shipment that was either already voided or was never submitted to the carrier.
Request
<?xml version="1.0" encoding="UTF-8"?> <VoidShipment> <key>YOUR-KEY-HERE</key> <id>440882464</id> </VoidShipment>
Response
<?xml version="1.0"?>
<response>
<result>-7</result>
<messages>
<Message>
<text>The shipment is not in the correct state for submission</text>
<originator>system</originator>
<code>-7</code>
</Message>
</messages>
</response>Successfully void a shipment.
Request
<?xml version="1.0" encoding="UTF-8"?> <VoidShipment> <key>YOUR-KEY-HERE</key> <id>440882464</id> </VoidShipment>
Response
<?xml version="1.0"?>
<response>
<result>0</result>
<messages>
<Message>
<text>Success</text>
<originator>carrier</originator>
<code>0</code>
</Message>
</messages>
</response>RequestPickup
This method requests a pickup booking for the given shipment. If the consolidate property is set to 1 or consolidation is mandatory then all shipments with the same (or very similar) pickup address will also be booked for pickup. To determine if a pickup should be booked, retrieve the pickuprequired and pickuprequested properties of a shipment.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| shipmentid | string | The shipment identifier returned in CreateShipment. |
| date | string | YYYY-MM-DD for pickup (local time) |
| ready | string | HH:MM ready time (local time) |
| close | string | HH:MM pickup until time (local time) |
| consolidate | int | 1 means book pickups for other shipments at the same location. For some carriers (e.g. Canpar) consolidation is automatic |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| id | int | Internal Pickup Reference which should be used in VoidPickup |
| reference | string | Carrier Pickup Confirmation Code which should be used when contacting the carrier directly |
Examples
Attempt to book a pickup with a window rejected by the carrier.
Request
<RequestPickup> <key>YOUR-KEY-HERE</key> <shipmentid>440881023</shipmentid> <date>2015-06-23</date> <ready>13:00</ready> <close>14:00</close> <consolidate>1</consolidate> </RequestPickup>
Response
<?xml version="1.0"?>
<response>
<result>-104</result>
<messages>
<Message>
<text>FedEx cannot accommodate the pickup window you specified -- please allow more time</text>
<originator>carrier</originator>
<code>-104</code>
</Message>
</messages>
<id/>
<reference/>
</response>VoidPickup
This method cancels a previously booked pickup. One cannot void a shipment if there is a pickup booked for that shipment.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| id | int | The pickup identifier returned from RequestPickup. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Examples
Attempt to void a pickup that you do not have access to
Request
<?xml version="1.0" encoding="UTF-8"?> <VoidPickup> <key>YOUR-KEY-HERE</key> <id>68919</id> </VoidPickup>
GetTransactions
This method retrieves financial data for the account, invoice or a specific shipment. If multiple transactions exist for a shipment the shipment fee is the sum of those transactions. This is also indicative of a shipment correction.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| shipmentid | string | Shipment Reference to get transactions for (can be empty) |
| invoiceid | string | Invoice Number to get transactions for (can be empty) |
| datestart | string | YYYY-MM-DD HH:MM:SS start range UTC |
| dateend | string | YYYY-MM-DD HH:MM:SS end range UTC |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| transactions | Transaction[] | Transaction Data |
OpenAccount
This method allows an authorised caller to request a new account.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| agreement | string | An agreement token provided to callers authorised to open accounts required |
| reference | string | A caller specified customer reference |
| username | string | Requested Administrator Username required |
| password | string | Requested Administrator Password required |
| string | Administrator Email Address required | |
| fullname | string | Administrator Full Name required |
| orgname | string | Name of Organization required |
| address | Card | Shipping Address of organization required |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
| custid | string | Customer ID for the newly created account |
Examples
Open an account with a valid agreement and authorisation
Request
<OpenAccount>
<key>YOUR-KEY-HERE</key>
<agreement>YOUR-AGREEMENT-HERE</agreement>
<username>test_user</username>
<password>test_password</password>
<email>test@example.com</email>
<address>
<attn>Contact Name</attn>
<street1>1 MAIN STREET</street1>
<street2 />
<street3 />
<orgname>Account Name</orgname>
<city>MONTREAL-OUEST</city>
<province>QC</province>
<postalcode>H4X1L4</postalcode>
<country>CA</country>
<tel>514-123-4567</tel>
<email />
<residential />
<tax_id />
<ext />
</address>
</OpenAccount>ShipmentQuery Beta
This method queries the shipment database
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| constraints | Filter[] | Query for searching. Note that multiple filters on the same subject are not supported. |
| firstindex | int | The index of the first result to return |
| limit | int | The maximum number of items to return. This value may be ignored if it is too great |
| username | string | The user account in which the shipment should be created. This property should be left blank unless you have permission to create shipments on behalf of the named user. |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| shipments | ShipmentSummary[] | List of shipment summaries |
Examples
Query shipments without a constraint which returns shipments based on the creation timestamp
Request
<?xml version="1.0" encoding="UTF-8"?> <ShipmentQuery> <key>YOUR-KEY-HERE</key> <firstindex>0</firstindex> <limit>10</limit> </ShipmentQuery>
Query shipments with a constraint on the status timestamp. The return order is always based on creation date
Request
<?xml version="1.0" encoding="UTF-8"?> <ShipmentQuery> <key>YOUR-KEY-HERE</key> <firstindex>5</firstindex> <limit>10</limit> <constraints> <Filter> <subject>statustimestamp</subject> <value>1594913275</value> <equality>gt</equality> </Filter> </constraints> </ShipmentQuery>
GetUser
This method retrieves a user record. This method is restricted to callers with the ROLE_API_USER privilege.
Parameters
| Name | Type | Details |
|---|---|---|
| key | string | This is your API Key which must be submitted with every request and uniquely identifies your account. |
| username | string | The Username of the requested user record |
Returned Data
| Name | Type | Details |
|---|---|---|
| result | int | Result code for operation. 0 indicates success, positive numbers are partial success and all negative numbers are errors |
| user | User | The user record to return |
| messages | Message[] | A list of human readable text messages which can potentially be passed to customers or used for debugging. |
Structures
Card
Properties
| Name | Type | Details |
|---|---|---|
| attn | string | Attention (Name) |
| street1 | string | Street address (line 1) |
| street2 | string | Street address (line 2) |
| street3 | string | Street address (line 3) |
| orgname | string | Company Name |
| city | string | City Name |
| province | string | Province Code or Name. For USA and Canada it must be a two character uppercase province/state code. |
| postalcode | string | Postal Code / ZIP |
| country | string | Two character ISO-3166-1 country code required |
| tel | string | Telephone number |
| string | Email address | |
| residential | int | 0 or 1 for residential flag |
| tax_id | string | Tax Number which may appear on international forms where necessary |
| ext | string | Telephone extension |
Package
Properties
| Name | Type | Details |
|---|---|---|
| id | int | Internal reference number read-only |
| qty | int | Quantity of this package definition. During submission this may be exploded so that each package is duplicated with a qty of 1 |
| description | string | Description used internally and for some labelling. Won't appear on most waybills. |
| weight | float | Weight of the package (in Shipment weight unit) |
| width | float | Package Width |
| length | float | Package Length |
| height | float | Package Height |
| insvalue | float | Insurance amount for package |
| pkgtrackingid | string | Individual package tracking number read-only |
Shipment
Properties
| Name | Type | Details |
|---|---|---|
| id | string | Internal unique reference number read-only |
| shipper | Card | Shipping/Pickup Address |
| destination | Card | Recipient Address |
| broker | Card | Broker Address (if applicable) |
| userid | int | Internal reference number for the user associated with the shipment (may be multiple users per account) read-only |
| custid | string | Internal reference number for the customer account associated with the shipment read-only |
| accountreference | string | Reference code for the customer account read-only |
| creationdate | int | Timestamp the shipment was created read-only |
| shipmentdate | string | YYYY-MM-DD for shipment estimating date (local origin time) required |
| statustext | string | General human readable status description read-only |
| statuscode | int | Shipment status code read-only
|
| statustimestamp | int | Status Update Timestamp |
| selectedquote | int | The ID of the quote used for shipping (where multiple quotes are maintained) read-only |
| dimensionunit | string | IN or CM required |
| weightunit | string | LB or KG required |
| currency | string | 3 character currency code for insurance amount and commodity values required |
| pickuprefcode | string | The confirmation number for an associated pickup read-only |
| pickuprequired | int | 1 if the provision indicates a pickup request is needed for this shipment read-only |
| pickuprequested | int | 1 if the pickup request has been made read-only |
| pickupid | int | Internal reference number for the pickup request read-only |
| tracking | Tracking[] | The shipment tracking data read-only |
| trackingnumber | string | Carrier provided tracking number read-only |
| pkgtype | string | Packaging Type
|
| weight | float | Reported weight of packages (read only) read-only |
| documentsonly | int | 0 for non-documents and 1 for documents-only shipment |
| reconciled | int | 1 if the shipment has been billed read-only |
| custrefcode | string | Customer Reference Code(s) with # as a place holder for the shipment identifier |
| accesstoken | string | A unique string or hash required for some access control operations (such as tracking) |
| options | Option[] | Options requested for the shipment |
| commodities | Commodity[] | Commodities for customs declarations |
| customs | Param[] | Properties specific to customs preparation. See the Customs section for details. |
| packages | Package[] | List of packages |
| quotes | Quote[] | List of quotes received for this shipment read-only |
| documents | Document[] | List of documents available for the shipment read-only |
| emailshipper | int | Send an e-mail with shipment details to the shipper e-mail address |
| emaildestination | int | Send an e-mail with shipment tracking link to the consignee e-mail address |
| paymentoption | int | Payment method for this shipment
|
| paymentaccount | string | Account number associated with specified payment option |
| deliverydate | string | YYYY-MM-DD for shipment delivery date if known read-only |
| deliverytime | string | HH:MM for shipment delivery time if known read-only |
| deliverysignature | string | Signature recorded at delivery if known read-only |
| limitcarriers | string | Limit to specific carrier (carrier reference) |
| limitservices | string | Limit to specific service (serviceid reference) |
ShipmentSummary
Properties
| Name | Type | Details |
|---|---|---|
| id | string | Internal unique reference number read-only |
| creationdate | int | Timestamp the shipment was created |
| shipmentdate | string | YYYY-MM-DD for shipment estimating date (local origin time) |
| statustext | string | General human readable status description |
| statuscode | int | Shipment status code read-only
|
| statustimestamp | int | Status Update Timestamp |
| trackingnumber | string | Carrier provided tracking number |
| trackingtimestamp | int | Tracking Update Timestamp |
| custrefcode | string | Customer Reference Code |
| accesstoken | string | A unique string or hash required for some access control operations (such as tracking) |
| references | Param[] | A set of reference values |
| shipper | Card | Shipper Address |
| destination | Card | Destination Address |
Tracking
Properties
| Name | Type | Details |
|---|---|---|
| date | string | YYYY-MM-DD (Local) read-only |
| time | string | HH:MM (Local) read-only |
| event | string | Carrier specific event code read-only |
| city | string | City of event if available read-only |
| province | string | Province of event if available read-only |
| country | string | Country of event if available read-only |
| class | string | Unified event classification read-only |
| text | string | General textual data read-only |
| trackingnumber | string | Identifies individual packages in multi-package shipments read-only |
Commodity
Properties
| Name | Type | Details |
|---|---|---|
| id | int | Internal Reference read-only |
| marks | string | Unique markings |
| description | string | Description for customs |
| unitofmeasure | string | Standardised measurement unit (default should be EA for 'each') |
| unitprice | float | Price in shipment currency for each unit |
| qty | float | Quantity of units (total value is qty x unitprice) |
| hscode | string | Harmonised Code or Schedule B code |
| origin | string | ISO 3166-1 country code for commodity origin |
| weight | float | Weight in Shipment Weight Unit |
| ext | Param[] | Additional data depending on documents required |
Document
Properties
| Name | Type | Details |
|---|---|---|
| id | int | Internal Reference read-only |
| type | string | Type of document read-only
|
| packageid | int | If this document is specific to a package the package Id is present here read-only |
| mimetype | string | Always application/pdf for laser labels but if configured the document could be application/zpl for Zebra thermal printers (or another type for future thermal implementations). read-only |
| formid | string | Form code (e.g. b13a, commercial_invoice) read-only
|
| url | string | The URL to use for retrieving the document read-only |
Transaction
Properties
| Name | Type | Details |
|---|---|---|
| id | string | Internal Reference read-only |
| invoiceid | string | Invoice Number read-only |
| net | float | Transaction before Tax read-only |
| gross | float | Transaction after Tax read-only |
| tax1amount | float | Tax 1 amount read-only |
| tax2amount | float | Tax 2 amount read-only |
| tax1name | string | Tax 1 code read-only |
| tax2name | string | Tax 2 code read-only |
| shipmentid | string | Reference if the transaction is for a shipment read-only |
| description | string | A text description of the transaction read-only |
| currency | string | ISO currency code read-only |
| timestamp | string | YYYY-MM-DD HH:MM:SS UTC read-only |
Quote
Properties
| Name | Type | Details |
|---|---|---|
| id | int | Internal reference number. To ship with this quote it should be passed to SubmitShipment. read-only |
| carrier | string | Carrier reference read-only |
| serviceid | string | Service reference (specific to carrier) read-only |
| baseprice | float | Price for freight (before surcharges) read-only |
| breakdown | Charge[] | Charge breakdown read-only |
| netprice | float | Total price before tax read-only |
| grossprice | float | Total price including tax read-only |
| tax1amount | float | Tax 1 amount read-only |
| tax2amount | float | Tax 1 code read-only |
| tax1name | string | Tax 2 amount read-only |
| tax2name | string | Tax 2 code read-only |
| servicename | string | Human readable service description read-only |
| currency | string | ISO currency code read-only |
| timestamp | string | YYYY-MM-DD HH:MM:SS UTC read-only |
| deliverydate | string | YYYY-MM-DD Local read-only |
| carriername | string | Human readable carrier name read-only |
| listnetprice | float | The published rate before tax (if available) read-only |
| resellernetprice | float | The reseller rate before tax (if available) read-only |
| costnetprice | float | The account rate before tax (if available) read-only |
Charge
Properties
| Name | Type | Details |
|---|---|---|
| class | string | Category of surcharge read-only
|
| type | string | Carrier specific code for surcharge, tax code for tax read-only |
| description | string | The amount of the charge read-only |
| amount | float | Human readable description read-only |
Option
Properties
| Name | Type | Details |
|---|---|---|
| code | string | Standardised option code. Each code has a different set of parameters (passed in the params property).
|
| params | Param[] | List of parameters specific to the option code. The default parameter name for an option is enable and for most options the value 1 is used to activate the option and 0 is used to de-activate it. |
Param
Properties
| Name | Type | Details |
|---|---|---|
| name | string | Parameter name |
| value | string | String encoded value specific to the parameter name |
Message
Properties
| Name | Type | Details |
|---|---|---|
| text | string | Human readable message read-only |
| originator | string | Optional carrier code if the message was generated by the carrier read-only |
| code | string | Non-readable message Id read-only |
Filter
Properties
| Name | Type | Details |
|---|---|---|
| subject | string | Field or property to be evaluated. Note that multiple filters with the same subject are not supported.
|
| value | string | Value to be compared to the subject |
| equality | string | Type of comparison to be performed.
|
User
Properties
| Name | Type | Details |
|---|---|---|
| username | string | The login username for this user |
| fullname | string | The full (descriptive) name for this user |
| roles | string | A comma separated list of role keywords |
| orgid | int | The identifier of the organization the user is assigned to |
| usergroupid | int | The identifier of the user group the user is assigned to |
| resellerid | int | The identifier of the reseller the organization is assigned to |
| orggroupid | int | The identifier of the associate the organization is assigned to |
| partnerid | int | The identifier of the partner the organization is assigned to |
| password | string | The user password hash used for authentication |
| avatar | string | An avatar URL if defined for this user |
| orgname | string | The name of the organization the user is assigned to |
| string | The email address for this user, if defined | |
| identityid | int | The identifier of the identity the organization is assigned to |
| identitylogo | string | The logo associated with the identity |
| identityname | string | The name associated with the identity |
Customs Parameters
The shipment customs property supports a number of parameters described below. The properties are presented as an array of Param pairs where the name property is taken from the list below.
| Parameter Name | Meaning and values |
|---|---|
| termsofsale | Terms Of Sale
|
| dutiespayor |
Party Paying Duty Charges
|
| dutiesaccount | Third-Party Duty Account number. If dutiespayor is set to THIRD_PARTY then the account number must be provided in this property. |
| purpose |
The purpose of this export.
|
| relationship |
The relationship between the exporter and importer.
|
| cifreight | Commercial Invoice Freight Amount. This amount will appear in the commercial invoice categorized as Freight. |
| ciinsurance | Commercial Invoice Insurance Amount. This amount will appear in the commercial invoice categorized as Insurance. |
| comments | This free-form text will appear in a Comments section of the Commercial Invoice |
| commercial_invoice |
Should the system produce a Commercial Invoice?
|
Error Codes
The error codes described below may be returned by operations in the "result" property. Not all error codes defined here are relevant to the API.
| Code | Description |
|---|---|
| 0 | Success |
| 1 | Request Succeeded but there are some concerns that generally appear in the associated messages |
| 2 | The request returned more result than expected and only the first is presented |
| -1 | Access Token or Key is invalid |
| -2 | Invalid username and/or password presented |
| -3 | Entity type in operation is not recognised or not appropriate |
| -4 | Entity identifier is not in the database |
| -5 | The username does not meet the format requirements |
| -6 | This username already exists or is disallowed |
| -7 | Subject does not have the required status for the requested change (e.g. attempt to modify shipment address after pickup) |
| -8 | Cannot use this address because it conflicts with another account |
| -9 | Requested entity cannot be located |
| -10 | Data upload failed |
| -11 | Required argument for operation is missing |
| -12 | Change to a locked entity is not permitted in general or given the current state |
| -13 | Cannot delete the given entity because there are dependencies in place |
| -14 | Change is not permitted due to age of the entity |
| -15 | The provision referred to is not available to the given entity |
| -16 | Error constructing a template |
| -17 | Error sending an e-mail |
| -18 | Provided argument is not amongst the allowed values |
| -19 | This operation requires at least one quote |
| -20 | This operation cannot be completed when a relevant e-mail address is missing |
| -21 | Cannot perform this operation because the current context does not match the entity owner |
| -22 | Operation involves multiple currencies where this is not permitted |
| -23 | Operation involves tax codes other than the allowed codes for this entity |
| -24 | Some operations are prohibited on flagged shipments (such as invoicing) |
| -25 | The account currently has shipping disabled |
| -26 | The account currently has login disabled |
| -27 | The current context is not permitted to perform this action |
| -28 | General internal error |
| -29 | Requested operation is not recognised |
| -30 | Cannot perform this operation because it is connected with a shipment that cannot be deleted |
| -31 | Tracking number not recognised either by the carrier or the internal tracking database |
| -32 | Cannot perform this operation until the shipment has a customer price assigned |
| -33 | This operation would exceed the allowed credit limit |
| -34 | Operation prevented because customer has been flagged |
| -35 | Operation prevented due to shipment lock |
| -101 | Unspecified error raised by Courier Integration |
| -102 | Error raised by Courier Address Validation |
| -103 | Courier originating address alternative recommendations |
| -105 | Alert raised by Courier Module |
| -104 | Courier Message could not be validated |
Testing
You can construct and send sample requests here and view the response. To use a sample, first enter your API key below and then select a sample to have your key automatically insterted into the request.