Application Programming Interface Document
Version 2.0
November 2013
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Table of Contents
1.
Introduction ..............................................................................................................5
1.1
1.2
1.3
1.4
2.
Purpose and Scope .........................................................................................................5
Audience ........................................................................................................................5
System Overview ............................................................................................................5
Assumptions ...................................................................................................................5
Interface Specifications ..............................................................................................6
2.1 Security / Credentials......................................................................................................6
2.1.1 Provisioning.................................................................................................................6
2.1.2 IP Restriction Security ..................................................................................................6
2.1.3 Test Credentials ...........................................................................................................6
3.
Workflow ..................................................................................................................7
3.1 Batch Workflow ..............................................................................................................7
3.1.1 EDI X12 ........................................................................................................................7
3.1.2 XML/Pipe Delimited.....................................................................................................7
3.2 Real-Time Workflow .......................................................................................................7
4.
Agreement of Record / Format ..................................................................................7
4.1
4.2
5.
Field Specification ...........................................................................................................7
General Data Limitations/Rules .......................................................................................8
Transactions, Formats, and Protocols .........................................................................9
5.1 Tracking Number Generation ..........................................................................................9
5.2 Label Overview ...............................................................................................................9
5.2.1 Label Requirements .....................................................................................................9
5.2.2 Sample Labels ............................................................................................................ 10
5.3 Structure for Batch Messages ........................................................................................ 11
5.3.1 X12 EDI ...................................................................................................................... 11
5.3.2 Pipe Delimited Flat File Shipment Notification ............................................................ 11
5.3.2.1 Shipment Record .................................................................................................... 11
5.3.2.2 Item Record ............................................................................................................ 14
5.4 Structure for Real-Time (SOAP/REST) Protocol Messages ............................................... 15
5.4.1 Function: CheckItems ................................................................................................. 15
5.4.1.1 Message Name: CheckItems.................................................................................... 15
5.4.1.2 Message Name: CheckItemsResponse ..................................................................... 16
5.4.2 Function: CheckoutLegacy .......................................................................................... 16
5.4.2.1 Message Name: CheckoutLegacy ............................................................................. 16
5.4.2.2 Message Name: CheckoutLegacyResponse .............................................................. 18
5.4.3 Function: Countries.................................................................................................... 19
5.4.3.1 Message Name: Countries....................................................................................... 19
5.4.3.2 Message Name: CountriesResponse ........................................................................ 20
5.4.4 Function: Currencies .................................................................................................. 20
5.4.4.1 Message Name: Currencies ..................................................................................... 20
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 2 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.4.4.2 Message Name: CurrenciesResponse....................................................................... 21
5.4.5 Function: CurrencyInfo............................................................................................... 22
5.4.5.1 Message Name: CurrencyInfo.................................................................................. 22
5.4.5.2 Message Name: CurrencyInfoResponse ................................................................... 23
5.4.6 Function: QueryQuote ............................................................................................... 23
5.4.6.1 Message Name: QueryQuote .................................................................................. 24
5.4.6.2 Message Name: QueryQuoteResponse .................................................................... 24
5.4.7 Function: AcknowledgeQuote .................................................................................... 25
5.4.7.1 Message Name: AcknowledgeQuote ....................................................................... 25
5.4.7.2 Message Name: AcknowledgeQuoteResponse......................................................... 25
5.4.8 Function: DutyTaxRequest ......................................................................................... 26
5.4.8.1 Message Name: DutyTaxRequest ............................................................................ 26
5.4.8.2 Message Name: iParcelDutyTaxResponse ................................................................ 27
5.4.9 Function: reprintlabel ................................................................................................ 27
5.4.9.1 Message Name: iparcelPackageLabelReprint ........................................................... 27
5.4.9.2 Message Name: iParcelReprintResponse ................................................................. 28
5.5 Function: Quote ............................................................................................................ 28
5.5.1 Message Name: Quote ............................................................................................... 28
5.5.2 MessageName: QuoteResponse ................................................................................. 30
5.6 Function: SubmitParcel ................................................................................................. 30
5.6.1 MessageName: SubmitParcel ..................................................................................... 30
5.6.2 Message Name: SubmitParcel Response ..................................................................... 32
5.6.3 Message Name: Error Response ................................................................................. 33
5.7 Function: Checkout ....................................................................................................... 33
5.7.1 Message Name: Checkout .......................................................................................... 33
5.7.2 Message Name: CheckoutResponse ........................................................................... 34
6.
Message Name: Error Response ............................................................................... 35
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 3 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
DOCUMENT OWNERS:
Author
Josh Stevens
Department
IT
REVISION HISTORY:
Version
Date
Author
1.0
10/30/2012 Josh Stevens
2.0
10/25/2013 Yursil Kidwai
Baselined
Description of Change
Documentation Creation
i-parcel Proprietary
Use pursuant to Company Instructions
Page 4 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
1. Introduction
1.1 Purpose and Scope
The purpose of this document is to describe system-to-system interface protocols
and practices between i-parcel and partners.
1.2 Audience
This document is intended for the Business Analysts, System Architects, System
Engineers, and Development and Testing organizations at i-parcel and partner
systems.
1.3 System Overview
The i-parcel API provides a reliable, secure, and easy interface between a partner
and the i-parcel system. By means of this API, a partner may obtain shipping, duty,
and tax rates to more than ninety countries, create a package pre-alert in the i-parcel
system, and get useful currency coding information. Additionally, a partner may clear
a logistics-only quote for parcel creation, and query it at any time.
1.4 Assumptions
1. The partner will establish appropriate credentials with i-parcel IT prior to
executing API calls.
2. The partner is familiar with SOAP and REST communication technologies.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 5 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
2. Interface Specifications
2.1 Security / Credentials
2.1.1 Provisioning
To provisioning new authentication credentials, please begin by contacting
ykidwai@i-parcel.com as part of an overall SWO.
2.1.2 IP Restriction Security
If requests will be provided via batch services or a known IP-Address, i-parcel
may elect to establish IP restrictions.
2.1.3 Test Credentials
Credentials:
Sequence: 1451293A-5C2E-E211-A8D8-CC9812142D0A
CustomerID: 1226
Operational Credentials:
Username: custtest
Password: custtest
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 6 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
3. Workflow
3.1 Batch Workflow
In the batch workflow, a partner will transmit flat files via the flat file formats,
described in section 5.3 to notify i-parcel of shipment data and associate the proper
tracking numbers using the agreed upon specification. Tracking numbers should be
generated by the partner according to section 5.1.
3.1.1 EDI X12
The EDI X12 workflow relies upon the partner sending the appropriate files via a
third party partner or internal file transmission
3.1.2 XML/Pipe Delimited
Batch XML/Pipe Delimited workflow files are transmitted using a tool available on the
website. Alternative file transport methods require additional communication with iparcel IT.
3.2 Real-Time Workflow
In the real-time workflow, a partner uses SOAP/REST API’s described in section 5.4
for communicating shipments, receiving tracking numbers and labels in real time.
4. Agreement of Record / Format
4.1 Field Specification
1. Field Name – name of field generally used as screen label if collected
from screen or refers i-parcel’s commonly used business term
2. Tag Name – code used for formatting the XML document
3. M/O/C Flags:
M: Mandatory
O: Optional
C: Conditional
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 7 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
4. Length – determines the number of digits/ alphanumeric characters
allowable for an element
5. Format
B: Boolean
N: Numeric
A/N: Alphanumeric
C: including special characters
Date: ISO Date
4.2
General Data Limitations/Rules
1. OPTIONAL FIELDS: All fields listed as optional are optional on all actions.
Tags may or may not be sent for these fields. Optional fields if sent must
meet level field edits.
2. MANDATORY FIELDS: Fields required from the sending system. Tags
are to be sent with valid values.
3. CONDITIONAL FIELDS: All conditional tags are required for the
conditions specified in the remarks. Otherwise, optional.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 8 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5. Transactions, Formats, and Protocols
5.1 Tracking Number Generation
In the batch workflow, i-parcel tracking numbers follow the following format:
M/O/C Format
Length
Remarks
Account Number
M
A/N
6
Unique
M
A/N
16
Provided by your account
representative
A unique 16 digit incrementing code
The two fields should be concatenated and presented on the label per section 5.2.
5.2 Label Overview
i-parcel requires shipping labels to be affixed to all packages ran through the
logistics system. These labels are scanned to create tracking and job events, and to
ensure data integrity. Label’s may be generated via the real-time API (See 5.4.9) or
generated by the partner in an alternative layout, as long as it meets the
requirements in section 5.2.1.
It is important to note that for proper customs procedure, and for the general
functionality of the system, a given package must have one label with one tracking
number on it, with that tracking number representing a parcel in the i-parcel system
that includes the items (and only the items) within the package’s box.
5.2.1 Label Requirements





