Kanal APIAPI reference
Overview
Conventions shared by every commerce endpoint.
The commerce API has 7 endpoints across 4 resources. They all share the same conventions below.
Base URL & path
https://api.getkanal.com/api/v1/stores/{store_id}/{resource}{store_id} is the numeric id issued with your API key. Every request is
scoped to that store.
Endpoints at a glance
| Method | Path | Resource |
|---|---|---|
POST | /orders | Create or update an order |
PATCH | /orders/{external_id} | Update order status |
POST | /checkouts | Create or update a checkout |
PATCH | /checkouts/{external_id} | Update checkout status |
POST | /customers | Create or update a customer |
DELETE | /customers/{external_id} | Delete a customer (GDPR) |
POST | /shipments | Create or update a shipment |
Conventions
- Auth —
Authorization: Bearer <key>, scoped per store. See Authentication. - Content type —
application/jsonon every request with a body. - Idempotency —
POSTupserts on(store_id, external_id).201= created,200= updated. See Idempotency. - Errors — JSON body,
422for validation. See Errors. - Rate limit — 60 requests / minute / store.
Type notation
| Notation | Meaning |
|---|---|
required | Must be present and non-null |
optional | May be omitted or null |
string(3) | String with exact/max length |
ISO 8601 | e.g. 2026-05-18T10:00:00Z |
number | Decimal, ≥ 0 for prices |
Messaging & templates — sending WhatsApp messages and templates uses a
separate, older API (/api/v1/messages/send, /api/v1/templates,
/api/v1/me). It is not part of the commerce ingestion API documented here;
ask your Kanal contact for its reference.