Set up Zonos
First, register for a Zonos account and configure your account on the Zonos Dashboard. You will then be able to get your API key, which will allow you to authenticate with the Zonos API.
Set base currency
To provide context about money amounts included in a landed cost request, you need to specify your request's base currency code (as an ISO currency code). This will refer to all monetary values in the request and what currency the resulting landed cost quote will be rendered in. You can find a list of supported currencies and their ISO codes on our landed cost docs.
Request
{
"currency": "USD"
}
Provide item details
To get an accurate possible landed cost quote using Zonos, you will need to supply as much per-item detail as possible, including harmonized (HS) codes. Generally, the more information you include, the more accurate your quote will be.
While providing HS codes allows Zonos Landed Cost to return the most accurate and complete calculations, it is possible to approximate the actual landed cost without an HS code. However, note that if your items' total cost exceeds the de minimis threshold, an HS code may be required. In those cases, sending a request without an HS code will result in an error.
For each item you want to include in your landed cost quote, add an entry to the items array on the request body.
Request
{
"items": [
{
"id": "294395",
"amount": 75,
"country_of_origin": "FR",
"description_customs": null,
"hs_code": "6116.10.00",
"quantity": 1
}
]
}
Add shipping addresses
The ship-from and ship-to locations for your shipment are required to calculate the landed cost. A complete address is required for the shipment destination, but including the ship-from country is enough for most landed cost quotes.
Request
{
"ship_from_country": "US",
"ship_to": {
"city": "Campinas",
"country": "BR",
"postal_code": "75828-000",
"state": "SP"
}
}
Provide shipping costs
The Zonos Landed Cost API doesn’t calculate shipping costs - it focuses on customs duties, taxes, and fees. Because shipping is a considerable aspect of a total landed cost quote and a significant factor in how things are calculated, it's essential to specify the shipping cost upfront. This value can be obtained by using a shipment rating API, such as the Zonos Rating API, or by a variety of other means, such as your carrier’s shipping software, rate charts, etc.
Information relating to shipping costs, including the overall shipping amount, is sent via the shipping field in your API request.
Request
{
"shipping": {
"amount": 14.23
}
}
While only the amount is required, you can also provide a service level name to enable the API to calculate carrier fees off the provided amount. You can see a list of supported carriers and service levels on our Landed Cost docs.
Request
{
"shipping": {
"amount": 14.23,
"service_level": "ups_express_saver"
}
}
Send an API request
Now that you've built your request and configured it, you can send a POST request to the Zonos Landed Cost API. Make sure to authenticate with your API key and provide the correct version header in your request.
POST https://api.zonos.com/v1/landed_cost
Request
{
"currency": "USD",
"items": [
{
"id": "294395",
"amount": 75,
"country_of_origin": "FR",
"description_customs": null,
"hs_code": "6116.10.00",
"quantity": 1
}
],
"ship_from_country": "US",
"ship_to": {
"city": "Campinas",
"country": "BR",
"postal_code": "75828-000",
"state": "SP"
},
"shipping": {
"amount": 14.23,
"amount_discount": 0,
"service_level": "ups_express_saver"
}
}
Response
{
"id": "ldct_1AoaDV8MZ8SAmsVFFTWISI",
"amount_subtotal": {
"duties": 53.54,
"fees": 27.64,
"taxes": 33.96
},
"currency": {
"id": "1aad3b7e-c",
"base": "USD",
"date": "2022-09-06T20:57:10.333+0000",
"rates": [
{
"currency": "BRL",
"rate": 5.2499
}
]
},
"customs": {
"delivery_duty_paid": "available",
"items": [
{
"id": "294395",
"amount": 75,
"country_of_origin": "FR",
"country_of_origin_source": "api_request",
"description_customs": null,
"description_retail": null,
"hs_code": "6116.10.00",
"hs_code_source": "api_request",
"note": "",
"quantity": 1
}
],
"shipping_amount": 14.23,
"ship_to_country": "BR"
},
"de_minimis": [
{
"formula": "(cost {'<='} 0 brl)",
"method": "FOB",
"note": "Duty applies to all shipments",
"threshold": "above",
"type": "duty"
},
{
"formula": "(cost {'<='} 0 brl)",
"method": "FOB",
"note": "Tax applies to all shipments",
"threshold": "above",
"type": "tax"
}
],
"duties": [
{
"amount": 45.0,
"description": "Basic customs duty",
"item_id": "294395",
"formula": "60 %",
"note": "Duty is 60% of the items total.",
"type": "item"
},
{
"amount": 8.538,
"description": "Basic customs duty",
"item_id": "294395",
"formula": "60 %",
"note": "Duty is 60% of the items total.",
"type": "shipping"
}
],
"fees": [
{
"amount": 15.0,
"description": "UPS United States Duty and Tax Forwarding Charge",
"item_id": null,
"formula": "15 USD",
"note": null,
"type": "ddp_service_fee"
},
{
"amount": 12.0,
"description": "UPS Disbursement Fee",
"item_id": null,
"formula": "2.00% of duties & taxes amount with a minimum of 12 usd, whichever is greater",
"note": null,
"type": "advancement"
},
{
"amount": 0.64,
"description": "UPS Currency Conversion Fee",
"item_id": null,
"formula": ".75% of the amount converted",
"note": null,
"type": "currency_conversion_fee"
}
],
"taxes": [
{
"amount": 16.46,
"description": "ICMS",
"item_id": "294395",
"formula": "0.82% applied to gross amount including tax. Calculate with fomula: value/(1-0.18)*0.18",
"note": null,
"type": "item"
},
{
"amount": 3.12,
"description": "ICMS",
"item_id": "294395",
"formula": "0.82% applied to gross amount including tax. Calculate with fomula: value/(1-0.18)*0.18",
"note": null,
"type": "shipping"
},
{
"amount": 9.88,
"description": "ICMS",
"item_id": "294395",
"formula": "0.82% applied to gross amount including tax. Calculate with fomula: value/(1-0.18)*0.18",
"note": "ICMS on the duty of the item",
"type": "duty"
},
{
"amount": 1.87,
"description": "ICMS",
"item_id": "294395",
"formula": "0.82% applied to gross amount including tax. Calculate with fomula: value/(1-0.18)*0.18",
"note": "ICMS on the duty of the shipping",
"type": "duty"
},
{
"amount": 2.63,
"description": "ICMS",
"item_id": null,
"formula": "0.82% applied to gross amount including tax. Calculate with fomula: value/(1-0.18)*0.18",
"note": null,
"type": "advancement"
}
],
"removed_items": [],
"remittance": [],
"landedCostGuaranteeCode": "ZONOS"
}
Calculate a landed cost
Learn how to request a landed cost via the REST API.REST
The Zonos Landed Cost API lets you quickly get a highly accurate landed cost quote for cross-border import and export shipments. While providing harmonized (HS) codes allows Zonos Landed Cost to return the most accurate duty calculation, we will return the approximate amount of duties and taxes even when a harmonized code isn't provided.