Landed Cost API

The shipping-quotes end point accepts details about your shopper’s cart, and returns shipping quotes complete with import duties and taxes quotes, as well as screening the items for restrictions. These returned shipping quotes are based on shipping profiles that are setup prior to the use of this API end point.

We have default shipping profiles for testing purposes. Though you will need to work with your Account Manager to setup the actual shipping profiles and settings your company wants to use.

Service End Point – shipping-quotes

HTTPS Request

HTTP Method POST
End Point 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-value
  Add 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/json
  Because 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

Request Parameters

Message Format JSON

Example request

{
    "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"
    },
    "boxCount": null,
    "shippingAmountOverride": null,
    "items": [
        {
            "cartItemId": 1,
            "detailedDescription": "description including options, material content, etc",
            "category": "sunglasses",
            "productId": "17898-675234",
            "sku": "oakley-123",
            "unitPrice": 199.00,
            "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.00,
            "quantity": 1,
            "length": 2.5,
            "width": 6.5,
            "height": 2.5,
            "dimensionalUnits": null,
            "weight": 4,
            "weightUnits": "OZ",
            "hsCode": null,
            "brandName": "Oakley",
            "countryOfOrigin": "CN"
        }
    ]
}

Request JSON Definitions

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, based on the country. The localization end point returns which specific address fields are required, or not, for each country. Note: stateCode is always not required, and not declared in the localization end point. You may pass stateCode if available.

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 end point returns which specific address fields are required, or not, for each country. Note: name and stateCode are always not required, and not declared in the localization end point. You may pass name and/or stateCode if available.

boxCount

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 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.

This field describes the boxes that will be used to ship the order. It is not expected that a merchant knows this at time of order. However if it is known, it may be passed in the following specific format.

shippingAmountOverride

Example value 212.99

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 an account representative.

items

Required

A list of item maps.

items[index].cartItemId

Required

Example values 1 or 2 or 3

This field is required to identify the item, specifically within the list of items. It may be as simple 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.

items[index].detailedDescription

Required

Example value “Torey 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.”

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.

items[index].category

Example values “Sunglasses” or “Evening Accessories Handbags”
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.

The product categories the specific product in 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.

items[index].productId

(Please pass at least the productId or the sku. Passing both is preferred.)

Example value “17898-675235”

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.

items[index].sku

(Please pass at least the productId or the sku. Passing both is preferred.)

Example value “oakley-125”

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.

items[index].unitPrice

Required

Example value 2102.99

This is your item’s unit price in USD (US Dollars). Please provide without commas, without a dollar sign “$”, and with two decimal places.

items[index].quantity

Required

Example values 1 or 9999 (we prefer you sell more items than less!)

This is the quantity being purchased on the specific item. Please provide as a positive integer, without commas, and no decimal places.

items[index].length

(Your shipping rates will be the most accurate if you do pass this field)

Example value 25.5

This is your item’s length. 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.

items[index].width

(Your shipping rates will be the most accurate if you do pass this field)

Example value 25.5

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.

items[index].height

(Your shipping rates will be the most accurate if you do pass this field)

Example value 25.5

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.

items[index].dimensionalUnits

(Defaults to “IN” for inches)

Example values “IN” for inches or “CM” for centimeters or null

The unit of measure for the length, width, and height values. If set to null, “IN”, inches, will be assumed.

items[index].weight

(Your shipping rates will be the most accurate if you do pass this field)

Example value 4.2

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.

items[index].weightUnits

(Defaults to “LB” for pounds)

Example values “LB” for pounds or “OZ” for ounces or “G” for grams or “KG” for kilograms or null

The unit of measure for the weight value. If set to null, “LB”, pounds, will be assumed.

items[index].hsCode

Example values “20.4560.0000” or “20.4560” or “204560” (either 10 or 6 digit codes are acceptable)

Format Either a 10 digit or 6 digit code. May include the separating “.” characters or not.

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.

items[index].brandName

Example values “Oakley” or “Nike” or null

The brand name of the specific item. The brand name 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.

items[index].countryOfOrigin

Example values “CN” for China or “US” for United States or null

The country of origin is the country the item was made in, 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.

HTTPS Response

