Shipments API

Create and retrieve trade shipments. Shipments track the lifecycle of a trade document set, including generation counts and validation state.

Create Shipment

Creates a new shipment record with tier-based generation limits.

POST /functions/v1/create-shipment

Request Body

Field	Type	Required	Description
shipment_data	object	Yes	The full shipment data object
shipment_ref	string	No	Human-readable reference (e.g., SHP-2026-001)

Example Request

curl -X POST "https://<project-ref>.supabase.co/functions/v1/create-shipment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_ANON_KEY" \
  -d '{
    "shipment_ref": "SHP-2026-001",
    "shipment_data": {
      "exporter": { "name": "Acme Corp" },
      "importer": { "name": "Global Trade GmbH" },
      "route": { "origin_country": "US", "destination_country": "DE" },
      "goods": { "currency": "USD", "total_value": 25000, "line_items": [] }
    }
  }'

Response (201)

{
  "shipment_id": "uuid-1234",
  "shipment_ref": "SHP-2026-001",
  "status": "created",
  "generation_count": 0,
  "max_generations": 10,
  "created_at": "2026-04-13T10:00:00Z"
}

Tier-Based Generation Limits

The max_generations value is determined by the team's subscription tier:

Tier	Max Generations
Free	2
Starter	5
Growth	10
Scale	20

Each call to generate-documents with a shipment_id increments the generation_count. When generation_count >= max_generations, further generation attempts return 429.

Error Codes

HTTP Status	Error Code	Description
400	KLV_SHIP_001	shipment_data is required
500	KLV_SHIP_002	Failed to create shipment (internal error)

---

Get Shipment

Retrieve a single shipment by ID, including its full generation history.

GET /functions/v1/get-shipment?id=<shipment-id>

Query Parameters

Parameter	Type	Required	Description
id	string	Yes*	Shipment UUID. Required unless status is provided.
status	string	No	Filter by status to list shipments (e.g., ?status=draft). When provided without id, returns a list.

*Either id or status must be provided.

Example Request (Single Shipment)

curl "https://<project-ref>.supabase.co/functions/v1/get-shipment?id=uuid-1234" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "apikey: YOUR_ANON_KEY"

Response (Single Shipment — 200)

{
  "id": "uuid-1234",
  "shipment_ref": "SHP-2026-001",
  "shipment_data": { "..." },
  "status": "generated",
  "generation_count": 2,
  "max_generations": 10,
  "current_validation_record_id": "uuid-val-5678",
  "current_validation_hash": "a1b2c3d4...",
  "created_by": "user-uuid",
  "created_at": "2026-04-13T10:00:00Z",
  "updated_at": "2026-04-13T12:30:00Z",
  "generation_history": [
    {
      "id": "uuid-hist-002",
      "generation_number": 2,
      "document_types": ["COMMERCIAL_INVOICE", "BILL_OF_LADING"],
      "validation_hash": "a1b2c3d4...",
      "shipment_data_snapshot": { "..." },
      "flattened_urls": {
        "COMMERCIAL_INVOICE": "https://..."
      },
      "created_at": "2026-04-13T12:30:00Z"
    },
    {
      "id": "uuid-hist-001",
      "generation_number": 1,
      "document_types": ["COMMERCIAL_INVOICE", "PACKING_LIST"],
      "validation_hash": "x9y8z7w6...",
      "shipment_data_snapshot": { "..." },
      "flattened_urls": null,
      "created_at": "2026-04-13T10:05:00Z"
    }
  ]
}

Example Request (List by Status)

curl "https://<project-ref>.supabase.co/functions/v1/get-shipment?status=draft" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "apikey: YOUR_ANON_KEY"

Response (List Mode — 200)

Returns up to 50 shipments ordered by updated_at descending.

{
  "shipments": [
    {
      "id": "uuid-1234",
      "shipment_ref": "SHP-2026-001",
      "shipment_data": { "..." },
      "status": "draft",
      "created_by": "user-uuid",
      "created_at": "2026-04-13T10:00:00Z",
      "updated_at": "2026-04-13T11:00:00Z"
    }
  ]
}

Shipment Statuses

Status	Description
created	Shipment created, not yet validated or generated
draft	Saved as draft via the save-draft endpoint
validated	Validation passed
validation_failed	Validation failed
generated	Documents generated (at least once)

Error Codes

HTTP Status	Error Code	Description
400	KLV_SHIP_003	id query parameter is required (when no status filter)
404	KLV_SHIP_004	Shipment not found
500	KLV_SHIP_005	Failed to list shipments