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 shipments, which includes duties, taxes, and any additional fees that customs, brokers, or shipping carriers may charge. We often guarantee these calculations by paying the duty, tax, and fee bill ourselves while charging you exactly what we calculate. In rare cases, our calculations can be used without our guarantee, where you take on any difference between our calculation and the duty and tax bill.

Prepare the mutation input 

Calculating a landed cost via GraphQL API involves multiple steps; we've organized these steps into workflows. In the end, you'll have everything you need to make one call to get a landed cost based on the shipping destination, items in the cart, and shipping.

Each workflow needs specific input data. GraphQL allows you to include more information than required; please refer to our full API reference to see all possible fields. Required fields are marked as such in our API reference, but this mark only applies to fields that are required for functionality. A few additional fields are required when using our guarantee.

Below, we've listed all required fields for calculating a guaranteed landed cost. Make sure you have this information ready.

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.
  • 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).

Options when calculating a landed cost

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.

By default, if you do not supply an hsCode and we call Classify, the hsCode generated by Classify will not be returned in the response as it will only be utilized internally to generate your landed cost. However, if you have a Classify subscription, we'll return Classify's HS code in your landed cost response.

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.

Send the mutation 

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
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
mutation {
  partyCreateWorkflow(
    input: [
      {
        location: {
          administrativeArea: "Utah"
          administrativeAreaCode: "UT"
          countryCode: US
          line1: "345 N 2450 E"
          line2: "#151"
          locality: "St George"
          postalCode: "84790"
        }
        type: ORIGIN
      }
      {
        location: {
          administrativeArea: "BC"
          administrativeAreaCode: "BC"
          countryCode: CA
          line1: "27 Sussex Dr."
          locality: "Victoria"
          postalCode: "V8T 2V9"
        }
        person: {
          email: "test@gmail.com"
          firstName: "firstName"
          lastName: "lastName"
          phone: "5022303021"
          companyName: "goProTest"
          metadata: { key: "key", value: "value" }
        }
        type: DESTINATION
      }
      {
        type: PAYOR
        location: {
          administrativeArea: "ON"
          administrativeAreaCode: "ON"
          countryCode: CA
          latitude: 1.2
          line1: "asdf"
          line2: "asdf"
          locality: "locality"
          longitude: 3423.2
          postalCode: "M4C 1A1"
        }
        person: {
          email: "test@gmail.com"
          firstName: "firstName"
          lastName: "lastName"
          phone: "5022303021"
          companyName: "goProTest"
          metadata: { key: "key", value: "value" }
        }
      }
    ]
  ) {
    type
    id
    organization
  }

  itemCreateWorkflow(
    input: [
      {
        amount: 69
        currencyCode: USD
        countryOfOrigin: US
        quantity: 1
        productId: "productId"
        hsCode: "1006.30"
        description: "description"
        measurements: [
          { type: WIDTH, value: 2, unitOfMeasure: CENTIMETER }
          { type: WEIGHT, value: 2, unitOfMeasure: POUND }
        ]
      }
      {
        amount: 62
        currencyCode: CAD
        countryOfOrigin: US
        hsCode: "1006.30"
        quantity: 1
        productId: "productId2"
        description: "description2"
        measurements: [
          { type: WIDTH, value: 2, unitOfMeasure: CENTIMETER }
          { type: WEIGHT, value: 2, unitOfMeasure: POUND }
        ]
      }
    ]
  ) {
    id
    amount
  }
  cartonizeWorkflow {
    id
    type
    items {
      item {
        id
      }
    }
  }
  shipmentRatingCalculateWorkflow {
    id
    amount
  }
  landedCostCalculateWorkflow(
    input: { endUse: FOR_RESALE, method: DAP, tariffRate: ZONOS_PREFERRED }
  ) {
    id
    duties {
      amount
      currency
    }
    taxes {
      amount
      currency
    }
    fees {
      amount
      currency
    }
  }
}

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
{
  "data": {
    "partyCreateWorkflow": [
      {
        "type": "ORIGIN",
        "id": "party_749959ae-b9ff-4de4-b4ac-59cc990c53ba",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      },
      {
        "type": "DESTINATION",
        "id": "party_cd7ff245-76b6-464f-a7bf-151ebe1f8833",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      },
      {
        "type": "PAYOR",
        "id": "party_00e63a9e-9735-44d9-b129-3b3e76c5df25",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      }
    ],
    "itemCreateWorkflow": [
      {
        "id": "item_eb27f071-de8b-4578-9db9-ae69aaf9be3e",
        "amount": 69
      },
      {
        "id": "item_fffa8ba8-cc8d-4e13-bed6-55044a71c115",
        "amount": 62
      }
    ],
    "cartonizeWorkflow": [
      {
        "id": "carton_b34b29c1-ce27-464b-b91b-df8e4a696312",
        "type": "PACKAGE",
        "items": [
          {
            "item": {
              "id": "item_eb27f071-de8b-4578-9db9-ae69aaf9be3e"
            }
          },
          {
            "item": {
              "id": "item_fffa8ba8-cc8d-4e13-bed6-55044a71c115"
            }
          }
        ]
      }
    ],
    "shipmentRatingCalculateWorkflow": [
      {
        "id": "shipment_rating_96787309-9510-43cc-b4fa-c341ff80f4cc",
        "amount": 173.2
      },
      {
        "id": "shipment_rating_b0ccb109-7794-4c7c-b5cc-e2cfbbc5c8ac",
        "amount": 190.1
      }
    ],
    "landedCostCalculateWorkflow": [
      {
        "id": "landed_cost_74d3ce11-bff2-4326-9e6f-368e03ac88b4",
        "duties": [
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "taxes": [
          {
            "amount": 3.45,
            "currency": "USD"
          },
          {
            "amount": 3.1,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "fees": [
          {
            "amount": 0.13,
            "currency": "USD"
          },
          {
            "amount": 1.44,
            "currency": "USD"
          }
        ]
      },
      {
        "id": "landed_cost_7bbfd354-028c-457f-8c8e-c81bb8fa09a0",
        "duties": [
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "taxes": [
          {
            "amount": 3.45,
            "currency": "USD"
          },
          {
            "amount": 3.1,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "fees": [
          {
            "amount": 0.13,
            "currency": "USD"
          },
          {
            "amount": 1.44,
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Was this page helpful?

Book a demo

Questions?

Get support
© 2025 Zonoszonos.com
On this page:
  • Calculate a landed cost
  • Prepare the mutation input
  • Send the mutation