TradeShipment Schema

The core data model for trade shipments in Klervex.

Full Schema

{
  "type": "object",
  "required": ["exporter", "importer", "route", "goods"],
  "properties": {
    "shipment_ref": {
      "type": "string",
      "description": "User-provided shipment reference number"
    },
    "exporter": { "$ref": "#/definitions/Party" },
    "importer": { "$ref": "#/definitions/Party" },
    "notify_party": { "$ref": "#/definitions/Party" },
    "route": { "$ref": "#/definitions/Route" },
    "goods": { "$ref": "#/definitions/Goods" },
    "packaging": { "$ref": "#/definitions/Packaging" },
    "documents_requested": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "COMMERCIAL_INVOICE",
          "PACKING_LIST",
          "BILL_OF_LADING",
          "CERTIFICATE_OF_ORIGIN",
          "PROFORMA_INVOICE",
          "DANGEROUS_GOODS",
          "AIR_WAYBILL"
        ]
      }
    }
  }
}

Top-Level Fields

Field	Type	Required	Description
shipment_ref	string	No	Your reference number
exporter	Party	Yes	Exporting company/person
importer	Party	Yes	Importing company/person
notify_party	Party	No	Third party to notify
route	Route	Yes	Shipping route details
goods	object	Yes	Line items and values
packaging	Packaging	No	Package details
documents_requested	string[]	No	Document types to generate

Goods Object

Field	Type	Required	Description
currency	string	Yes	ISO 4217 currency code (e.g., USD, EUR)
total_value	number	Yes	Total shipment value
line_items	LineItem[]	Yes	Array of line items

Example

{
  "shipment_ref": "SHP-2026-001",
  "exporter": {
    "name": "Acme Corp",
    "address": "123 Export St",
    "city": "Los Angeles",
    "country": "US",
    "tax_ids": { "ein": "12-3456789" }
  },
  "importer": {
    "name": "Global Trade GmbH",
    "address": "456 Import Str",
    "city": "Hamburg",
    "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"
  },
  "goods": {
    "currency": "USD",
    "total_value": 25000,
    "line_items": [
      {
        "description": "Electronic components",
        "hs_code": "8542.31.0000",
        "quantity": 500,
        "unit": "PCS",
        "unit_price": 50,
        "origin_country": "US",
        "net_weight_kg": 25
      }
    ]
  },
  "packaging": {
    "total_packages": 5,
    "total_gross_weight_kg": 30
  },
  "documents_requested": ["COMMERCIAL_INVOICE", "PACKING_LIST"]
}