Shipments API

Create, retrieve, and manage trade shipments.

Create Shipment

Creates a new shipment record.

POST /api/v1/shipments

Request Body

{
  "shipment_ref": "SHP-2026-001",
  "exporter": {
    "name": "Acme Corp",
    "address": "123 Export St",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US",
    "tax_ids": {
      "ein": "12-3456789"
    },
    "contact_email": "export@acme.com"
  },
  "importer": {
    "name": "Global Trade GmbH",
    "address": "456 Import Str",
    "city": "Hamburg",
    "postal_code": "20095",
    "country": "DE",
    "tax_ids": {
      "eori": "DE123456789012345"
    }
  },
  "route": {
    "origin_country": "US",
    "destination_country": "DE",
    "transport_mode": "sea",
    "incoterms": "CIF",
    "port_of_loading": "USLAX",
    "port_of_discharge": "DEHAM",
    "vessel_name": "MSC Ravenna",
    "etd": "2026-04-15",
    "eta": "2026-05-02"
  },
  "goods": {
    "currency": "USD",
    "total_value": 25000,
    "line_items": [
      {
        "description": "Electronic integrated circuits",
        "hs_code": "8542.31.0000",
        "quantity": 500,
        "unit": "PCS",
        "unit_price": 50,
        "origin_country": "US",
        "net_weight_kg": 25,
        "gross_weight_kg": 28,
        "is_hazardous": false
      }
    ]
  },
  "packaging": {
    "total_packages": 5,
    "total_gross_weight_kg": 30,
    "packages": [
      {
        "type": "CARTON",
        "quantity": 5,
        "gross_weight_kg": 6,
        "length_cm": 40,
        "width_cm": 30,
        "height_cm": 20
      }
    ]
  },
  "documents_requested": ["COMMERCIAL_INVOICE", "PACKING_LIST"]
}

Response

{
  "id": "shp_a1b2c3d4",
  "shipment_ref": "SHP-2026-001",
  "status": "draft",
  "created_at": "2026-03-31T10:00:00Z",
  "team_id": "team_xyz"
}

Get Shipment

GET /api/v1/shipments/:id

Response

Returns the full shipment object including all nested data.

List Shipments

GET /api/v1/shipments

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
status	string	Filter by status: draft, validated, generated, failed
search	string	Search by shipment ref or party names

Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}