Quickstart
Catalogue, quote, order and cancel, against the sandbox.
From nothing to a delivered order, against the sandbox: nothing real is bought, and the sandbox's site moves the order on by itself within minutes. You need curl; any HTTP client will do.
1. A sandbox key
Once your application is approved, sign in, go to API keys, and make a sandbox key with every scope. Keep it in your shell:
export KIUKI_KEY=kp_... curl -s https://platform.kiuki.com/v1/whoami -H "Authorization: Bearer $KIUKI_KEY"
The answer says "sandbox": true.
2. What is on sale
curl -s "https://platform.kiuki.com/v1/catalogue?market=GB" -H "Authorization: Bearer $KIUKI_KEY"
The sandbox's listings come back with their packs, food labels, unit prices and availability. Their ids never change:
| Listing | Pack | Temperature | Unit price |
|---|---|---|---|
6b69756b-5ab0-4000-8000-000000000401 | Oat bars, case of 12 (Sandbox Oats) | ambient | £19.80 |
6b69756b-5ab0-4000-8000-000000000402 | Strawberry jam 340 g, case of 6 (Sandbox Preserves) | ambient | £26.40 |
6b69756b-5ab0-4000-8000-000000000403 | Mature cheddar 200 g, case of 10 (Sandbox Dairy) | chilled | £33.00 |
3. A quote
Price a basket delivered to a postcode. The quote holds for 10 minutes:
curl -s https://platform.kiuki.com/v1/quotes -H "Authorization: Bearer $KIUKI_KEY" -H "Content-Type: application/json" -d '{
"market": "GB",
"ship_to": {"country": "GB", "postcode": "SW1A 1AA"},
"lines": [{"listing_id": "6b69756b-5ab0-4000-8000-000000000401", "qty": 2}]
}'
It is itemised per origin: products, then each origin's fulfilment charges. Note its id.
4. The order
curl -s https://platform.kiuki.com/v1/orders -H "Authorization: Bearer $KIUKI_KEY" -H "Content-Type: application/json" -d '{
"quote_id": "QUOTE_ID",
"external_ref": "test-1001",
"ship_to": {"name": "Alex Example", "lines": ["10 Test Road"], "city": "London", "postcode": "SW1A 1AA", "country": "GB"},
"contact": {"email": "alex@example.com"}
}'
201 Created, with the order. external_ref is your own order id: sending the same request again returns the same order (200), so a retry after a timeout never orders twice (idempotency).
5. Watch it move
curl -s https://platform.kiuki.com/v1/orders/ORDER_ID -H "Authorization: Bearer $KIUKI_KEY"
At first each shipment is pending with awaiting_payment: true. Within seconds the sandbox pays for it with a pretend card: the order is paid and the shipment goes to Sandbox Warehouse 1. Then, about once a minute, it moves on: acknowledged, picking, packed, dispatched (carrier "Sandbox Parcels" and a tracking number), delivered. Once every shipment has been dispatched the order is completed. Better than asking again and again: register a webhook endpoint for your sandbox and be told.
6. Cancel one
Place another order, then cancel it within its first minute or two, while its shipment is still pending or acknowledged:
curl -s -X POST https://platform.kiuki.com/v1/orders/ORDER_ID/cancel -H "Authorization: Bearer $KIUKI_KEY" \
-H "Content-Type: application/json" -d '{"reason": "customer changed their mind"}'
Its stock goes back on sale and the pretend payment is dropped. Once a shipment is being picked it can't be cancelled: the answer is 409 not_cancellable.
To cancel one shipment of an order and let the others go on, send the same request to /v1/orders/ORDER_ID/shipments/SHIPMENT_ID/cancel, by the same rules.
7. Going live
Make a live key with the same scopes and point the same code at it. Before your first live order, Kiuki sends you a link to save the card your orders are paid with.