/
1
Start a session
To start a session, you will create a rootId. The root is an identifier that will link the retailer's order in your system to the order in Zonos' system. API reference for the createRoot mutation can be found here.
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_0bfa01a6-202a-41cf-aeda-793aba1502de"
}
}
}
2
Match items needing additional customs information
Using the root ID that was generated, pass item details for the shipment to enable Zonos to generate a customsSpec for those items. The base requirement for this mutation is the productId and rootId. Any other information that can be shared about the item will be used to enrich the customsSpec. API reference documentation can be found here.
Mutation
1
2
3
4
5
mutation ItemsCreate($itemsCreate: ItemsCreateInput!) {
itemsCreate(input: $itemsCreate) {
id
}
}
Variables
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"itemsCreate": [
{
"amount": 82.25,
"countryOfOrigin": "MX",
"currencyCode": "USD",
"description": "item 1",
"productId": "F39502-1",
"quantity": 1,
"rootId": "root_0bfa01a6-202a-41cf-aeda-793aba1502de"
}
]
}
Response
1
2
3
4
5
6
7
8
9
{
"data": {
"itemsCreate": [
{
"id": "item_0bfa01a6-202a-41cf-aeda-793aba1502de"
}
]
}
}
3
Add ship from details for the order
Zonos will be unable to know the origin of this shipment as the label was not manifested in the Zonos dashboard. To provide the right documentation and calculation amounts, you will need pass the shipFrom party details using the root ID that was used to start this flow. Please note that this step can happen prior to the addition of item details and vice versa. For this mutation, we only require location details. API reference can be found here.
Mutation
1
2
3
4
5
6
7
8
mutation CreateParties( $shipFrom: CreatePartyInput!) {
shipFrom: createParty(input: $shipTo) {
id
location {
countryCode
}
}
}
Variables
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"shipFrom": {
"type": "ORIGIN",
"referenceId": "root_cd8d3d85-283f-4865-af77-9cda0c123c0a",
"location": {
"administrativeArea": "Utah",
"administrativeAreaCode": "UT",
"countryCode": "US",
"line1": "370 Buena Vista Boulevard",
"locality": "St. George",
"postalCode": "84790"
}
}
}
Response
1
2
3
4
5
6
7
8
9
10
{
"data": {
"shipFrom": {
"id": "party_ac64040b-228e-424c-a090-6da03197011d",
"location": {
"countryCode": "US"
}
}
}
}
4
Link shipment with Zonos order
Supply Zonos with the account id of the merchant as well as their accountOrderNumber, and rootId that was created to match the details from your system with the order in our system. API reference can be found here.
Mutation
1
2
3
4
5
mutation OrderLink($orderLink: OrderLinkInput!) {
orderLink(input: $orderLink) {
id
}
}
Variables
1
2
3
4
5
6
7
{
"orderLink": {
"account": "4442523",
"accountOrderNumber": "P32940203",
"root": "root_0bfa01a6-202a-41cf-aeda-793aba1502de"
}
}
Response
1
2
3
4
5
6
7
8
9
{
"data": {
"orderLink": [
{
"id": "order_0bfa01a6-202a-41cf-aeda-793aba1502de"
}
]
}
}
5
Retrieve complete customs documentation for the order
Now that you have a matched order with Zonos, you can retrieve the enhanced customs documentation for an order. You can expect changes and updates to the item details, such as description, hs code, country of origin, prices, and more. API reference for this mutation can be found here.
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
mutation CustomsSpecGenerate(
$customsSpecGenerate: CustomsSpecGenerateInput!
) {
customsSpecGenerate(input: $customsSpecGenerate) {
cartons {
dimensionalUnit
height
length
weight
weightUnit
width
}
currency
customsItems {
amount
countryOfOrigin
description
hsCode
items {
productId
}
quantity
}
declarationStatement
id
metadata {
key
value
}
mode
parties
reasonForExport
trackingNumber
}
}
Variables
1
2
3
4
5
6
7
8
9
10
11
{
"customsSpecGenerate": {
"amountSubtotals": {
"items": 131.23,
"shipping": 20
},
"currency": "USD",
"root": "root_0bfa01a6-202a-41cf-aeda-793aba1502de",
"trackingNumber": "1z094A8329084085203"
}
}
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
{
"data": {
"customsSpecGenerate": {
"currency": "USD",
"cartons": [
{
"dimensionalUnit": "INCH",
"height": 6,
"length": 6,
"weight": 5,
"weightUnit": "POUND",
"width": 6
}
],
"customsItems": [
{
"amount": "32.75",
"countryOfOrigin": "MX",
"description": "Canvas shoes",
"hsCode": "6404.19.9010",
"items": [
{
"productId": "T596031"
}
],
"quantity": "4"
}
],
"declarationStatement": "These goods qualify for preferential treatment",
"id": "customs_clearance_be1901d7-d153-48fe-ae65-50c1ff806872",
"parties": [],
"reasonForExport": "PERSONAL_USE",
"trackingNumber": "1Z309AT490509209103"
}
}
}
Match your order to retrieve customs documentation with the Zonos Customs APIÂ
If you are a partner of Zonos and we share mutual customers, you can call the Customs API to update and retrieve complete customs documentation on an existing Zonos order. You can retrieve customs data on a shipment where the shipper may have provided missing or inaccurate information. For example, it is common for a shipper to provide a poor description or not provide a harmonized code. Zonos can add, supplement or improve information such as a description, hs code, country of origin, prices, and more.