Overview
What the platform is, what an aggregator does, prices, shipments and the payment release gate.
The Kiuki platform connects the people who make and hold food and drink with the people who sell it to shoppers. This API is how you sell it.
Who uses it: aggregators
An aggregator sells platform products to its own shoppers: a shop, a marketplace, a meal-kit service, an AI assistant. You show what is on sale, take your shopper's payment your own way, and buy each order from the platform. Kiuki charges you per shipment, on the card you saved with Kiuki, and the platform has the order picked, packed and sent by the sites that hold the stock. kiuki.com is an aggregator too, through this same API.
The sellers are producers, brands and distributors; the sites (origins) are the warehouses and the producers' own premises that hold their stock and ship it.
Prices
- Product price, per pack: the seller's own price plus Kiuki's 10% distribution fee (VAT included), rounded half up per pack. It is the
unit_pricethe catalogue shows. There is no recommended retail price: what you charge your shoppers is yours to decide, within the law (alcohol in Scotland and Wales has a legal minimum price). - Fulfilment, per origin: each site's rate card, at cost, itemised in the quote (order handling, picking, packaging, coolant, carriage, surcharges).
- An order costs its products plus the fulfilment of each origin it ships from. Money is always a whole number of minor units with its currency, such as
{"minor": 4950, "currency": "GBP"}: never a float.
One shipment per origin and temperature
A quote, and the order made from it, is split into shipments: one per origin site and temperature. Chilled and frozen packs travel apart from ambient ones. Each shipment moves on its own:
| Status | Means | Who moves it |
|---|---|---|
pending | Placed. While awaiting_payment is true it is held: its site doesn't have it yet. | You, by ordering |
acknowledged | The site has it and will pick it. | The site |
picking, packed | Being picked, then packed. | The site |
dispatched | It left the site, with carrier and tracking. | The site |
delivered | Delivered. | The carrier or the site's system |
cancelled | Cancelled: by you while pending or acknowledged, by the site, or by Kiuki (it says why in cancel_reason). | You, the site or Kiuki |
failed | Kiuki staff gave up on it: it won't be sent, as if it had been cancelled. | Kiuki |
The order follows its shipments: placed, paid once its payment is secured, in_progress once a shipment is acknowledged, completed once every shipment went, was cancelled or failed and at least one went, cancelled once every shipment was cancelled or failed. It never moves back. A completed order may still have shipments that never went: check each shipment's status.
The payment release gate
Goods never leave a site before their payment is secured. Every shipment starts out held (awaiting_payment: true): its site can't see it. When you order, Kiuki authorises each shipment's cost on your saved card; once it is authorised the shipment goes to its site (shipment.released), and its acknowledgement and dispatch deadlines count from then. The payment is taken when the shipment is dispatched, and the authorisation is dropped if it is cancelled, so a cancellation never needs a refund.
If the payment can't be secured (a declined card), the shipment stays held. If it still isn't secured 24 hours after the order, Kiuki cancels it, with cancel_reason "payment not secured within 24 hours": its stock goes back on sale and nothing is taken from your card.
Live and sandbox
Your organisation has two worlds, each with its own keys and webhook endpoints, at the same address. Live keys buy real products from real sites. Sandbox keys see only the sandbox: invented producers and a site whose orders move on by themselves within minutes, paid with a pretend card. Neither ever sees the other.
Where next
- Authentication: API keys, scopes, and the plain refusals.
- Quickstart: Catalogue, quote, order and cancel, against the sandbox.
- Sandbox: The sandbox world: its listings, its pretend payments, its simulated site, and how it answers complaints.
- Webhooks: Events, signatures, retries, how fast deliveries come, turning off and resending.
- Complaints: Reporting a problem a shopper found with an order line, and following what Kiuki decides.
- Errors: Every status and error code, and what to do about it.
- Idempotency: Which requests are safe to send again, and how.
- Rate limits: How fast a key may call.
- API reference: Every endpoint, schema and webhook, from openapi.json.
The machine-readable description is /v1/openapi.json (OpenAPI 3.1), webhooks included.