Skip to content
KiukiPlatform
Documentation

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:

ListingPackTemperatureUnit price
6b69756b-5ab0-4000-8000-000000000401Oat bars, case of 12 (Sandbox Oats)ambient£19.80
6b69756b-5ab0-4000-8000-000000000402Strawberry jam 340 g, case of 6 (Sandbox Preserves)ambient£26.40
6b69756b-5ab0-4000-8000-000000000403Mature 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.