Zonos logo
DOCS

Calculate landed cost graphql

/

Calculate a landed cost - GraphQL 

The Zonos Landed Cost API lets you quickly get a highly accurate landed cost quote for cross-border shipments.

1

Send a request to the Zonos Landed Cost API

To start a session, you will create a rootId. The root is an identifier that will link all subsequent calls that are made for this landed cost request.

POST https://api.zonos.com/graphql

Mutation

1
2
3
4
5
mutation {
  createRoot {
    id
  }
}

Response

1
2
3
4
5
6
7
{
    "data": {
        "createRoot": {
            "id": "root_f6d0b902-49db-4472-a573-11a7d53606e8"
        }
    }
}
2

Add item details for the order

To get an accurate 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 do not pass an hsCode, the default hsCode assigned to your store will be used.

Mutation

1
2
3
4
5
6
mutation createItems($rootId: ID!) {
 itemsCreate(
  input: [
   {
    rootId: $rootId
    amount: 221.25
    currencyCode: USD
    description: "item 1"
    hsCode: "6202"
    productId: "prod-123"
    quantity: 1
    countryOfOrigin: US
    measurements: [
     { type: WEIGHT, value: 9, unitOfMeasure: OUNCE, source: API_REQUEST }
    ]
   }
   {
    amount: 55.25
    currencyCode: USD
    description: "item 2"
    hsCode: "6202"
    productId: "prod-123-special"
    quantity: 1
    countryOfOrigin: US
    measurements: [
     { type: WEIGHT, value: 9, unitOfMeasure: OUNCE, source: API_REQUEST }
    ]
   }
  ]
 ) {
  id
  description
 }
}

Variables

1
2
3
{
 "rootId": "root_f6d0b902-49db-4472-a573-11a7d53606e8"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
 "data": {
  "itemsCreate": [
   {
    "id": "item_4bd5d508-fdb2-46a1-8843-974e8fe9dcb0",
    "description": "item 1"
   },
   {
    "id": "item_f3b15e47-6354-477f-9ca9-7ac489c2058b",
    "description": "item 2"
   }
  ]
 }
}
3

Add shipment details for the order

The shipFrom and shipTo locations for your shipment are required to calculate landed cost. A complete address is required for the shipment destination, but simply including the shipFrom country is enough for most landed cost quotes.

Mutation

1
2
3
4
5
6
7
8
mutation createParty($rootId: ID!) {
 shipFrom: createParty(
  input: {
   location: {
    line1: "123 street"
    postalCode: "84790"
    administrativeArea: "Utah"
    administrativeAreaCode: "UT"
    countryCode: US
    locality: "St george"
   }
   referenceId: $rootId
   type: ORIGIN
  }
 ) {
  id
 }
 shipTo: createParty(
  input: {
   location: {
    line1: "123 street"
    postalCode: "T5A 0A7"
    administrativeArea: "AB"
    administrativeAreaCode: "AB"
    countryCode: CA
    locality: "Edmonton"
   }
   type: DESTINATION
  }
 ) {
  id
 }
}

Variables

1
2
3
{
 "rootId": "root_f6d0b902-49db-4472-a573-11a7d53606e8"
}

Response

1
2
3
4
5
6
7
8
9
10
{
 "data": {
  "shipFrom": {
   "id": "party_3764ee11-fec2-46f9-876e-05e1e1f7f15a"
  },
  "shipTo": {
   "id": "party_0bed3320-5e18-4a69-a272-dfc5a8ba6696"
  }
 }
}
4

Cartonize the items in order to get an accurate shipment rating

The cartonize mutation is used to assign the items in your shipment to a box or multiple boxes that will then be used to calculate the shipmentRating. If you have not specified a packaging option using the createPackagingOption mutation, Zonos will default to a packing option with the dimensions of 8x4x2.

Mutation

1
2
3
4
5
6
7
8
9
10
11
mutation cartonize($rootId: ID!) {
 cartonize(input: { rootId: $rootId }) {
  id
  length
  width
  height
  dimensionalUnit
  weight
  weightUnit
 }
}

Variables

1
2
3
{
 "rootId": "root_ead03e32-2c81-4423-897c-519df43a5e22"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
 "data": {
  "cartonize": [
   {
    "id": "carton_9d6581a2-cc6c-4c3c-8562-12d87fc4cebb",
    "length": 8,
    "width": 4,
    "height": 2,
    "dimensionalUnit": "INCH",
    "weight": 1.14,
    "weightUnit": "POUND"
   }
  ]
 }
}
5

Calculate a shipment rating for this order

