Endpoints
Request shipping quotes
POST | https://api.iglobalstores.com/2.0/shipping-quotes - Create a new request for shipping quotes on items in the shopping cart that includes import duties and taxes plus item restrictions screening information.
HTTPS request
| Field | Notes |
|---|---|
| HTTP method | POST |
| Endpoint URL | https://api.iglobalstores.com/2.0/shipping-quotes |
| Protocol | HTTPS |
| Message format | JSON |
| Accept HTTP header | Accept: application/json |
| Security Token HTTP Header | serviceToken: your-test-token-valueAdd a header to your HTTPS request named serviceToken with a value of your Test Security API Token. (Contact your Account Manager for this token) |
| Content-Type HTTP Header | Content-Type: application/jsonBecause you will be posting JSON data to the service, add a header to your HTTPS request named Content-Type with a value of application/json |
JSON KEY/VALUE PAIRS in the request body
Message Format: JSON
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"boxCount": null,
"items": [
{
"cartItemId": 1,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675234",
"sku": "oakley-123",
"unitPrice": 199.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
},
{
"cartItemId": 2,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675235",
"sku": "oakley-125",
"unitPrice": 179.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
}
],
"shippingAmountOverride": null,
"shipFromAddress": null,
"shipToAddress": {
"name": "John Doe",
"address1": "123 S West Elm St",
"address2": null,
"address3": null,
"city": "Calgary",
"state": "Alberta",
"stateCode": "AB",
"postalCode": "T2P 5G8",
"countryCode": "CA"
}
}
Request JSON definitions
| Field | Notes |
|---|---|
boxCount | This field describes the boxes that will be used to ship the order. It is not expected that a merchant knows this at the time of the order; however, if it is known, it may be passed in the following specific format.Example value: 22x15x15(1),8x8x4(2),32x22x14(1)Format: Comma-separated list of box dimensions and count. In the example above, there are a total of 4 boxes. The first box in the list will be 22 inches long, by 15 inches wide, by 15 inches high. There will only be one box used for that size. There will be two boxes of size 8x8x4 inches. It is acceptable to pass the same box dimension multiple times if that is easy for you, like this: “22x15x15(1),22x15x15(1)”, which means 2 boxes of size 22x15x15 inches. |
items REQUIRED | A list of item maps |
items[index].brandName | The brand name of the specific item will help our rules engine best determine if a restriction applies to the item for the destination country.Even if an item’s brand name does or does not textually match a specific restriction, our rules engine will use the item’s SKU and or productId to better decide if the item is in fact restricted into the destination country. Please send the brand name if available.Example values: “Oakley” or “Nike” or null |
items[index].cartItemId REQUIRED | This field is required to identify the item, specifically within the list of items. It may be as simple as an index value. We will use this cartItemId to identify an item if it is restricted in the JSON response. So make sure that you are able to identify the same item in your cart by this cartItemId you are passing to us.Example values: 1 or 2 or 3 |
items[index].category | The product categories - the specific product it is a part of. The category will help our rules engine best determine if a restriction applies to the item for the destination country.Even if an item’s category does or does not textually match a specific restriction, our rules engine will use the item’s SKU and/or productId to better decide if the item is in fact restricted into the destination country.Format: A pipe-separated list of category names. Each category name may be one or more words. If an item exists in more than one category, please list them both separated by a pipe “” character.Example: values “Sunglasses” or “Evening AccessoriesHandbags” |
items[index].countryOfOrigin | The country of origin is the country the item was made in or originally came from. The country of origin will help our rules engine best determine if a restriction applies to the item for the destination country. Some countries do not allow specific kinds of goods from other specific countries.Example values: “CN” for China or “US” for United States or null |
items[index].detailedDescription REQUIRED | This field is simply text, but should include as much information as possible about the item being purchased. For example, the full name and item code if applicable, the color or other options selected, material content, and any description text you have for the item.There are many different types of import restrictions into foreign countries, such as leather shoes into Italy. Sometimes, the only way to catch these restricted items is through the detailedDescription.Note: Even if an item’s detailedDescription does or does not textually match a specific restriction, our rules engine will use the item’s SKU and/or productId to better decide if the item is in fact restricted into the destination country. For best results, please send as much information as possible in the detailedDescription field.Example value: “Tory Burch, Robinson – Double Zip’ Tote, color: New Carnival, material content: leather, Color-rich leather lends eye-catching appeal a neatly structured tote, tipped with logo hardware and rolled handles for a completely sophisticated look. Magnetic-snap closure with dual zippered compartments. Interior zip, wall and cell-phone pockets. Protective metal feet. Leather. By Tory Burch; imported.” |
items[index].height | This is your item’s height. There is another field named dimensionalUnits, which is where you specify inches or centimeters for this measurement. Please provide without commas and with no more than two decimal places.Example value: 25.5Your shipping rates will be the most accurate if you do pass this field. |
items[index].hsCode | This is the HS Code that identifies the item to foreign countries. Passing the hsCode will help in properly identifying the right import duty rate for the specific item. Not required if unavailable – we will take care of it if you don’t have it.Format: Either a 10-digit or 6-digit code; may include the separating “.” characters or not.Example values: “20.4560.0000” or “20.4560” or “204560” (either 10 or 6 digit codes are acceptable) |
items[index].length | This is your item’s length. There is another field named dimensionalUnits, which is where you specific inches or centimeters for this measurement. Please provide without commas and with no more than two decimal places.Example value: 25.5Your shipping rates will be the most accurate if you do pass this field. |
items[index].productId | This is your product id for the specific item. Our rules engine will use this value as an ID to tie learned item information to your item.Example value: “17898-675235”Please pass at the least the productID or the SKU. Passing both is preferred. |
items[index].quantity REQUIRED | This is the quantity being purchased on the specific item. Please provide as a positive integer, without commas and no decimal places.Example values: 1 or 9999 (we prefer you sell more items than less!) |
items[index].sku | This is your SKU for the specific item. Our rules engine will use this value as an ID to tie learned item information to your item.Example value: “oakley-125”Please pass at least the productId or the SKU. Passing both is preferred. |
items[index].unitPrice REQUIRED | This is your item’s unit price in USD (US dollars). Please provide without commas, without a dollar sign “$”, and with two decimal places.Example value: 2102.99 |
items[index].weight | This is your item’s weight. There is another field named weightUnits, which is where you specify pounds, ounces, grams, or kilograms for this measurement. Please provide without commas and with no more than two decimal places.Example value: 4.2Your shipping rates will be the most accurate if you do pass this field. |
items[index].weightUnits | Defaults to “LB” for poundsThe unit of measure for the weight value. If set to null, “LB” (pounds), will be assumed.Example values: “LB” for pounds or “OZ” for ounces or “G” for grams or “KG” for kilograms or null |
items[index].width | This is your item’s width. There is another field named dimensionalUnits, which is where you specify inches or centimeters for this measurement. Please provide without commas and with no more than two decimal places.Example value: 25.5Your shipping rates will be the most accurate if you do pass this field. |
shipFromAddress | If passed as null, we will use a default shipFromAddress associated with your merchant account. This is the address the order will be shipped from, i.e. your warehouse.This is a map containing the following address fields: address1, address2, address3, city, state, stateCode, postalCode, countryCode. These contained fields are required or not required, based on the country. The localization endpoint returns which specific address fields are required for not for each country.Note: stateCode is always not required and not declared in the localization endpoint. You may pass stateCode, if available. |
shippingAmountOverride | This is only used if you know the shipping cost before calling the API. It is in USD (US dollars).Please provide without commas, without a dollar sign “$”, and with two decimal places. This feature will not work without setting it up with a Zonos representative. Example value: 212.99 |
shipToAddress REQUIRED | This is the address the order will be shipped to. This is a map containing the following address fields: name, address1, address2, address3, city, state, stateCode, postalCode, countryCode. These contained fields are required or not based on the country. The localization endpoint returns which specific address fields are required for each country.Note: name and stateCode are always not required and not declared in the localization endpoint. You may pass name and/or stateCode, if available. |
HTTPS response
Message format: JSON
Example response for only Canada & Australia
Note: Actual responses will contain all supported countries.
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
"shippingQuotes": [
{
"id": "bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a",
"carrier": "UPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Express Air 2-4 Day Delivery",
"duty": 10.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 29.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 23.62,
"taxOrVat": 9.18
},
{
"id": "80c57724-ab4e-4997-8477-08b668fef103",
"carrier": "USPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Post 5-10 Day Delivery",
"duty": 9.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 27.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 13.62,
"taxOrVat": 8.18
}
]
}
Response JSON definitions
| Field | Notes |
|---|---|
shippingQuotes | This is a list of shipping quote maps. |
shippingQuotes[index].carrier | The carrier that the shipping quote is specific to. Only ever set to null if the merchant has asked to have generic shipping profiles setup, not specific to a carrier. Shipping quotes do not need to be specific to a carrier; but may be. Contact your Account Manager for help setting up your shipping profiles.Example values: UPS or FEDEX or DHL or USPS or CAPOST or null |
shippingQuotes[index].displayName | Display name for the shipping option, suitable to be displayed to the shopper. These values are customizable for the merchant. Contact your Account Manager to do so.Example value: “Express Air 2-4 Day Delivery” |
shippingQuotes[index].duty | The import duty amount included in the dutyTaxTotal. This amount is in USD, will not contain commas, and will contain two decimal places.Example value: 8.29 |
shippingQuotes[index] .dutyTaxBrokerageFee | This is what the foreign importing broker will charge you to process your import duties and taxes. This amount is included in the dutyTaxTotal. The amount is in USD, will not contain commas, and will contain two decimal places.Example value: 5.00 |
shippingQuotes[index] .duyTaxCarrierPrepaymentFee | This is what the carrier will charge you to prepay the duties and taxes to the importing country. This amount is included in the dutyTaxTotal. This amount is in USD, will not contain commas, and will contain two decimal places.Example value: 5.00 |
shippingQuotes[index] .duyTaxEnabled | Whether this shipping quote enables the shopper to prepay their import duties and taxes.If set to false, the dutyTaxTotal should be ignored.Example values: true or false |
shippingQuotes[index] .duyTaxForced | Whether this shipping quote forces the shopper to prepay their import duties and taxes.If set to true, you should include the dutyTaxTotal in the order, explaining to the shopper that it’s required with this specific shipping option.If set to false, you may allow the shopper to choose if they want to prepay their import duties and taxes.Example values: true or false |
shippingQuotes[index].dutyTaxTotal | The total cost of duty and tax for the given shipping quote. Duty and tax may be optional, not available, or forced for the given shipping quote. This amount is not included in the shippingTotal. This amount is in USD, will not contain commas, and will contain two decimal places.Example value: 19.55 |
shippingQuotes[index] .dutyTaxUnderDeMinimis | Whether the order’s total, using this specific shipping option, is under both the tax/VAT de minimis amount and the duty de minimis amount.If set to true, the dutyTaxTotal will be set to 0.00, and you should message the customer that there will be no import duties or taxes due on their order. Additionally, force prepayment of duties and taxes, because the cost is 0.00. |
shippingQuotes[index].id | An identifier for the specific shipping quote; a 36-character UUIDExample value: bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a |
shippingQuotes[index].restrictedItems | This is a list of maps, containing details about any items in the cart that are restricted using this specific shipping quote.Each restricted item has a reasonCode. The reason may or may not be specific to the shipping option. Some reasons for item restrictions are due to country import laws, brand restrictions, or even merchant-created rules.Each time a shipping option is chosen by the shopper, the cart items should be cross-referenced against the shipping quote’s restrictedItems list. If any of the cart items are restricted, a message should be displayed to the shopper, and the restricted item(s) should be removed from the order’s total, etc. |
shippingQuotes[index] .restrictedItems[index].cartItemId | This is the cartItemId from the request JSON of a restricted cart item. You should be able to tie this cartItemId back to a specific item in your shopper’s cart.Example values: 1 or 2 or 3 |
shippingQuotes[index] .restrictedItems[index].message | This is a message that may be displayed to the shopper about why the item is restricted. These messages are customizable by the merchant. Please contact your Zonos rep for details.Example value: “We are unable to sell Oakely products to your country.” |
shippingQuotes[index] .restrictedItems[index].reasonCode | This is the reason code for the item being restricted. Restrictions are always country-specific and our reason codes make that obvious.Example values: BRAND_COUNTRY or IMPORT_COUNTRY or EXPORT_COUNTRY or CARRIER_COUNTRY or MERCHANT_COUNTRY``BRAND_COUNTRY means you have specified that you cannot sell a brand to a specific set of countries.IMPORT_COUNTRY means the importing country will not permit the item to be imported.EXPORT_COUNTRY means the exporting country (usually United States) will not permit the item to be exported.CARRIER_COUNTRY means the specific carrier will not carry the item.MERCHANT_COUNTRY means you have set up a custom restriction rule that the item has triggered. |
shippingQuotes[index] .shippingTotal | The total cost of shipping for the given shipping quote. Shipping quotes also may have a dutyTaxTotal amount, which is not included in this shippingTotal. This amount is in USD, will not contain commas, and will contain two decimal places.Example value: 25.82 |
shippingQuotes[index].taxOrVat | The tax or VAT amount included in the dutyTaxTotal. For some countries, this is a tax; for others, it is a VAT. This amount is in UST, will not contain commas, and will contain two decimal places.Example value: 4.35 |
Landed Cost API Legacy
Learn how the Legacy Landed Cost API works.The information below is for our legacy Landed Cost API. See our Landed Cost API for the latest version.
The shipping-quotes endpoint accepts details about your shopper’s cart, returns shipping quotes complete with import duties and taxes quotes, and screens the items for restrictions. These returned shipping quotes are based on shipping profiles that are set up prior to the use of this API endpoint.
We have default shipping profiles for testing purposes, but you will need to work with your Account Manager to set up the actual shipping profiles and settings your company wants to use.