DOCS

Calculate landed cost - GraphQL

Landed Cost•
HomeFor logistics providers Landed Cost Calculate landed cost - GraphQL

Calculate a landed cost

Calculate duties, taxes, and fees with GraphQL.

GraphQL

Zonos calculates the total landed cost for international shipments—including duties, taxes, and any additional fees charged by customs, brokers, or carriers. In most cases, we guarantee these calculations by paying the final bill ourselves and charging you exactly what we calculated. In some cases, you can use our landed cost without a guarantee, meaning you assume responsibility for any difference between our calculation and the actual charges.

Prepare the request 

Calculating a landed cost API requires several inputs, which we've organized into workflows. Once complete, you’ll be able to make a single request to return a landed cost based on the shipping destination, items in the cart, and shipping details.

Each workflow has its own required inputs. GraphQL allows you to pass more data than necessary, but only certain fields are required to return a landed cost. These are clearly marked in our API reference to see all possible fields.

Note that some fields are conditionally required if you want your calculation to be guaranteed.

Below, we’ve outlined all fields required to calculate a guaranteed landed cost. Make sure this information is included before making your request.

Required inputs for guaranteed calculations

partyCreateWorkflowInput

The partyCreateWorkflowInput identifies the involved parties and their locations. View the full schema in our GraphQL API reference. Required fields are:

  • location
    • administrativeAreaCode: The state or province code, in two letters. Only required for CA and BR.
    • countryCode: The two letter ISO code of the country.
    • line1: The first line of the address.
    • postalCode: The postal code or zip code of the address.
  • person
    • email: The email address of the person.
    • firstName: The first name of the person.
    • lastName: The last name of the person.
    • phone: The phone number of the person.
  • type
    • DESTINATION: The location & person information for the shipping destination.
    • ORIGIN: The location information for the shipping origin. The person associated with the shipping origin is not required.
itemCreateWorkflowInput

The itemCreateWorkflowInput lists the items in the cart. There are many optional fields (see all possibilities in our API reference), but the fields below are required.

  • amount: The price of the item.
  • currencyCode: The currency code for the item amount.
  • quantity: The quantity of the item.
  • countryOfOrigin: The country where the item was manufactured.
  • One of the following (whichever is set as your item key preference. Your item key connects information stored in Catalog to the item in the cart and is used during label creation.)
    • productId: The item's product ID.
    • sku: The item's SKU.

The measurements (WEIGHT, LENGTH, WIDTH, HEIGHT) are only required if you want to cartonize your items when getting a shipment rating.

cartonsCreateWorkflowInput

The cartonsCreateWorkflowInput only requires the input itself. View the full schema in our GraphQL API reference to see all values that can be passed. It is important to pass the dimensions and weight of the carton if Zonos is calculating the shipping cost.

shipmentRatingCreateWorkflowInput

This workflow is used when you already know the shipping service and cost; if you want Zonos to calculate these costs for services you have enabled, swap this workflow out and use the shipmentRatingCalculateWorkflow instead.

The shipmentRatingCreateWorkflowInput communicates the shipping cost. View the full schema in our GraphQL API reference. Required fields are:

  • amount: The shipping cost.
  • currencyCode: The currency code of the shipping cost.
  • serviceLevelCode: The code indicating the shipping service level used in the shipment rating.
landedCostWorkFlowInput

The landedCostWorkFlowInput dictates preferences for the landed cost calculation. View the full schema in our GraphQL API reference. Required fields are:

  • calculationMethod: Indicates your preference for how you plan to ship: DDP (prepaid duties and taxes) or DAP (either duties and taxes are paid at delivery, or if a remittance scheme applies, they are remitted via a tax ID).
    • If you use our landed cost guarantee, this value should always be DDP_PREFERRED, which will provide a DDP quote when possible and a DAP quote is a DDP one is not allowed. Using DAP instead may result in landed costs no longer being guaranteed, as this typically results in duties and taxes paid at delivery.
  • endUse: Indicates if the goods are being sold to another business (FOR_RESALE) or for end use with a consumer (NOT_FOR_RESALE).
  • tariffRate: Indicates the method that Zonos should use to calculate the tariff rates for this quote, in the event that there is a range of tariff rates that could be applied. *When using our landed cost guarantee, this should always be ZONOS_PREFERRED.

Add calculated shipping: If you want Zonos to calculate the shipping cost for you, replace the shipmentRatingCreateWorkflow with the shipmentRatingCalculateWorkflow. Add the cartonizeWorkflow if you want Zonos to sort your items into cartons before finding the shipping cost (used for dimensional weight).

HS code and shipping options

GraphQL gives you the flexiblity to customize the request to your preference. There are a couple of options for how you include HS codes and shipping costs in the request.

HS codes

HS codes impact duty rates are therefore required. You can pass the HS code for each item or let Classify generate them.

Pass HS codes for each item

