Shipping labels | Validate a Declaration ID

If you create postal labels, you can call Zonos to retrieve complete customs declaration details when a user provides a Declaration ID. This eliminates the need for users to manually fill out customs documentation, creating a seamless shipping experience where duties are prepaid and customs forms are automatically populated.

Auto-fill customs declarations 

Follow the steps below to enable automatic customs declaration population using Declaration IDs from your platform.

1. Enable Declaration ID field in label creation flow

Add a Declaration ID field to your postal label creation interface. When users enter a valid Declaration ID, your platform can auto-populate the customs declaration, eliminating manual data entry.

2. Query Declaration ID status and customs declaration details

Use the following query to retrieve complete customs declaration data using the Declaration ID. This returns validation status along item details, values, HS codes, and recipient information when available

3. Handle response and auto-populate customs declaration

The API response includes validation status and customs data. Use the status information to determine whether the Declaration ID is valid, then auto-populate available customs data or prompt for manual entry.

Example responses

Valid Declaration ID with complete customs data:

{
  "data": {
    "declaration": {
      "id": "0mm1993s0mdcn",
      "status": "OPEN",
      "paymentStatus": "OPEN",
      "landedCost": {
        "id": "landed_cost_eabb13ab-df23-45df-9ce8-96dd29d396d1",
        "method": "DAP",
        "landedCostGuaranteeCode": "NOT_APPLICABLE",
        "amountSubtotals": {
          "duties": 0.0,
          "taxes": 0.0,
          "fees": 2.62,
          "landedCostTotal": 2.62
        }
      },
      "items": [
        {
          "id": "item_0mm199388v57g",
          "sku": "item_1",
          "productId": "item_1",
          "amount": 70.0,
          "currencyCode": "USD",
          "name": "Item 1",
          "hsCode": "9504.90.4000",
          "description": "This is the description for Item 1",
          "hsCodeSource": "TARIFF_COMPLETED",
          "countryOfOrigin": "CN",
          "quantity": 2,
          "measurements": [
            {
              "type": "WEIGHT",
              "value": 1,
              "unitOfMeasure": "POUND"
            }
          ]
        }
      ],
      "parties": [
        {
          "id": "party_0kesb32rw5hfa",
          "type": "DESTINATION",
          "person": {
            "firstName": "test",
            "lastName": "origin",
            "email": null,
            "phone": "1234567890"
          },
          "location": {
            "id": "location_c7882546-652e-49cb-81a4-98962a54c49f",
            "line1": "123 Test Street",
            "line2": "",
            "countryCode": "US",
            "postalCode": "84790"
          }
        },
        {
          "id": "party_0mjfz59bgg175",
          "type": "ORIGIN",
          "person": {
            "firstName": "test",
            "lastName": "destination",
            "email": null,
            "phone": "1234567890"
          },
          "location": {
            "id": "location_0mdzb9vk8bp7c",
            "line1": "998 Ridgehaven",
            "line2": null,
            "countryCode": "CA",
            "postalCode": "N0N 0N0"
          }
        }
      ]
    }
  }
}

4. Create the shipment

Process the label creation using either auto-populated data from a Declaration ID or manually entered declaration information.

5. Link tracking number to Declaration ID

After label creation, use the declarationShipmentCreate mutation to link the tracking number with the Declaration ID, ensuring proper duty payment validation and shipment tracking.

You can create a shipment tied to a Declaration ID by passing an array of trackingNumbers and the declarationID used for the shipment.

You can also create a shipment by passing the declarationID with details about the cartons, and items within the cartons, you can pass those in the shipmentCarton along with the trackingNumber for that carton.