Zonos logo
DOCS

Calculate a landed cost without hs code

/

Calculate a landed cost quote without 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, it is still possible to approximate the actual landed cost by sending a request without item HS code details. Note: If your items' total cost exceeds the de minimis threshold, an HS code may be required. In those cases, sending an API request without an HS code will result in an error.

If you have per-item HS codes, it's generally best to send those for a more accurate and complete quote. Check out our guide on calculating landed cost with HS codes for more information.

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.

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
{
  "items": [
    {
      "id": "294395",
      "amount": 75,
      "country_of_origin": "FR",
      "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
{
  "currency": "USD",
  "items": [
    {
      "id": "294395",
      "amount": 75,
      "country_of_origin": "FR",
      "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_4w7BFYVxqzPQ3vY32amaZT",
  "amount_subtotal": {
    "duties": 53.54,
    "fees": 27.64,
    "taxes": 33.96
  },
  "currency": {
    "id": "350e8951-e",
    "base": "USD",
    "date": "2022-09-07T15:32:09.367+0000",
    "rates": [
      {
        "currency": "BRL",
        "rate": 5.2493
      }
    ]
  },
  "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": "6206.10",
        "hs_code_source": "account_default",
        "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"
}