Zonos highly recommends using product-specific HS codes as it leads to a more accurate landed cost quote. If you know your HS codes, pass the hsCode for each item during the itemCreateWorkflow.

If you pass an HS code, Zonos will validate it on the fly when getting a landed cost quote. If the HS code you provided is invalid (meaning it does not exist), Zonos will re-classify your item on the fly and use the new, valid HS code instead of your provided one.

If you need help generating HS codes for your products, learn about Zonos Classify and how to request a classification.

Generate HS codes with Classify

If you do not pass Zonos an hsCode, we'll first check Zonos Catalog to see if you have an HS code stored for your item. If you don't, we'll call Classify to generate a classification to power your landed cost calculation based on the following itemCreateWorkflow product detail fields: description, category, and material. If your product detail fields are not detailed enough to generate a classification based on Classify's confidence scoring, the default HS code assigned to your store will be used.

Shipping cost

Both the shipping service level and its cost impacts the duties, taxes, and fees and is therefore required. Zonos can calculate shipping or you can pass this to us.

Calculate shipping

To have Zonos calculate shipping costs, use the shipmentRatingCalculateWorkflow. The shipment options returned in the calculated shipping response will correlate with the serviceLevels you have assigned to shipping profiles in Dashboard.

Troubleshooting: If you are expecting a serviceLevel in the response but it does not show up, please ensure that the serviceLevel is enabled and is supported by the method you selected.

