LandedCost.io Landed Cost API Documentation

The Landed Cost API calculates international duties, brokerage fees and taxes based on the online retailer's shopping cart details.

Landed Cost API Endpoint URL

https://api.landedcost.io/calculator

Landed Cost API Request Method

POST

Landed Cost API Request Definitions

Name Description Required Type Max Allowed Length
securityKey The seller's API security key Yes String 1 1...100
carrier Shipping carrier to deliver the merchandise. Options: ANY, UPS, FEDEX, DHL Yes String 1 1…5
shippingMethod Shipping method to deliver the merchandise. Options: ANY, AIR, GROUND, 2DAY Yes String 1 1…5
languageCode The landed cost quote's target ISO language code. The default is 'en-us' (English/United States) Yes String 1 1…5
shippingCostTotal The total shipping costs for the order Yes String 1 1…20
sourceCurrencyCode The source currency code, normally the currency code of the seller's country. ISO currency codes supported. Yes String 1 3
targetCurrencyCode The target currency code, normally the currency code of the customer's country. ISO currency codes supported. Yes String 1 3
discountTotal The discount that should be applied to the landed cost calculation. Only positive amounts are accepted. For example, 10.00 would represent a 10 USD Dollar discount. Yes String 1 1…20
transactionId The seller may provide a transaction ID to lookup landed cost details by the seller's transaction ID (order number) No String 1 1…100
additionalInsuranceTotal The insurance value that should be applied to the landed cost calculation Yes String 1 1…20
addresses The collection of addresses. Two addresses are required: seller and Customer. The first address in the collection should contain the seller's address. The second address in the collection should contain the customer's address Yes Container 2 N/A
--- firstName The seller's or customer's first name Yes String 1 1…255
--- lastName The seller's or customer's last name Yes String 1 1…255
--- company The seller's or customer's company's name No String 1 1…100
--- address1 The seller's or customer's address1 line Yes String 1 1…255
--- address2 The seller's or customer's address2 line Yes String 1 1…255
--- city The seller's or customer's city Yes String 1 1…255
--- regionCode The seller's or customer's state/province/region Yes String 1 1…255
--- countryCode The seller's or customer's country code. Full list available here: https://www.landedcost.io/documentation/country-codes Yes String 1 1…255
--- postalCode The seller's or customer's zip code/postal code No String 1 1…20
--- emailAddress The seller's or customer's email address Yes String 1 1…100
--- nationalIdentificationNumber The seller's national identification number No String 1 1…100
--- addressType The seller's addressType must contain "ShipFrom" (without the quotes). The customer's addressType must contain "ShipTo" (without the quotes). Yes String 1 1…100
items The collection of products/items included in the transaction Yes Container Unbounded N/A
--- sku The product's SKU number. Yes String 1 1…255
--- name The product's name Yes String 1 1…255
--- description The product's full description Yes String 1 1…4000
--- price The product's price Yes String 1 1…25
--- quantity The product's quantity ordered by the customer Yes Integer 1 1…4
--- category The product's category name. This will contain the Web category for online sellers. No String 1 1…100
--- attributes The product's special attributes No String 1 Unbounded
--- weight The product's weight. A numeric value is required. Yes String 1 1…15
--- uom The product's Unit of Measure. Acceptable options: lbs, ea , kg No String 1 2
--- countryOfOrigin The product's country of origin Yes String 1 2
--- hsCode The item's HTS or HS Classification Code, supports both HTS (10-digits) and HS Codes (6-digits) Yes String 1 1…15
--- autoClassify Informs the Landed Cost API to auto select the appropriate HS Code based on the product description, category and attributes. To enable auto-classification, set this attribute to: auto-classify (all lower case). Otherwise, set this attribute to: false No String 1 1...15
--- freeCirculation For UK-based sellers Informs the Landed Cost API whether the product is considered free circulation. If set to false, the product will be considered GSP Eligible. If set to true, the product will be non-GSP Eligible. Default value is set to: false if not provided in the API No String 1 1...15
--- isFTAEligible If the seller has been able to certify that a specific product originates/qualifies for the ship to (destination) country's free trade agreement, the seller can set this element to true to recieve the free trade agreement benefit for a specific sku. Only set the value to true, if you have received a Free Trade Agreement Certification or Declaration from the ship to country's issuing authority. Default value is set to false if not provided in the API No String 1 1...15

Landed Cost API Response Definitions

