Orders

Create or update an order

POST /api/v1/stores/{store_id}/orders

Upserts an order on (store_id, external_id).

Body

Field	Type	Required	Notes
`external_id`	string(255)	required	Your order id. Natural key.
`placed_at`	ISO 8601	required	When the order was placed.
`total_price`	number ≥ 0	required	Order total.
`currency`	string(3)	optional	ISO 4217, e.g. `EUR`.
`financial_status`	string(64)	optional	e.g. `pending`, `paid`.
`fulfillment_status`	string(64)	optional	e.g. `unfulfilled`.
`customer`	object	required	See below.
`customer.phone`	string	required	Matched to a WhatsApp contact.
`customer.external_id`	string(255)	optional	Your customer id.
`customer.first_name`	string(255)	optional
`customer.last_name`	string(255)	optional
`customer.email`	email(255)	optional
`customer.locale`	string(10)	optional	e.g. `fr`.
`customer.tags`	string[]	optional
`customer.lifetime_value`	integer ≥ 0	optional
`customer.orders_count`	integer ≥ 0	optional
`line_items`	object[]	optional	Free-form line items.
`tags`	string[]	optional
`metadata`	object	optional	Free-form.

Request

curl -X POST https://api.getkanal.com/api/v1/stores/123/orders \
  -H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORDER-1001",
    "placed_at": "2026-05-18T10:00:00Z",
    "total_price": 49.90,
    "currency": "EUR",
    "customer": { "phone": "+33612345678", "first_name": "Marie" }
  }'

Response `201 Created` / `200 OK`

{
  "external_id": "ORDER-1001",
  "store_id": 123,
  "total_price": "49.90",
  "currency": "EUR",
  "financial_status": null,
  "fulfillment_status": null,
  "tags": [],
  "created_at": "2026-05-18T10:00:00+00:00"
}

Update an order

PATCH /api/v1/stores/{store_id}/orders/{external_id}

Patches status/tags on an existing order. Returns 404 if the order does not exist. All fields optional; only provided fields change.

Field	Type	Notes
`financial_status`	string(64)	e.g. `paid`, `refunded`.
`fulfillment_status`	string(64)	e.g. `fulfilled`.
`tags`	string[]	Replaces tags.
`metadata`	object	Free-form.

curl -X PATCH https://api.getkanal.com/api/v1/stores/123/orders/ORDER-1001 \
  -H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
  -H "Content-Type: application/json" \
  -d '{ "financial_status": "paid" }'

Response 200 OK — same shape as the create response.