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 -etter 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
: Thelocation
&person
information for the shipping destination.ORIGIN
: Thelocation
information for the shipping origin. Theperson
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.
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. UsingDAP
instead may result in landed costs no longer being guaranteed, as this typically results in duties and taxes paid at delivery.
- If you use our landed cost guarantee, this value should always be
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 beZONOS_PREFERRED
.
Add calculated shipping: If you want Zonos to calculate the shipping cost for you, replace the
shipmentRatingCreateWorkflow
with theshipmentRatingCalculateWorkflow
. Add thecartonizeWorkflow
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.
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.
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.
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 theserviceLevel
is enabled and is supported by themethod
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.
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.
Mutation
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
{
"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"
}
]
}
]
}
}
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.