Message Format JSON

Example response for only Canada & Australia; actual responses will contain all supported countries.

    {
        "shippingQuotes": [
            {
                "id": "bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a",
                "displayName": "Express Air 2-4 Day Delivery",
                "carrier": "UPS",
                "shippingTotal": 23.62,
                "dutyTaxTotal": 29.38,
                "taxOrVat": 9.18,
                "duty": 10.20,
                "dutyTaxCarrierPrepaymentFee": 5.00,
                "dutyTaxBrokerageFee": 5.00,
                "dutyTaxEnabled": true,
                "dutyTaxForced": false,
                "dutyTaxUnderDeminimus": false,
                "conversionRate": 1.32,
                "currencyCode": "CAD",
                "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"
                    }
                ]
            },
            {
                "id": "80c57724-ab4e-4997-8477-08b668fef103",
                "displayName": "Post 5-10 Day Delivery",
                "carrier": "USPS",
                "shippingTotal": 13.62,
                "dutyTaxTotal": 27.38,
                "taxOrVat": 8.18,
                "duty": 9.20,
                "dutyTaxCarrierPrepaymentFee": 5.00,
                "dutyTaxBrokerageFee": 5.00,
                "dutyTaxEnabled": true,
                "dutyTaxForced": false,
                "dutyTaxUnderDeminimus": false,
                "conversionRate": 1.32,
                "currencyCode": "CAD",
                "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"
                    }
                ]
            }
        ]
    }

Response JSON Definitions

shippingQuotes

This is a list of shipping quote maps.

shippingQuotes[index].id

Example value: ‘bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a’

An identifier for the specific shipping quote. A 36 character UUID.

shippingQuotes[index].displayName

Example value: ‘Express Air 2-4 Day Delivery’

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.

shippingQuotes[index].carrier

Example values: UPS or FEDEX or DHL or USPS or CAPOST or null

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.

shippingQuotes[index].shippingTotal

Example value: 25.82

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.

shippingQuotes[index].dutyTaxTotal

Example value: 19.55

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.

shippingQuotes[index].taxOrVat

Example value: 4.35

The tax or vat amount included in the dutyTaxTotal. For some countries this is a tax, and for some it is a vat. This amount is in USD, will not contain commas, and will contain two decimal places.

shippingQuotes[index].duty

Example value: 8.29

The import duty amount included in the dutyTaxTotal. This amount is in USD, will not contain commas, and will contain two decimal places.

shippingQuotes[index].dutyTaxCarrierPrepaymentFee

Example value: 5.00

This is what the carrier will charge you to prepay the duties and taxes for you 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.

shippingQuotes[index].dutyTaxBrokerageFee

Example value: 5.00

This is what the foreign importing broker will charge you to process your import and duties and taxes. This amount is included in the dutyTaxTotal. This amount is in USD, will not contain commas, and will contain two decimal places.

shippingQuotes[index].dutyTaxEnabled

Example values: true or false

Whether this shipping quote enables the shopper to prepay their import duties and taxes.

How to use If set to false, the dutyTaxTotal should be ignored.

shippingQuotes[index].dutyTaxForced

Example values: true or false

Whether this shipping quote forces the shopper to prepay their import duties and taxes.

How to use If set to true, you should include the dutyTaxTotal in the order, explaining to the shopper that it is a 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.

shippingQuotes[index].dutyTaxUnderDeminimus

Example values: true or false

Whether the order’s total, using this specific shipping option, is under both the tax/vat deminimus amount and the duty deminimus amount.

How to use 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].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 because of country import laws, brand restrictions, or even merchant created rules.

How to use 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

Example values: 1 or 2 or 3

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.

shippingQuotes[index].restrictedItems[index].message

Example value: “We are unable to sell Oakley products to your country.”

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 Account Manager for details.

shippingQuotes[index].restrictedItems[index].reasonCode

Example values: BRAND_COUNTRY or IMPORT_COUNTRY or EXPORT_COUNTRY or CARRIER_COUNTRY or MERCHANT_COUNTRY

This is the reason code for the item being restricted. Restrictions are always country specific, and our reason codes make that obvious.

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 setup a custom restriction rule that the item has triggered.