Zonos logo
DOCS

Match orders to get customs info graphql

/

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.

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

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"
        }
    }
}