Name Description Required Type Max Allowed Length Validation Rules
id Unique identifier generated by each Landed Cost API call. This id can be used for reference during reconciliation or integration. Yes String 1 13
transactionId The transaction ID provided by the seller to lookup landed cost response details by the seller's transaction ID No String 1 1…100
code The API response code Yes String 1 1…10
message The API response message Yes String 1 1…100
securityKey The seller's API security key Yes String 1 1…100
dutiesTotal The calculated duties total Yes String 1 1…20
taxesTotal The calculated taxes total Yes String 1 1…20
feesTotal The calculated fees total Yes String 1 1…20
subTotal The calculated sub-total (merchandise total) Yes String 1 1…20
grandTotal The calculated grand total Yes String 1 1…20
landedCostTotal The calculated "landed cost" total Yes String 1 1…20
carrier Shipping carrier to deliver the merchandise. Options: UPS, FEDEX, DHL Yes String 1 1…5
shippingMethod Shipping method to deliver the merchandise. Options: ANY, AIR, GROUND, 2DAY Yes String 1 1…5
languageCode The landed cost quote's target ISO language code. The default is 'en-us' (English/United States) Yes String 1 1…5
shippingCostTotal The total shipping costs for the order No String 1 1…20
sourceCurrencyCode The source currency code, normally the currency code of the seller's country. ISO currency codes supported. Yes String 1 3
targetCurrencyCode The target currency code, normally the currency code of the customer's country. ISO currency codes supported. Yes String 1 3
discountTotal The discount applied to the landed cost calculation Yes String 1 1…20
additionalInsuranceTotal The insurance value applied to the landed cost calculation Yes 1
utcDateTimeStamp The transaction date/timeStamp in Coordinated Universal Time (UTC) Yes String 1 1…100
timeStamp The transaction UNIX timeStamp Yes String 1 1…12
fees The collection of fees applied in the calculation Yes Container Unbounded N/A
--- name The fee applied in the calculation Yes String 1 1…25
--- amount The fee amount applied in the calculation Yes String 1 1…25
taxes The collection of taxes applied in the calculation Yes Container Unbounded N/A
--- name The tax applied in the calculation Yes String 1 1…25
--- localName The tax's local name applied in the calculation Yes String 1 1…25
--- amount The tax amount applied in the calculation Yes String 1 1…25
addresses The collection of addresses. Two addresses are required: seller and Customer. The first address in the collection should contain the seller's address. The second address in the collection should contain the customer's address Yes Container 2 N/A
--- firstName The seller's or customer's first name Yes String 1 1…255
--- lastName The seller's or customer's last name Yes String 1 1…255
--- company The seller's or customer's company's name No String 1 1…100
--- address1 The seller's or customer's address1 line Yes String 1 1…255
--- address2 The seller's or customer's address2 line Yes String 1 1…255
--- city The seller's or customer's city Yes String 1 1…255
--- regionCode The seller's or customer's state/province/region Yes String 1 1…255
--- countryCode The seller's or customer's country code. Full list available here: https://www.landedcost.io/documentation/country-codes Yes String 1 1…255
--- postalCode The seller's or customer's zip code/postal code No String 1 1…20
--- emailAddress The seller's or customer's email address Yes String 1 1…100
--- nationalIdentificationNumber The seller's national identification number No String 1 1…100
--- addressType The seller's addressType must contain "ShipFrom" (without the quotes). The customer's addressType must contain "ShipTo" (without the quotes). Yes String 1 1…100
items The collection of shopping cart items. Yes Container Unbounded N/A
--- sku The product's SKU number. Yes String 1 1…255
--- name The product's name Yes String 1 1…255
--- description The product's full description Yes String 1 1…4000
--- price The product's price Yes String 1 1…25
--- quantity The product's quantity ordered by the customer Yes Integer 1 1…4
--- category The product's category name. This will contain the Web category for online sellers. Yes String 1 1…100
--- attributes The product's special attributes No String 1 Unbounded
--- weight The product's weight. A value of numeric value is required. Yes String 1 1…15
--- uom The product's Unit of Measure. Acceptable options: lbs, ea , kg No String 1 2
--- countryOfOrigin The product's country of origin Yes String 1 2
--- hsCode The product's HTS or HTS Classification Code. No String 1 1…15
--- dutiesAmount The product's calculated duties amount Yes String 1 1...15
--- taxesAmount The product's calculated taxes amount Yes String 1 1...15
--- hsCodeAccuracy The accuracy of HS Code lookup on a scale from 0 to 100 (100 signifies the HTS Code was found. 80 signifies the HS Code was found. 0 signifies neither the HTS Code or HS Code were found in the system.) Yes String 1 1…3
--- restricted Indicates whether the product may or may not be shipped to the destination country. Possible return values: true , false Yes String 1 1…10
--- autoClassify Indicates whether the product used the auto-select feature to identify the appropriate HS Code based on the product description, category and attributes No String 1 1...15

