Kanal APIAPI reference
Shipments
Push fulfillment and tracking updates.
Create or update a shipment
POST /api/v1/stores/{store_id}/shipmentsUpserts a shipment on (store_id, external_id) and links it to an order via
order_external_id. Triggers shipping-notification automations.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
external_id | string(255) | required | Your shipment id. Natural key. |
order_external_id | string(255) | required | external_id of the related order. |
tracking_number | string(255) | optional | |
tracking_url | url(1024) | optional | |
carrier | string(255) | optional | e.g. Colissimo. |
status | enum | optional | One of pending, in_transit, delivered, failed, returned. |
metadata | object | optional | Free-form. |
Request
curl -X POST https://api.getkanal.com/api/v1/stores/123/shipments \
-H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
-H "Content-Type: application/json" \
-d '{
"external_id": "SHIP-9001",
"order_external_id": "ORDER-1001",
"tracking_number": "1Z999AA10123456784",
"tracking_url": "https://track.example.com/1Z999AA10123456784",
"carrier": "Colissimo",
"status": "in_transit"
}'Response 201 Created / 200 OK
{
"external_id": "SHIP-9001",
"store_id": 123,
"order_id": 4567,
"tracking_number": "1Z999AA10123456784",
"tracking_url": "https://track.example.com/1Z999AA10123456784",
"carrier": "Colissimo",
"status": "in_transit"
}order_id in the response is Kanal's internal numeric id for the linked
order — you reference orders by order_external_id on the way in, not this.
There is no PATCH for shipments — send a POST with the same external_id
to update tracking or status.