The label must be printed with a resolution of at least 72 DPI
The label must feature the i-parcel tracking number of the parcel it
represents in Code 128 Format
The bar code must be at least 0.75” x 2.25”
The bar code must be black on a white background
There must be 0.5” of empty space on all four sides of the bar code.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 9 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.2.2 Sample Labels
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 10 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.3 Structure for Batch Messages
5.3.1 X12 EDI
i-parcel supports X12 EDI data formats for shipment notifications.
US Shipments (X12 v. 4010):
i-parcel will receive a 215 (Motor Carrier Pick-up Manifest).
i-parcel will send a 210 (Motor Carrier Freight Details and Invoice) and a 214
(Transportation Carrier Shipment Status Message).
EU shipments (UN/EDIFACT v. D01A)
i-parcel will receive an IFTMIN (freight manifest) and send IFTSTA (tracking status
file) and an INVOIC (invoice).
5.3.2 Pipe Delimited Flat File Shipment Notification
File may contain two record types, shipment record and item record. Files may be
transmitted via web site interaction, once user provisioning is complete.
5.3.2.1
Shipment Record
Internal Field Name
M/O/C Format
Record Type
PackageNum
M
M
A/N
A/N
Literal: “S”
Package Number in File
Payment Currency
O
A/N
Currency Payment is made in (used
if looking up Duty/Tax Rates)
Payment Method
O
A/N
Payment only used for iParcel
collect
DDP
M
A/N
1 for DDP, 0 for DDU
Service
M
A/N
112 for Immediate
115 for Preferred
119 for i-Parcel Saver
128 for i-Parcel Saver Deferred
Baselined
Length
i-parcel Proprietary
Use pursuant to Company Instructions
Remarks
Page 11 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Reference
O
A/N
Any Reference for Package
Identification
TrackingBarcode
O
A/N
Tracking Barcode (Order # or other
identifier on package)
If left blank i-parcel will return the
tracking number, if completed it
must be the agreed numbering
format with i-parcel
GeneralDescription
M
A/N
General Description
(CD,Book,DVD)
CustomsValue
M
A/N
Value of package for Customs
Purposes (sale price)
CustomsValueCurrency
M
A/N
Currency the Customs Valus is in
(3 Letter Code)
InsuranceValue
O
A/N
Value for insurance purposes (This
may incur addtional charges)
Items
M
A/N
Number of Items in Package
WeightUnits
M
A/N
Weights Units
Valid values:
LBS
KGS
Weight
M
A/N
Weight in Weight Units
MeasureUnits
M
A/N
Measurement Units Valid values:
IN
CM
Length
M
A/N
Length of Package in Measurement
Units
Width
Baselined
M
A/N
i-parcel Proprietary
Use pursuant to Company Instructions
May be provided as 0
Width of Package in Measurement
Units
Page 12 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
May be provided as 0
Height of Package in Measurement
Units
Height
M
A/N
ShipperName
M
A/N
May be provided as 0
Shipper Name
ShipperAdd1
M
A/N
Shipper Address Line 1
ShipperAdd2
O
A/N
Shipper Address Line 2
ShipperCity
M
A/N
Shipper City
ShipperStateProvince
M
A/N
Shipper State or Province
ShipperPostcode
M
A/N
Shipper Postcode or Zipcode
ShipperCountryCode
M
A/N
Shipper Country Code (ISO 2
Letter)
ConsigneeName
M
A/N
Consignee Name
ConsigneeAdd1
M
A/N
Consignee Address Line 1
ConsigneeAdd2
O
A/N
Consignee Address Line 2
ConsigneeCity
M
A/N
Consignee City
ConsigneeStateProvince
M
A/N
Consignee State or Province
ConsigneerPostcode
O
A/N
Consignee Postcode or Zipcode
Based on country address
requirements
ConsigneeCountryCode
M
A/N
Consignee Country Code (ISO 2
letter)
Phone
M
A/N
Consignee Phone Number
Email
O
A/N
Consignee Email
InCountryControlNum
O
A/N
In Country Control Number
(Customs required number for
clearance)
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 13 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
TrackbyEmail
M
A/N
1 or 0 sets automatic tracking by
email of package to the Consignee
Email
TrackBySMS
M
A/N
1 or 0 sets automatic tracking by
sms of package to the Consignee
Phone
5.3.2.2
Item Record
Internal Field Name
M/O/C Format
Length
Remarks
Record Type
PackageNum
M
M
A/N
A/N
Literal: “I”
Package Number in File
Description
M
A/N
Description of Item
Items
M
A/N
Number of this item.
Items will multiply with the item
value, total items by item value
must equal customs value
Weight
M
A/N
Weight of Items
Value
M
A/N
Value of Items
Items will multiply with the item
value, total items by item value
must equal customs value
Harmonization Code of Item
HSCode
O
A/N
CountryofMan
M
A/N
Country of Manufacture (ISO 2
Letter)
SKU
M
A/N
Individual Item Sku
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 14 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.4 Structure for Real-Time (SOAP/REST) Protocol Messages
5.4.1 Function: CheckItems
5.4.1.1
Message Name: CheckItems
This API call performs the task of determining eligibility for a particular item for
international shipment, based on its SKU and what country it could potentially be
shipped to.
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
SKUs
M
A/N
256
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
The SKUs passed must match
the SKUs that were provided as
such during the initial catalog
feed to the i-parcel system (see
“Message Name:
DutyTaxRequest”). The
formatting for this list is as
follows: sku1,sku2,sku3
CountryCode
M
A/N
2
BaseCurrency
M
A/N
3
Currency
M
A/N
3
CatalogPrice
M
Boolean
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
This is the ISO two-digit country
code of the country that eligibility
is to be tested against. For
example, CA.
This is the base currency to
compare against for currency
conversion of the items’ prices,
presented as the ISO three-digit
currency code. Generally will be
USD.
– This is the currency that the
items’ prices are to be converted
to, for example CAD
This is a Boolean value
representing whether the call is
to return item pricing information
or not. If this is false, all returned
Page 15 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
price values will be 0.
5.4.1.2
Message Name: CheckItemsResponse
This API call performs the task of determining eligibility for a particular item for
international shipment, based on its SKU and what country it could potentially be
shipped to.
Field Name
M/O/C
<Array 0:N>
itemSku
itemValid
itemPrice
itemPriceNumeric
currentPrice
CatalogPrice
</Array 0:N>
Format
Length
M
M
A/N
A/N
2
256
M
M
M
M
A/N
A/N
A/N
Boolean
2
3
3
Remarks
Sample:
[{"itemSku":"n2610","itemValid":"1","itemPrice":"USD149.99","itemPriceNumeric":"14
9.99","totalPrice":"USD149.99","currentPrice":"149.9900"}]
5.4.2 Function: CheckoutLegacy
5.4.2.1
Message Name: CheckoutLegacy
This API call performs the task of determining eligibility for a particular item for
international shipment, based on its SKU and what country it could potentially be
shipped to.
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
This string represents the
WebID of the Merchant. It is
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 16 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
CheckoutType
M
A/N
Cart
M
A/N
10
provided by i-parcel and is used
for authentication purposes.
This string can be one of three
values: quote, order, or
manualorder. Passing quote
ensures the call will result in a
JSON object containing the
landed costs of a particular cart
as well as other miscellaneous
information. Order returns the iparcel payment link for a call (for
Global e-commerce integrations
only) and manualorder returns a
shipping label for a particular
cart, in the form of a link to a
PDF file.
This string must be passed as a
comma-separated list of tildedelimited cart elements. For
example: n2610~1, n2611~2
Each comma-separated element
in the list is to be split by tildes
using the following format:
Index 0 : SKU
Index 1: Quantity
Additional indexes exist for
specific functionality.
ShipAddr
M
A/N
3
BillAddr
Reference
M
M
A/N
Boolean
3
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
The ship-to address, presented
as a pipe-delimited list of
elements. For example:
Name|Line1|Line2|City|Region|
Misc.|Zip/Postal Code|Country
Code|Phone|Email
The country field must always
be the ISO two-digit country
code representation of the
shipping country.
A merchant-provided reference
for the quote. Often used for
custom functionality, for
example passing a timer to the
Page 17 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Service
M
N
DDP
M
Boolean
payment link.
The service level code of
whatever service an order is to
be for. For quotes, this field can
be left blank; doing so will cause
all valid service levels to be
contained in the response as a
list. Currently, the valid service
levels are 112, 115, and 119.
Whether the shipment is to be
Delivered Duty Paid, currently
must always be set to True.
BaseCurrency
This is the base currency to
compare against for currency
conversion of the items’ prices,
presented as the ISO three-digit
currency code. Generally will be
USD.
This is the currency that the
items’ prices are to be converted
to, for example CAD.
Currency
5.4.2.2
Message Name: CheckoutLegacyResponse
The response can vary depending on the arguments supplied. Quotes return a
JSON list of rate responses ( If a quote fails, the rateFailed element will be nonblank), while manual orders return a link to the label. Orders return a link to the iparcel checkout. Note that non-zero returned prices will include currency codes.
Note that returned links must have the i-parcel address prefix, provided by i-parcel
IT, prepended to them.
Field Name
M/O/C
Format
Length
M
M
A/N
A/N
2
256
M
A/N
2
Remarks
<Array 0:N>
orderServiceID
orderService
orderSubtotal
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 18 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
orderShipping
orderDuty
orderTax
orderTotal
M
M
M
M
A/N
A/N
Boolean
A/N
3
3
orderID
orderTracking
rateFailed
M
M
M
A/N
A/N
A/N
2
3
3
256
</Array 0:N>
Sample:
[{"orderServiceID":"112","orderService":"i-Parcel
Immediate","orderSubtotal":"0","orderShipping":"0","orderDuty":"0","orderT
ax":"0","orderTotal":"0","orderID":"12358382","orderTracking":"","rateFail
ed":"We are sorry, but we cannot calculate shipping on the quantity and
type of item(s) currently in your
cart."},{"orderServiceID":"115","orderService":"i-Parcel
Preferred","orderSubtotal":"0","orderShipping":"0","orderDuty":"0","orderT
ax":"0","orderTotal":"0","orderID":"12358382","orderTracking":"","rateFail
ed":"We are sorry, but we cannot calculate shipping on the quantity and
type of item(s) currently in your cart."}]
(Order)
https://test.adyen.com/paymentlink
(Manual Order)
/files/12358390_635086369971991647.pdf
5.4.3 Function: Countries
5.4.3.1
Message Name: Countries
This API call returns a list of what countries are supported for a particular Merchant
by Sequence, and these countries’ associated currencies and ISO codes.
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 19 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.4.3.2
Message Name: CountriesResponse
The response can vary depending on the arguments supplied. Quotes return a
JSON list of rate responses ( If a quote fails, the rateFailed element will be nonblank), while manual orders return a link to the label. Orders return a link to the iparcel checkout. Note that non-zero returned prices will include currency codes.
Note that returned links must have the i-parcel address prefix, provided by i-parcel
IT, prepended to them.
Field Name
M/O/C
Format
Length
M
M
A/N
A/N
2
256
M
A/N
2
Remarks
<Array 0:N>
countryName
countryCode
currencyCode
</Array 0:N>
Sample:
[{"countryName":"United
States","countryCode":"US","currencyCode":"USD"},{"countryName":"Andorra",
"countryCode":"AD","currencyCode":"EUR"},{"countryName":"Anguilla","countr
yCode":"AI","currencyCode":"XCD"},{"countryName":"Antigua and
Barbuda","countryCode":"AG","currencyCode":"XCD"},{"countryName":"Australi
a","countryCode":"AU","currencyCode":"AUD"},{"countryName":"Austria","coun
tryCode":"AT","currencyCode":"EUR"},{"countryName":"Bahrain","countryCode"
:"BH","currencyCode":"BHD"},{"countryName":"Barbados","countryCode":"BB","
currencyCode":"BBD"},{"countryName":"Belize","countryCode":"BZ","currencyC
ode":"BZD"},{"countryName":"Bermuda","countryCode":"BM","currencyCode":"BM
D"},{"countryName":"Brazil","countryCode":"BR","currencyCode":"BRL"},{"cou
ntryName":"British Virgin
Islands","countryCode":"VG","currencyCode":"USD"},{"countryName":"Bulgaria
","countryCode":"BG","currencyCode":"BGN"},{"countryName":"Canada","countr
yCode":"CA","currencyCode":"CAD"},{"countryName":"China","countryCode":"CN
","currencyCode":"CNY"},{"countryName":"Colombia","countryCode":"CO","curr
encyCode":"COP"}]
5.4.4 Function: Currencies
5.4.4.1
Baselined
Message Name: Currencies
i-parcel Proprietary
Use pursuant to Company Instructions
Page 20 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
This API call returns a list of what currencies are supported for a particular Merchant
by Sequence.
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
5.4.4.2
Message Name: CurrenciesResponse
The response can vary depending on the arguments supplied. Quotes return a
JSON list of rate responses ( If a quote fails, the rateFailed element will be nonblank), while manual orders return a link to the label. Orders return a link to the iparcel checkout. Note that non-zero returned prices will include currency codes.
Note that returned links must have the i-parcel address prefix, provided by i-parcel
IT, prepended to them.
Field Name
M/O/C
Format
Length
A/N
A/N
2
256
Remarks
<Array 0:N>
currencyCode
currencyName
M
M
</Array 0:N>
Sample:
[{"currencyCode":"USD","currencyName":"US
Dollar"},{"currencyCode":"AUD","currencyName":"Australia
Dollars"},{"currencyCode":"BHD","currencyName":"Bahrain
Dinars"},{"currencyCode":"BRL","currencyName":"Brazil
Reais"},{"currencyCode":"BGN","currencyName":"Bulgaria
Leva"},{"currencyCode":"CAD","currencyName":"Canada
Dollars"},{"currencyCode":"CNY","currencyName":"China Yuan
Renminbi"},{"currencyCode":"COP","currencyName":"Colombia
Pesos"},{"currencyCode":"CZK","currencyName":"Czech Republic
Koruny"},{"currencyCode":"DKK","currencyName":"Denmark
Kroner"},{"currencyCode":"XCD","currencyName":"East Caribbean
Dollars"},{"currencyCode":"EUR","currencyName":"Euro"},{"currencyCode":"HK
D","currencyName":"Hong Kong
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 21 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Dollars"},{"currencyCode":"HUF","currencyName":"Hungary
Forint"},{"currencyCode":"INR","currencyName":"India
Rupees"},{"currencyCode":"IDR","currencyName":"Indonesia
Rupiahs"},{"currencyCode":"ILS","currencyName":"Israel New
Shekels"},{"currencyCode":"JPY","currencyName":"Japan
Yen"},{"currencyCode":"KWD","currencyName":"Kuwait
Dinars"},{"currencyCode":"LVL","currencyName":"Latvia
Lati"},{"currencyCode":"LTL","currencyName":"Lithuania
Litai"},{"currencyCode":"MYR","currencyName":"Malaysia
Ringgits"},{"currencyCode":"MXN","currencyName":"Mexico
Pesos"},{"currencyCode":"NZD","currencyName":"New Zealand
Dollars"},{"currencyCode":"NOK","currencyName":"Norway
Kroner"},{"currencyCode":"PEN","currencyName":"Peru Nuevos
Soles"},{"currencyCode":"PLN","currencyName":"Poland
Zlotych"},{"currencyCode":"QAR","currencyName":"Qatar
Riyals"},{"currencyCode":"RON","currencyName":"Romania New
Lei"},{"currencyCode":"RUB","currencyName":"Russia
Rubles"},{"currencyCode":"SAR","currencyName":"Saudi Arabia
Riyals"},{"currencyCode":"SGD","currencyName":"Singapore
Dollars"},{"currencyCode":"ZAR","currencyName":"South Africa
Rand"},{"currencyCode":"KRW","currencyName":"South Korea
Won"},{"currencyCode":"SEK","currencyName":"Sweden
Kronor"},{"currencyCode":"CHF","currencyName":"Switzerland
Francs"},{"currencyCode":"TWD","currencyName":"Taiwan New
Dollars"},{"currencyCode":"THB","currencyName":"Thailand
Baht"},{"currencyCode":"AED","currencyName":"United Arab Emirates
Dirhams"},{"currencyCode":"GBP","currencyName":"United Kingdom
Pounds"},{"currencyCode":"USD","currencyName":"United States Dollars"}]
5.4.5 Function: CurrencyInfo
5.4.5.1
Message Name: CurrencyInfo
This API call returns a list of what currencies are supported for a particular Merchant
by Sequence.
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
Country
M
A/N
2
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
The ISO two-digit code of the
country that the currency is to be
used in.
Currency
M
A/N
2
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
The ISO two-digit code of the
Page 22 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
currency to be used.
BaseCurrency
5.4.5.2
M
A/N
2
The ISO two-digit code of the
currency to be used as the base
currency for the exchange.
Typically USD, and if left blank,
will be passed as USD by
default.
Message Name: CurrencyInfoResponse
Field Name
M/O/C
Format
Length
currencyCode
currencyName
M
M
A/N
A/N
256
currencyLocalName
M
A/N
256
currencySymbol
M
A/N
256
exchangeRate
M
A/N
256
exchangeExpires
M
Date
256
Remarks
Sample:
{"currencyCode":"CAD","currencyName":"Canadian
Dollar","currencyLocalName":"Canadian
Dollar","currencySymbol":"CAD","exchangeRate":"0.925086203","exchangeExpir
es":"2013-07-06T00:00:00"}
5.4.6 Function: QueryQuote
QueryQuote is a Logistics-Only function that is used to get quote information for a
quote generated via Checkout.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 23 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.4.6.1
Message Name: QueryQuote
Field Name
M/O/C
Format
Length
Remarks
Sequence
M
A/N
2
CustomerID
M
N
2
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
– This integer is the i-parcel
Customer ID, provided by iparcel.
ServerPrefix
M
A/N
2
CParcelID
M
A/N
2
5.4.6.2
This is the ServerPrefix returned
as part of the original quote.
This is the CParcelID returned
as part of the original quote.
Message Name: QueryQuoteResponse
Field Name
M/O/C
Format
Length
orderServiceID
orderService
M
M
A/N
A/N
2
256
orderSubtotal
orderShipping
orderDuty
orderTax
orderTotal
M
M
M
M
M
A/N
A/N
A/N
Boolean
A/N
2
3
3
orderID
orderTracking
rateFailed
M
M
M
A/N
A/N
A/N
2
3
3
Remarks
<Array 0:N>
256
</Array 0:N>
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 24 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
5.4.7 Function: AcknowledgeQuote
QueryQuote is a Logistics-Only function that is used to get quote information for a
quote generated via Checkout.
5.4.7.1
Message Name: AcknowledgeQuote
Field Name
M/O/C
Format
Sequence
M
A/N
CustomerID
M
N
ServerPrefix
M
A/N
CParcelID
M
A/N
Address
M
A/N
CParcelID
M
A/N
5.4.7.2
Remarks
This string represents the
WebID of the Merchant. It is
provided by i-parcel and is used
for authentication purposes.
– This integer is the i-parcel
Customer ID, provided by iparcel.
This is the ServerPrefix returned
as part of the original quote.
This is the CParcelID returned
as part of the original quote.
Presented as a pipe-delimited
list of elements. For example:
Name|Line1|Line2|City|Region|
Misc.|Zip/Postal Code|Country
Code|Phone|Email
The country field must always
be the ISO two-digit country
code representation of the
shipping country.
This is the CParcelID returned
as part of the original quote.
Message Name: AcknowledgeQuoteResponse
Field Name
Baselined
Length
M/O/C
Format
Length
i-parcel Proprietary
Use pursuant to Company Instructions
Remarks
Page 25 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Result
M
A/N
2
Success or Failure
5.4.8 Function: DutyTaxRequest
This call feeds SKUs into the i-parcel system for international classification.
5.4.8.1
Message Name: DutyTaxRequest
Field Name
M/O/C
Format
Length
<Validation>
UserName
Password
M
M
A/N
N
2
M
A/N
2
1:N
M
M
M
M
M
M
M
O
O
M
A/N
A/N
A/N
A/N
A/N
A/N
A/N
A/N
A/N
A/N
2
CurrentPrice
WeightUnits
M
M
A/N
A/N
WeightLbs
ProductURL
M
M
N
A/N
BannedSKU
M
A/N
</ProductInfo>
1:N
</Validation>
Version
<Products>
<ProductInfo>
SKU
Attribute1
Attribute2
Attribute3
Attribute4
Attribute5
Attribute6
HSCodeUS
HSCodeCA
CountryofOrigin
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Remarks
Internal SKU or Products ID
ISO Countrycode of Origin
Country
Unit Price for the product
Weight unit of measure.
Allowed values: lbs
Location where the product can
be viewed online for personell
assigning HSCOde and
Duty/TaxIf Y, SKU will be ineligible for
international shipment
Page 26 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
</Products>
5.4.8.2
Message Name: iParcelDutyTaxResponse
Field Name
<Products>
SKU
RequestId
RequestDate
</Products>
M/O/C/Rel
1:N
M
M
M
Format
Length
A/N
A/N
A/N
Remarks
Success or Failure
Success or Failure
5.4.9 Function: reprintlabel
This call returns a label in various formats for a particular parcel.
Ultimately, the request is generated by means of the provided Parcel ID, and is
returned as a link, and as a base64 string in a number of formats, including EPL,
depending on configuration.
5.4.9.1
Message Name: iparcelPackageLabelReprint
Field Name
M/O/C
Format
<Validation>
UserName
Password
M
M
A/N
N
M
A/N
M
A/N
</Validation>
Version
<Package>
ParcelId
</Package>
Baselined
Length
i-parcel Proprietary
Use pursuant to Company Instructions
Remarks
Returned via
Page 27 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Sample Request:
<?xml version="1.0" encoding="UTF-8"?>
<iparcelPackageLabelReprint xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Validation>
<UserName>custtest</UserName>
<Password>custtest</Password>
</Validation>
<Package>
<ParcelId>211115894</ParcelId>
</Package>
</iparcelPackageLabelReprint>
5.4.9.2
Message Name: iParcelReprintResponse
Field Name
< PackageLabel >
ParcelID
ParcelLabelBase64
ParcelLabelLink
M/O/C/Rel
1:N
M
M
M
Format
Length
A/N
Base64
A/N
2
Remarks
2
</ PackageLabel >
Sample Response:
<?xml version="1.0" encoding="utf-8"?>
<iParcelReprintResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<PackageLabel>
<ParcelID>207928615</ParcelID>
<ParcelLabelBase64>JVBERi0xLjUgCiXi48/TIAoxIDAgb2JqIAo8PCAKL1R5cGUgL0NhdGFsb2cgCi9QYWdlcyA
yIDAgUiAKL1BhZ2VNb2RlIC9Vc2VOb25lIAovVmlld2VyUHJlZmVyZW5jZXMgPDwgCi9GaXRXaW5kb3cgdHJ1Z
SAKL1BhZ2VMYXlvdXQgL1NpbmdsZVBhZ2UgCi9Ob25GdWxsU2NyZWVuUGFnZU1vZGUgL1VzZU5vbmUgCj
4+IAo+PiAKZW5kb2JqIAo1IDAgb2JqIAo8PCAKL0xlbmd0aCAxMDIyIAovRmlsdGVyIFsgL0ZsYXRlRGVjb2RlIF0
gCj4+IApzdHJlYW0KeJxlVdty2zYQfedX7CM5U9EEeAGZN9dSUmcaa2IpTWeSPtAURKHlRQHJNPr77gIEpcZjS
8Oz992zSzGI8I/hJ4k5VK2BEejasw/P78wDz3NYkYWW3mev8zi896KQJegYxizB7yQTsHvwGPzrxWGcwoqLLIyh
9XiehtGCG4OTBRPKLcjSKxLkUnkzjrMizNPZl7CIQm6tKRLBDFwei6q5CovQMyyulvhZYphnGx/zEZqzNw7Zyoy<
/ParcelLabelBase64>
<ParcelLabelLink>http://www.i-parcel.com/files/2901082013957.pdf</ParcelLabelLink>
</PackageLabel>
</iParcelReprintResponse>
5.5 Function: Quote
5.5.1 Message Name: Quote
This call generates quote (cost) information for a given cart. It may be used as part
of a logistics only integration, or as part of a Global e-Commerce integration.
Optionally, a ParcelID may be provided, so that is the call is being made on a parcel
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 28 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
already quoted. The referenced parcel will be updated, and the new quote will be
added to that parcel’s quote history.
Field Name
< QuotePostRequest >
Key
ParcelID
<ItemList>
<Item>
SKU
Quantity
Weight
WeightUnits
Price
Currency
HTS
Override
M/O/C/Rel
M
M
O
Format
Object
A/N
A/N
Length
N
N
999
M
M
M
M
Object
1:N
A/N
N
N
N
100
3
O
O
O
O
O
O
N
A/N
N
A/N
A/N
Bool
M
M
M
M
M
M
M
M
Object
A
A
A/N
A/N
A/N
A/N
A/N
N
128
128
128
128
128
128
128
M
M
M
O
O
O
O
O
O
M
A
A
A
A/N
A/N
A/N
A/N
A/N
A
A/N
2
128
128
128
128
128
128
128
2
128
2
3
12
1
Remarks
Body of request
Authentication Key
Optional reference to existing
parcel.
Contains all items in request
For each item in request
SKU for the given item
Quantity of the items (1 for a
single item)
Weight of item
LB or KG
Value/Price of item
Currency code for price
HTS Code
Default: “false”
Set to “true” to ignore i-parcel
Catalog Weight, Price, HTS
(Warning, setting this value to
“true” may result in higher or
incorrect costs)
</Item>
</ ItemList >
<Address>
ShippingFirstName
ShippingLastName
ShippingStreet1
ShippingStreet2
ShippingCity
ShippingRegion
ShippingPostcode
ShippingCountry
BillingFirstName
BillingLastName
BillingStreet1
BillingStreet2
BillingCity
BillingRegion
BillingPostcode
BillingCountry
EmailAddress
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Address info for consignee
Consignee first name
Field must be passed, may be
blank if not Canadian address
ISO 2-digit Country Code
Consignee first name
ISO 2-digit Country Code
Customer Email Address
Page 29 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
ControlNumber
C
A/N
DDP
M
Boolean
ServiceLevelID
M
N
512
End-user control number for
particular countries that require
such information to be provided.
</Address>
999
Whether the shipment is to be
Delivered Duty Paid
112 for Immediate
115 for Preferred
119 for i-Parcel Saver
128 for i-Parcel Saver Deferred
</QuotePostRequest>
This call responds with the following:
5.5.2 MessageName: QuoteResponse
Field Name
M/O/C/R Format
el
< QuotePostResponse >
M
Object
ParcelID
M
A/N
<ServiceLevel>
Shipping
Duty
Tax
ItemSubtotal
CurrencyCode
Length
Remarks
N
N
Body of response
Parcel identifier for future
requests.
Contains object for each
service level the request. May
be blank or null if no valid rates
are returned.
Shipping cost
Duty cost
Tax cost
Cost of items summed
Currency of above numbers
M
1:N
N
M
M
M
M
M
N
N
N
N
N
999
999
999
999
3
</ServiceLevel>
</QuotePostResponse>
5.6 Function: SubmitParcel
5.6.1 MessageName: SubmitParcel
This call makes a parcel active in the system for shipping. It may be called with or
without an existing ParcelID reference. If a reference is provided, the referenced
ParcelID will be updated as indicated in the request, and considered a submitted
package/parcel. If a referenced ParcelID is not provided, a new one will be
generated. A history of all quotes associated with the parcel will be returned. This
call should only be made as part of Logistics Only integrations.
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 30 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Field Name
< SubmitPackagePostRequest >
Key
ParcelID
<ItemList>
<Item>
SKU
Quantity
Weight
WeightUnits
Price
Currency
HTS
Override
M/O Format
/C/R
el
M
Object
M
A/N
O
A/N
Length
Remarks
N
N
999
M
M
M
M
Object
1:N
A/N
N
N
N
100
3
O
O
O
O
O
O
N
A/N
N
A/N
A/N
Bool
3
12
1
Body of request
Authentication Key
Optional reference to existing
parcel.
Contains all items in request
For each item in request
SKU for the given item
Quantity of the items (1 for a
single item)
Weight of item
LB or KG
Value/Price of item
Currency code for price
HTS Code
Default: “false”
Set to “true” to ignore i-parcel
Catalog Weight, Price, HTS
(Warning, setting this value to
“true” may result in higher or
incorrect costs)
M
M
M
M
M
M
M
M
Object
A
A
A/N
A/N
A/N
A/N
A/N
N
128
128
128
128
128
128
128
M
M
M
O
O
O
O
O
O
M
O
A
A
A
A/N
A/N
A/N
A/N
A/N
A
A/N
A/N
2
128
128
128
128
128
128
128
2
128
512
</Item>
</ItemList>
<Address>
ShippingFirstName
ShippingLastName
ShippingStreet1
ShippingStreet2
ShippingCity
ShippingRegion
ShippingPostcode
ShippingCountry
BillingFirstName
BillingLastName
BillingStreet1
BillingStreet2
BillingCity
BillingRegion
BillingPostcode
BillingCountry
EmailAddress
ControlNumber
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Address info for consignee
Consignee first name
Field must be passed, may be
blank if not Canadian address
ISO 2-digit Country Code
Consignee first name
ISO 2-digit Country Code
Customer Email Address
End-user control number for
Page 31 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
particular countries that require
such information to be provided.
</Address>
DDP
M
Boolean
ServiceLevelID
M
N
999
Whether the shipment is to be
Delivered Duty Paid
112 for Immediate
115 for Preferred
119 for i-Parcel Saver
128 for i-Parcel Saver Deferred
</SubmitPackagePostRequest>
5.6.2 Message Name: SubmitParcel Response
This is the response from the package submission.
Field Name
ParcelID
M/O Format
/C/R
el
M
Object
M
A/N
<Quotes>
M
Object
<Quote>
M
1:N
QuoteID
M
A/N
999
M
1:N
N
M
M
M
M
M
M
N
N
N
N
N
N
999
999
999
999
3
999
< SubmitPackageResponse >
<ServiceLevel>
Shipping
Duty
Tax
ItemSubtotal
CurrencyCode
ServiceLevelID
Baselined
Length
Remarks
N
N
Body of response
Parcel identifier for future
requests.
At least one will be returned (for
the parcel created if no other
was referenced). Otherwise, the
every quote returned for the
referenced parcel will be on the
list.
The ID for the given quote.
These IDs will remain consistent
as new quotes are performed on
the parcel, if referenced.
Contains object for each service
level the request. May be blank
or null if no valid rates are
returned.
Shipping cost
Duty cost
Tax cost
Cost of items summed
Currency of above numbers
112 for Immediate
115 for Preferred
i-parcel Proprietary
Use pursuant to Company Instructions
Page 32 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
119 for i-Parcel Saver
128 for i-Parcel Saver Deferred
</ServiceLevel>
</Quote>
</Quotes>
</SubmitPackageResponse>
5.6.3 Message Name: Error Response
.
Field Name
< Exception >
Code
M/O/C/Rel
M
M
Format
Object
A/N
Length
N
N
Remarks
Body of response
See Exception Table for further
details
< / Exception >
M
Object
N
Body of response
5.7 Function: Checkout
5.7.1 Message Name: Checkout
This should be called only for Global e-Commerce integrations. It is used to
generate a payment link for the end-user to visit, in order to complete their shopping
experience. It is highly recommended that an existing quoted parcel is referenced.
Field Name
M/O/C/Rel Format
Length
Remarks
< Checkout >
M
Object
N
Body of request
Key
M
A/N
N
Authentication Key
ParcelID
O
A/N
999
Optional reference to existing
parcel.
< ItemList >
M
Object
N
Contains all items in request
<ItemDetails>
M
1:N
N
For each item in request
SKU
M
A/N
100
SKU for the given item
Quantity
M
N
3
Quantity of the items (1 for a
single item)
Weight
O
N
Weight of item
WeightUnits
O
A/N
LB or KG
Price
O
N
Value/Price of item
Currency
O
A/N
3
Currency code for price
HTS
O
A/N
12
HTS Code
Override
O
Bool
1
Default: “false”
Set to “true” to ignore i-parcel
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 33 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
Catalog Weight, Price, HTS,
Banning (Warning, setting this
value to “true” may result in
higher or incorrect costs)
</ItemDetails>
</ ItemList>
<Address>
M
M
M
M
M
M
M
M
Object
A
A
A/N
A/N
A/N
A/N
A/N
N
128
128
128
128
128
128
128
M
M
M
O
O
O
O
O
O
M
O
A
A
A
A/N
A/N
A/N
A/N
A/N
A
A/N
A/N
2
128
128
128
128
128
128
128
2
128
512
DDP
M
Boolean
ServiceLevelID
M
N
ShippingFirstName
ShippingLastName
ShippingStreet1
ShippingStreet2
ShippingCity
ShippingRegion
ShippingPostcode
ShippingCountry
BillingFirstName
BillingLastName
BillingStreet1
BillingStreet2
BillingCity
BillingRegion
BillingPostcode
BillingCountry
EmailAddress
ControlNumber
Address info for consignee
Consignee first name
Field must be passed, may be
blank if not Canadian address
ISO 2-digit Country Code
Consignee first name
ISO 2-digit Country Code
Customer Email Address
End-user control number for
particular countries that require
such information to be provided.
</Address>
999
Whether the shipment is to be
Delivered Duty Paid
112 for Immediate
115 for Preferred
119 for i-Parcel Saver
128 for i-Parcel Saver Deferred
</Checkout>
5.7.2 Message Name: CheckoutResponse
Field Name
M/O/C/ Format
Rel
< CheckoutResponse >
M
Object
PaymentLink
M
A/N (URL)
Length
Remarks
N
999
Body of response
Link for end-user to checkout.
</CheckoutResponse>
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 34 of 35
Application Programming Interface Document
Last Updated: 10/23/2013
Version: 2.0
6. Message Name: Error Response
.
Code
001
Remarks
Invalid Address
002
Invalid Item
003
Invalid Field
004
Services Temporarily Unavailable
005
Banned or Unknown SKU
Baselined
i-parcel Proprietary
Use pursuant to Company Instructions
Page 35 of 35