Sample Landed Cost JSON Request Using Valid HS Code

 

{
    "carrier": "DHL",
    "shippingMethod": "ANY",
    "securityKey": "{Your Security Key Goes Here}",
    "shippingCostTotal": "00.00",
    "sourceCurrencyCode": "USD",
    "targetCurrencyCode": "USD",
    "discountTotal": "0.00",
    "additionalInsuranceTotal": "0.00",
    "languageCode": "en-us",
    "addresses": [{
        "firstName": "John",
        "lastName": "Shipper",
        "address1": "123 Vine Street",
        "address2": "",
        "city": "Lemoore",
        "regionCode": "CA",
        "countryCode": "US",
        "postalCode": "93245",
        "emailAddress": "john_shipper@email.com",
        "nationalIdentificationNumber": "",
        "addressType": "shipFrom"
    },
    {
        "firstName": "Bob",
        "lastName": "Customer",
        "address1": "Filbert Way",
        "address2": "",
        "city": "Toronto",
        "regionCode": "ON",
        "countryCode": "CA",
        "postalCode": "M4C 1B5",
        "emailAddress": "bob_customer@email.com",
        "nationalIdentificationNumber": "",
        "addressType": "shipTo"
    }],
    "items": [{
        "sku": "SC90",
        "description": "Men's Cotton Shorts (Color: Blue, Size: Large)",
        "name": "Men's Cotton Shorts",
        "price": "19.00",
        "quantity": 1,
        "category": "Apparel",
        "hsCode": "6203.42.00.41",
        "weight": 1,
        "uom": "lbs",
        "countryOfOrigin": "US",
        "autoClassify": "false"
        
    }]
}

Sample Landed Cost JSON Response Using Valid HS Code

 
{
    "id": "583e625043f3127d8afe129d",
    "code": "200",
    "message": "Landed Cost API Request Was Successful",
    "securityKey": "{Your Security Key Goes Here}",
    "shippingMethod": "ANY",
    "shippingCostTotal": "0.00",
    "additionalInsuranceTotal": "0.00",
    "discountTotal": "0.00",
    "languageCode": "en-us",
    "dutiesTotal": "0.03",
    "taxesTotal": "2.47",
    "feesTotal": "0.00",
    "subTotal": "19.00",
    "grandTotal": "21.50",
    "landedCostTotal": "2.50",
    "carrier": "DHL",
    "sourceCurrencyCode": "USD",
    "targetCurrencyCode": "USD",
    "transactionId": "",
    "items": [
        {
            "sku": "SC90",
            "name": "Men's Cotton Shorts",
            "description": "Men's Cotton Shorts (Color: Blue, Size: Large)",
            "price": "19.00",
            "quantity": "1",
            "category": "Apparel",
            "dutiesAmount": "0.03",
            "taxesAmount": "2.47",
            "restricted": "false",
            "hsCode": "6203.42.00.41",
            "weight": "1",
            "uom": "lbs",
            "countryOfOrigin": "US",
            "hsCodeAccuracy": "100",
            "autoClassify": "false"
        }
    ],
    "fees": [
    ],
    "taxes": [
        {
            "name": "Goods and Services Tax",
            "localName": "Goods and Services Tax",
            "amount": "0.95"
        },
        {
            "name": "Harmonized Sales Tax",
            "localName": "Harmonized Sales Tax",
            "amount": "1.52"
        }
    ],
    "addresses": [
        {
            "firstName": "John",
            "lastName": "Shipper",
            "company": "",
            "address1": "123 Vine Street",
            "address2": "",
            "city": "Lemoore",
            "regionCode": "CA",
            "postalCode": "93245",
            "countryCode": "US",
            "emailAddress": "john_shipper@email.com",
            "addressType": "shipFrom",
            "nationalIdentificationNumber": ""
        },
        {
            "firstName": "Bob",
            "lastName": "Customer",
            "company": "",
            "address1": "Filbert Way",
            "address2": "",
            "city": "Toronto",
            "regionCode": "ON",
            "postalCode": "M4C 1B5",
            "countryCode": "CA",
            "emailAddress": "bob_customer@email.com",
            "addressType": "shipTo",
            "nationalIdentificationNumber": ""
        }
    ],
    "utcDateTimeStamp": "Wed, Nov 30, 2016 05:23:28 AM UTC",
    "timeStamp": "1480483408"
}

