Save Draft API

Create or update a draft shipment. Drafts are shipments with status: "draft" that can be resumed later. Drafts do not count toward generation limits until they are promoted to a full shipment.

Save Draft

POST /functions/v1/save-draft

Request Body

Field	Type	Required	Description
shipment_data	object	Yes	The shipment data to save. Must be a non-empty object.
shipment_ref	string	No	Human-readable reference (e.g., SHP-2026-001)
shipment_id	string	No	Existing draft shipment ID to update. If omitted, a new draft is created.

Example Request (Create New Draft)

curl -X POST "https://<project-ref>.supabase.co/functions/v1/save-draft" \
  -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" },
      "route": { "origin_country": "US" }
    }
  }'

Response (Create — 201)

{
  "shipment_id": "uuid-1234",
  "updated_at": "2026-04-13T10:00:00Z"
}

Example Request (Update Existing Draft)

curl -X POST "https://<project-ref>.supabase.co/functions/v1/save-draft" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_ANON_KEY" \
  -d '{
    "shipment_id": "uuid-1234",
    "shipment_data": {
      "exporter": { "name": "Acme Corp" },
      "importer": { "name": "Global Trade GmbH" },
      "route": { "origin_country": "US", "destination_country": "DE" }
    }
  }'

Response (Update — 200)

{
  "shipment_id": "uuid-1234",
  "updated_at": "2026-04-13T10:15:00Z"
}

Behavior

• Create: When shipment_id is omitted, a new shipment is inserted with status: "draft", generation_count: 0, and max_generations: 0.
• Update: When shipment_id is provided, the existing draft is updated with the new shipment_data and shipment_ref. Only drafts can be updated — shipments with any other status are rejected.
• The entire shipment_data object is replaced on update (not merged).

Error Codes

HTTP Status	Error Code	Description
400	KLV_DRAFT_001	shipment_data is required and must be an object
400	KLV_DRAFT_002	shipment_data must have at least one field
404	KLV_DRAFT_003	Draft not found (when updating with shipment_id)
400	KLV_DRAFT_004	Only draft shipments can be updated via save-draft
500	KLV_DRAFT_005	Failed to update draft
500	KLV_DRAFT_006	Failed to create draft