> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasiye.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a shipment

> Book a covered shipment for the authenticated workspace.

Creates a shipment in `pending` / `awaiting_payment`. The workspace must have PayChangu connected, and the route must be covered. API creates do not set `created_by`.

If the customer name and email already exist on the workspace, Kasiye links that customer. Otherwise it creates a customer record.

<ParamField path="body.customer_name" type="string" required>
  Customer display name.
</ParamField>

<ParamField path="body.customer_email" type="string" required>
  Customer email.
</ParamField>

<ParamField path="body.customer_id" type="number">
  Existing customer id on this workspace. Ignored if it belongs to another team.
</ParamField>

<ParamField path="body.customer_id_number" type="string">
  Optional national id or similar identifier.
</ParamField>

<ParamField path="body.pickup_address" type="string" required>
  Human-readable pickup address.
</ParamField>

<ParamField path="body.pickup_lat" type="number" required>
  Pickup latitude (`-90` to `90`).
</ParamField>

<ParamField path="body.pickup_lng" type="number" required>
  Pickup longitude (`-180` to `180`).
</ParamField>

<ParamField path="body.dropoff_address" type="string" required>
  Human-readable dropoff address.
</ParamField>

<ParamField path="body.dropoff_lat" type="number" required>
  Dropoff latitude (`-90` to `90`).
</ParamField>

<ParamField path="body.dropoff_lng" type="number" required>
  Dropoff longitude (`-180` to `180`).
</ParamField>

<ParamField path="body.weight_kg" type="number" required>
  Package weight in kilograms. Must be at least `0.01`.
</ParamField>

```bash theme={null}
curl -X POST https://api.kasiye.com/v1/shipments \
  -H "Authorization: Bearer shp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Acme Corp",
    "customer_email": "logistics@acme.com",
    "pickup_address": "Area 47, Lilongwe",
    "pickup_lat": -13.9626,
    "pickup_lng": 33.7741,
    "dropoff_address": "City Centre, Lilongwe",
    "dropoff_lat": -13.9833,
    "dropoff_lng": 33.7689,
    "weight_kg": 5
  }'
```

Returns `201` with the shipment wrapped in `data`.

<Warning>
  Connect PayChangu on the workspace first. Otherwise the API returns `422` on `paychangu`. Uncovered routes return `422` on `coverage` or `weight_kg`.
</Warning>