/
1
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.
2
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
1
2
3
{
"currency": "USD"
}
3
Indicate per-item information
To get an accurate possible landed cost quote using Zonos, you will need to supply as much per-item detail as possible, including HS codes. Generally, the more information you include, the more sure you can be that a quote will be accurate.
If you don’t have full item details or don’t have an HS code for every item you want to include in your landed cost calculation, check out our guide on calculating landed cost quotes without HS codes.
For each item you want to include in your landed cost quote, simply add an entry to the items array on the request body.
Request
1
2
3
4
5
6
7
8
9
10
11
12
{
"items": [
{
"id": "294395",
"amount": 75,
"country_of_origin": "FR",
"description_customs": null,
"hs_code": "6116.10.00",
"quantity": 1
}
]
}
4
Indicate ship-from and ship-to locations
The ship-from and ship-to locations for your shipment are required to calculate landed cost. A complete address is required for the shipment destination, but simply including the ship-from country is enough for most landed cost quotes.
Request
1
2
3
4
5
6
7
8
9
{
"ship_from_country": "US",
"ship_to": {
"city": "Campinas",
"country": "BR",
"postal_code": "75828-000",
"state": "SP"
}
}
5
Indicate your shipping amount
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
1
2
3
4
5
{
"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
1
2
3
4
5
6
{
"shipping": {
"amount": 14.23,
"service_level": "ups_express_saver"
}
}
6
Send a request to the Zonos Landed Cost API
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
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
{
"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
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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{
"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 quote using HS codes
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.
If you don’t have full item details or don’t have an HS code for every item you want to include in your landed cost calculation, check out our guide on calculating landed cost quotes without HS codes.