Sample Landed Cost JSON Request Using Auto-Classification

 

{
    "carrier": "DHL",
    "shippingMethod": "ANY",
    "securityKey": "{Your Security Key Goes Here}",
    "shippingCostTotal": "00.00",
    "sourceCurrencyCode": "USD",
    "targetCurrencyCode": "USD",
    "discountTotal": "0.00",
    "additionalInsuranceTotal": "0.00",
    "languageCode": "en-us",
    "addresses": [{
        "firstName": "John",
        "lastName": "Shipper",
        "address1": "123 Vine Street",
        "address2": "",
        "city": "Lemoore",
        "regionCode": "CA",
        "countryCode": "US",
        "postalCode": "93245",
        "emailAddress": "john_shipper@email.com",
        "nationalIdentificationNumber": "",
        "addressType": "shipFrom"
    },
    {
        "firstName": "Bob",
        "lastName": "Customer",
        "address1": "Filbert Way",
        "address2": "",
        "city": "Toronto",
        "regionCode": "ON",
        "countryCode": "CA",
        "postalCode": "M4C 1B5",
        "emailAddress": "bob_customer@email.com",
        "nationalIdentificationNumber": "",
        "addressType": "shipTo"
    }],
    "items": [{
        "sku": "SC90",
        "description": "Men's Cotton Shorts (Color: Blue, Size: Large)",
        "name": "Men's Cotton Shorts",
        "price": "19.00",
        "quantity": 1,
        "category": "Apparel",
        "hsCode": "",
        "weight": 1,
        "uom": "lbs",
        "countryOfOrigin": "US",
        "autoClassify": "auto-classifiy"
        
    }]
}

Sample Landed Cost JSON Response Using Auto-Classification

 
{
    "id": "583e625043f3127d8afe129d",
    "code": "200",
    "message": "Landed Cost API Request Was Successful",
    "securityKey": "{Your Security Key Goes Here}",
    "shippingMethod": "ANY",
    "shippingCostTotal": "0.00",
    "additionalInsuranceTotal": "0.00",
    "discountTotal": "0.00",
    "languageCode": "en-us",
    "dutiesTotal": "0.03",
    "taxesTotal": "2.47",
    "feesTotal": "0.00",
    "subTotal": "19.00",
    "grandTotal": "21.50",
    "landedCostTotal": "2.50",
    "carrier": "DHL",
    "sourceCurrencyCode": "USD",
    "targetCurrencyCode": "USD",
    "transactionId": "",
    "items": [
        {
            "sku": "SC90",
            "name": "Men's Cotton Shorts",
            "description": "Men's Cotton Shorts (Color: Blue, Size: Large)",
            "price": "19.00",
            "quantity": "1",
            "category": "Apparel",
            "dutiesAmount": "0.03",
            "taxesAmount": "2.47",
            "restricted": "false",
            "hsCode": "6203.42.00.41",
            "weight": "1",
            "uom": "lbs",
            "countryOfOrigin": "US",
            "hsCodeAccuracy": "100",
            "autoClassify": "auto-classifiy"
        }
    ],
    "fees": [
    ],
    "taxes": [
        {
            "name": "Goods and Services Tax",
            "localName": "Goods and Services Tax",
            "amount": "0.95"
        },
        {
            "name": "Harmonized Sales Tax",
            "localName": "Harmonized Sales Tax",
            "amount": "1.52"
        }
    ],
    "addresses": [
        {
            "firstName": "John",
            "lastName": "Shipper",
            "company": "",
            "address1": "123 Vine Street",
            "address2": "",
            "city": "Lemoore",
            "regionCode": "CA",
            "postalCode": "93245",
            "countryCode": "US",
            "emailAddress": "john_shipper@email.com",
            "addressType": "shipFrom",
            "nationalIdentificationNumber": ""
        },
        {
            "firstName": "Bob",
            "lastName": "Customer",
            "company": "",
            "address1": "Filbert Way",
            "address2": "",
            "city": "Toronto",
            "regionCode": "ON",
            "postalCode": "M4C 1B5",
            "countryCode": "CA",
            "emailAddress": "bob_customer@email.com",
            "addressType": "shipTo",
            "nationalIdentificationNumber": ""
        }
    ],
    "utcDateTimeStamp": "Wed, Nov 30, 2016 05:23:28 AM UTC",
    "timeStamp": "1480483408"
}