Add the cartonizeWorkflow (which has no inputs) if you want Zonos to sort your items into cartons before finding the shipping cost (used for dimensional weight.

Pass shipping costs

If you know the serviceLevel and amount for a shipment, you can pass those in the shipmentRatingCreateWorkflow portion of the request. We will use those values to calculate any associated carrier fees and return those in the response.

Request a landed cost via API 

Once you have the required input data, send the GraphQL mutation to the API endpoint using your chosen client library or tool. Here are some examples of how you can structure the mutation.

Use this request when you are having Zonos calculate the shipping cost as part of the Landed Cost request. We will then calculate duties and taxes on shipping if they are assessed by the destination country.

Mutation

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
mutation CalculateLandedCost(
  $parties: [PartyCreateWorkflowInput!]!
  $items: [ItemCreateWorkflowInput!]!
  $landedCostConfig: LandedCostWorkFlowInput!
) {
  partyCreateWorkflow(input: $parties) {
    type
    id
    organization
  }
  itemCreateWorkflow(input: $items) {
    id
    amount
    productId
  }
  cartonizeWorkflow {
    id
    type
    items {
      item {
        id
      }
    }
  }
  shipmentRatingCalculateWorkflow {
    id
    amount
  }
  landedCostCalculateWorkflow(input: $landedCostConfig) {
    id
    duties {
      amount
      currency
      note
    }
    taxes {
      amount
      currency
      note
    }
    fees {
      amount
      currency
      note
    }
  }
}

Variables

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
{
  "parties": [
    {
      "location": {
        "administrativeArea": "Utah",
        "administrativeAreaCode": "UT",
        "countryCode": "US",
        "line1": "345 N 2450 E",
        "line2": "#151",
        "locality": "St George",
        "postalCode": "84790"
      },
      "type": "ORIGIN"
    },
    {
      "location": {
        "administrativeArea": "New South Wales",
        "administrativeAreaCode": "NSW",
        "countryCode": "AU",
        "line1": "123 George Street",
        "line2": "Apartment 5B",
        "locality": "Sydney",
        "postalCode": "2000"
      },
      "person": {
        "email": "aussie.customer@gmail.com",
        "firstName": "James",
        "lastName": "Thompson",
        "phone": "+61412345678",
        "companyName": "Sydney Trading Co",
        "metadata": { "key": "customer_type", "value": "premium" }
      },
      "type": "DESTINATION"
    },
    {
      "type": "PAYOR",
      "location": {
        "administrativeArea": "Victoria",
        "administrativeAreaCode": "VIC",
        "countryCode": "AU",
        "latitude": -37.8136,
        "line1": "456 Collins Street",
        "line2": "Suite 12",
        "locality": "Melbourne",
        "longitude": 144.9631,
        "postalCode": "3000"
      },
      "person": {
        "email": "billing@reallysilkstore.com.au",
        "firstName": "Sarah",
        "lastName": "Mitchell",
        "phone": "+61398765432",
        "companyName": "Really Silk Store",
        "metadata": { "key": "billing_contact", "value": "primary" }
      }
    }
  ],
  "items": [
    {
      "amount": 120,
      "currencyCode": "USD",
      "countryOfOrigin": "US",
      "quantity": 1,
      "productId": "productId1",
      "hsCode": null,
      "description": "leather wallet",
      "measurements": [
        { "type": "WIDTH", "value": 1, "unitOfMeasure": "CENTIMETER" },
        { "type": "LENGTH", "value": 2, "unitOfMeasure": "CENTIMETER" },
        { "type": "HEIGHT", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "WEIGHT", "value": 1, "unitOfMeasure": "POUND" }
      ]
    },
    {
      "amount": 55,
      "currencyCode": "USD",
      "countryOfOrigin": "US",
      "quantity": 1,
      "productId": "productId2",
      "hsCode": "6206.30",
      "description": "t-shirt",
      "measurements": [
        { "type": "WIDTH", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "LENGTH", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "HEIGHT", "value": 5, "unitOfMeasure": "CENTIMETER" },
        { "type": "WEIGHT", "value": 1.5, "unitOfMeasure": "POUND" }
      ]
    }
  ],
  "landedCostConfig": {
    "calculationMethod": "DDP_PREFERRED",
    "endUse": "NOT_FOR_RESALE",
    "tariffRate": "ZONOS_PREFERRED"
  }
}

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
{
  "data": {
    "partyCreateWorkflow": [
      {
        "type": "ORIGIN",
        "id": "party_01044774-758f-4021-b8dd-e17d97609647",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      },
      {
        "type": "DESTINATION",
        "id": "party_0m6wgfjmhbnf2",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      },
      {
        "type": "PAYOR",
        "id": "party_0m6wgfjn5bnfh",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      }
    ],
    "itemCreateWorkflow": [
      {
        "id": "item_0m6wgfjpfw9fz",
        "amount": 120,
        "productId": "productId1"
      },
      {
        "id": "item_0m6wgfjpfw9g0",
        "amount": 55,
        "productId": "productId2"
      }
    ],
    "cartonizeWorkflow": [
      {
        "id": "carton_0m6wgfme53aqb",
        "type": "PACKAGE",
        "items": [
          {
            "item": {
              "id": "item_0m6wgfjpfw9g0"
            }
          },
          {
            "item": {
              "id": "item_0m6wgfjpfw9fz"
            }
          }
        ]
      }
    ],
    "shipmentRatingCalculateWorkflow": [
      {
        "id": "shipment_rating_0m6wgfmghvhh1",
        "amount": 24.8864
      }
    ],
    "landedCostCalculateWorkflow": [
      {
        "id": "landed_cost_7730b476-1307-4d14-8f76-3b37bd162054",
        "duties": [],
        "taxes": [
          {
            "amount": 5.5,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0.7822,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 12,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 1.7065,
            "currency": "USD",
            "note": null
          }
        ],
        "fees": [
          {
            "amount": 0,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0.8,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0,
            "currency": "USD",
            "note": null
          }
        ]
      }
    ]
  },
  "errors": []
}

Next step: Create an order

After you calculate a landed cost and receive the landedCostId from the API response, you should create an order to finalize the transaction in the Zonos system. Use the orderCreate mutation and pass in the landedCostId from your quote. Learn more about creating orders.

Request a landed cost in Dashboard 

You can also calculate landed costs directly in Zonos Dashboard without using the API. This is helpful for testing calculations, training your team, or getting quick quotes for customer inquiries.

Dashboard uses the same API endpoints described above, so the results will match what you'd get from direct API calls. This makes it a great way to validate your API integration or explore how different inputs affect the calculations.

Using the Dashboard calculator

With the landed cost calculator in Dashboard, you can get quotes with calculated shipping rates, create quotes with known shipping costs, or process multiple quotes in bulk.

Use this flow when you know the shipping service level and cost for your shipment.

  1. Go to Dashboard → Orders → Quotes
  2. Click New quote
  3. Optional — Modify the location of your ship-from address
  4. Select a Destination country from the dropdown
  5. Enter the shipping amount
    • The service level is optional; adding it allows us to calculate applicable carrier fees
  6. Add the item details for the shipment
    • When you enter a description, we automatically classify the product and generate an HS code
    • You can overwrite the generated HS code if needed
    • For multiple items, click Save and add another. Otherwise, click Save
  7. Optional — Click More options to change:
    • Sale type to For resale
    • Delivery mode to Delivery duties unpaid
  8. Click Get quote
    • To make changes, click Edit form and modify any details
    • Click Get quote again to update

A landed cost quote will appear on the right, including product, shipping, and import costs. Expand the quote to see detailed breakdowns of items, shipping, duties, taxes, and fees. All quotes are saved on the quotes page for future reference.

Edit existing quotes: Click Quote again in the top right to modify an existing quote rather than starting from scratch.

Benefits of using Dashboard

  • No coding required — Generate quotes through a user-friendly interface
  • Team training — Help non-technical team members understand landed cost components
  • API validation — Verify your API integration produces expected results
  • Customer support — Quickly generate quotes for customer inquiries
  • Bulk processing — Handle multiple calculations efficiently (coming soon)

Dashboard quotes include the same detailed breakdowns available through the API, making it an excellent complement to your automated integration.

Was this page helpful?

Book a demo

Questions?

Get support
© 2025 Zonoszonos.com
On this page:
  • Calculate a landed cost
  • Prepare the request
  • Request a landed cost via API
  • Request a landed cost in Dashboard