In order to obtain an accurate landed cost, you must provide a shipping value, or in this case, calculate a shipment rating. When calculating a shipment rating in the landed cost API, Zonos will return results for carriers and service levels that you have enabled in Dashboard.

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
mutation calculateShipmentRatings($rootId: ID!) {
 calculateShipmentRatings(input: { rootId: $rootId }) {
  id
  amount
  displayName
  minTransitAt
  maxTransitAt
  shippingProfile {
   customServiceLevelCode
   landedCostMethod
  }
 }
}

Variables

1
2
3
{
  "rootId": "root_ead03e32-2c81-4423-897c-519df43a5e22"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
 "data": {
  "calculateShipmentRatings": [
   {
    "id": "shipment_rating_f596ca9a-1ff5-4378-bac6-c83ea9497ef3",
    "amount": 52.5,
    "displayName": "USPS Priority",
    "minTransitAt": null,
    "maxTransitAt": null,
    "shippingProfile": {
     "customServiceLevelCode": "USPS_PRIORITY",
     "landedCostMethod": "DAP_FORCED"
    }
   }
  ]
 }
}
6

Calculate the landed cost

Now that the items, parties, and shipmentRating have been assigned to the root, you can calculate the landed cost for the shipment.

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
mutation calculateLandedCost($rootId: ID!) {
  calculateLandedCost(input: { rootId: $rootId, method: DAP }) {
    id
    rootId
    shipmentRating {
      displayName
    }
    tariffRate
    deMinimis {
      formula
      method
      note
      threshold
      type
    }
    duties {
      amount
      currency
      formula
      item {
        id
        description
      }
    }

    taxes {
      amount
      formula
      currency
      item {
        id
        description
      }
    }
    fees {
      amount
      description
      formula
      item {
        id
        description
      }
    }

}
}

Variables

1
2
3
{
  "rootId": "root_ead03e32-2c81-4423-897c-519df43a5e22"
}

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
{
 "data": {
  "calculateLandedCost": [
   {
    "id": "landed_cost_ed07d3b4-19ee-4d11-90e4-cff877995d89",
    "rootId": "root_ead03e32-2c81-4423-897c-519df43a5e22",
    "shipmentRating": {
     "displayName": "USPS Priority"
    },
    "tariffRate": "ZONOS_PREFERRED",
    "deMinimis": [
     {
      "formula": "(cost {'<='} 20 cad and hs_code not_starts_with \"2203,2204,2205,2206,2208,24\")",
      "method": "FOB",
      "note": "Items value less than 20 CAD and not containing alcohol, tobacco, or other excluded items",
      "threshold": "ABOVE",
      "type": "DUTY"
     },
     {
      "formula": "(cost {'<='} 20 cad and hs_code not_starts_with \"2203,2204,2205,2206,2208,24\")",
      "method": "FOB",
      "note": "Items value less than 20 CAD and not containing alcohol, tobacco, or other excluded items",
      "threshold": "ABOVE",
      "type": "TAX"
     }
    ],
    "duties": [
     {
      "amount": 0,
      "currency": "USD",
      "formula": "0.0 % cost",
      "item": {
       "id": "item_8a113a77-45d9-4d1f-b6ee-5df2b01cc4e2",
       "description": "item 2"
      }
     },
     {
      "amount": 0,
      "currency": "USD",
      "formula": "0.0 % cost",
      "item": {
       "id": "item_a7bb4bc8-3e96-4cb1-99c0-4a5462af20aa",
       "description": "item 1"
      }
     }
    ],
    "taxes": [
     {
      "amount": 2.7625,
      "formula": "5%",
      "currency": "USD",
      "item": {
       "id": "item_8a113a77-45d9-4d1f-b6ee-5df2b01cc4e2",
       "description": "item 2"
      }
     },
     {
      "amount": 11.0625,
      "formula": "5%",
      "currency": "USD",
      "item": {
       "id": "item_a7bb4bc8-3e96-4cb1-99c0-4a5462af20aa",
       "description": "item 1"
      }
     },
     {
      "amount": 0,
      "formula": "5%",
      "currency": "USD",
      "item": {
       "id": "item_8a113a77-45d9-4d1f-b6ee-5df2b01cc4e2",
       "description": "item 2"
      }
     },
     {
      "amount": 0,
      "formula": "5%",
      "currency": "USD",
      "item": {
       "id": "item_a7bb4bc8-3e96-4cb1-99c0-4a5462af20aa",
       "description": "item 1"
      }
     }
    ],
    "fees": [
     {
      "amount": 7.33,
      "description": "Postal Clearance Fee",
      "formula": "9.95 CAD Handling Fee Per Shipment",
      "item": null
     }
    ]
   }
  ]
 }
}