API reference

Customs

Customs declarations for shipments that cross a border.

Endpoints

POST /customs/declarations
GET /customs/declarations/{id}

Create a customs declaration

POST /v1/customs/declarations

Describes what is in a cross-border shipment: each item's description, quantity, value, HS code, country of origin and weight. Pass the returned id as customs_declaration_id when you get rates and buy the label. Look up HS codes with GET /v1/public/hs-codes?q=… (add country=US for 10-digit US codes).

Request body

contents_type • Required string

merchandise, documents, gift, commercial_sample, returned_goods or other.
declaration_currency • Required string

Currency of the item values. Use one currency for the whole declaration.
from_country • Required string

Ship-from country code.
incoterm • Required string

Who pays duties and taxes: DAP (the recipient, on delivery) or DDP (you, prepaid with the label, where GET /v1/shipments/duties-availability says it is offered).
items • Required array of objects

Every item in the shipment.
Each item · 13
- country_of_origin • Required string
  
  Two-letter code of the country where the item was made.
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- description • Required string
  
  What the item is, specifically ("cotton t-shirt", not "clothing").
- hs_code • Required string
  
  Harmonized System code. Find one with GET /v1/public/hs-codes?q=….
- net_weight_g • Required integer
  
  Weight of all units of this item, in grams.
- package_index • Required integer
  
  Which box the item is in (from 0).
- position • Required integer
  
  Order of the item in the list (from 0).
- quantity • Required integer
  
  How many.
- unit_value_cents • Required integer
  
  Value of one unit, in cents of currency.
- gross_weight_g integer
  
  Weight including packaging, in grams (optional).
- hs_code_version_id uuid
  
  Leave out; set by the dashboard's HS-code picker.
- manufacturer_country string
  
  Country of the manufacturer, if different from the origin.
- sku string
  
  Your product code.
signed_by • Required string

Name of the person certifying the declaration.
to_country • Required string

Ship-to country code.
hs_code_version_id uuid

Leave out; set by the dashboard's HS-code picker.
invoice_date date

Invoice date (YYYY-MM-DD).
invoice_number string

Your commercial invoice or order number.
non_delivery_option string

If it cannot be delivered: return (default) or abandon.
reason_for_export string

sale, gift, sample, repair, return, personal or other.
restrictions_note string

Any restriction or licence to declare.
tax_ids any

Tax numbers where the destination asks for them, e.g. {"IOSS": "…", "recipient": "…", "recipient_type": "personal"}. Brazil, Argentina, Israel and some other countries require the recipient's number.

Response in `data`

contents_type • Required string
created_at • Required timestamp

When it was created (ISO 8601, UTC).
declaration_currency • Required string
eei_required • Required boolean
id • Required uuid
incoterm • Required string
items • Required array of objects
Each item · 15
- country_of_origin • Required string
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- description • Required string
- hs_code • Required string
  
  Harmonized System code.
- id • Required uuid
- net_weight_g • Required integer
- package_index • Required integer
- position • Required integer
- quantity • Required integer
  
  How many.
- unit_value_cents • Required integer
- gross_weight_g integer
- hs_code_version_id uuid
  
  Leave out; set by the dashboard's HS-code picker.
- manufacturer_country string
- sku string
  
  Your product code.
non_delivery_option • Required string
signed_by • Required string
tax_ids • Required any
total_value_cents • Required integer
updated_at • Required timestamp

When it last changed (ISO 8601, UTC).
eei_reason string
hs_code_version_id uuid

Leave out; set by the dashboard's HS-code picker.
invoice_date date
invoice_number string
reason_for_export string
restrictions_note string
shipment_id uuid

POST /v1/customs/declarations

curl -X POST "https://api.parcelhub.ca/v1/customs/declarations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "contents_type": "merchandise",
  "declaration_currency": "string",
  "from_country": "string",
  "incoterm": "DAP",
  "invoice_date": "2026-11-03",
  "invoice_number": "string",
  "items": [
    {
      "country_of_origin": "string",
      "currency": "CAD",
      "description": "string",
      "gross_weight_g": 1,
      "hs_code": "6109.10",
      "manufacturer_country": "string",
      "net_weight_g": 1,
      "package_index": 1,
      "position": 1,
      "quantity": 1,
      "sku": "string",
      "unit_value_cents": 1299
    }
  ],
  "non_delivery_option": "return",
  "reason_for_export": "sale",
  "restrictions_note": "string",
  "signed_by": "string",
  "to_country": "string"
}'

Response

{
  "ok": true,
  "data": {
    "contents_type": "string",
    "created_at": "2026-10-31T15:04:05Z",
    "declaration_currency": "string",
    "eei_reason": "string",
    "eei_required": true,
    "hs_code_version_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "incoterm": "string",
    "invoice_date": "2026-11-03",
    "invoice_number": "string",
    "items": [
      {
        "country_of_origin": "string",
        "created_at": "2026-10-31T15:04:05Z",
        "currency": "CAD",
        "description": "string",
        "gross_weight_g": 1,
        "hs_code": "6109.10",
        "hs_code_version_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "manufacturer_country": "string",
        "net_weight_g": 1,
        "package_index": 1,
        "position": 1,
        "quantity": 1,
        "sku": "string",
        "unit_value_cents": 1299
      }
    ],
    "non_delivery_option": "string",
    "reason_for_export": "string",
    "restrictions_note": "string",
    "shipment_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "signed_by": "string",
    "tax_ids": null,
    "total_value_cents": 1299,
    "updated_at": "2026-10-31T15:04:05Z"
  },
  "request_id": "01JBX7Q2…"
}

Get a customs declaration

GET /v1/customs/declarations/{id}

One customs declaration with its items.

Path parameters

id • Required string

Response in `data`

contents_type • Required string
created_at • Required timestamp

When it was created (ISO 8601, UTC).
declaration_currency • Required string
eei_required • Required boolean
id • Required uuid
incoterm • Required string
items • Required array of objects
Each item · 15
- country_of_origin • Required string
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- description • Required string
- hs_code • Required string
  
  Harmonized System code.
- id • Required uuid
- net_weight_g • Required integer
- package_index • Required integer
- position • Required integer
- quantity • Required integer
  
  How many.
- unit_value_cents • Required integer
- gross_weight_g integer
- hs_code_version_id uuid
  
  Leave out; set by the dashboard's HS-code picker.
- manufacturer_country string
- sku string
  
  Your product code.
non_delivery_option • Required string
signed_by • Required string
tax_ids • Required any
total_value_cents • Required integer
updated_at • Required timestamp

When it last changed (ISO 8601, UTC).
eei_reason string
hs_code_version_id uuid

Leave out; set by the dashboard's HS-code picker.
invoice_date date
invoice_number string
reason_for_export string
restrictions_note string
shipment_id uuid

GET /v1/customs/declarations/{id}

1
2

curl "https://api.parcelhub.ca/v1/customs/declarations/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "contents_type": "string",
    "created_at": "2026-10-31T15:04:05Z",
    "declaration_currency": "string",
    "eei_reason": "string",
    "eei_required": true,
    "hs_code_version_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "incoterm": "string",
    "invoice_date": "2026-11-03",
    "invoice_number": "string",
    "items": [
      {
        "country_of_origin": "string",
        "created_at": "2026-10-31T15:04:05Z",
        "currency": "CAD",
        "description": "string",
        "gross_weight_g": 1,
        "hs_code": "6109.10",
        "hs_code_version_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "manufacturer_country": "string",
        "net_weight_g": 1,
        "package_index": 1,
        "position": 1,
        "quantity": 1,
        "sku": "string",
        "unit_value_cents": 1299
      }
    ],
    "non_delivery_option": "string",
    "reason_for_export": "string",
    "restrictions_note": "string",
    "shipment_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "signed_by": "string",
    "tax_ids": null,
    "total_value_cents": 1299,
    "updated_at": "2026-10-31T15:04:05Z"
  },
  "request_id": "01JBX7Q2…"
}

Customs

Create a customs declaration

Request body

Response in data

Get a customs declaration

Path parameters

Response in data

Response in `data`

Response in `data`