Skip to content
KiukiPlatform
Documentation

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_price the 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:

StatusMeansWho moves it
pendingPlaced. While awaiting_payment is true it is held: its site doesn't have it yet.You, by ordering
acknowledgedThe site has it and will pick it.The site
picking, packedBeing picked, then packed.The site
dispatchedIt left the site, with carrier and tracking.The site
deliveredDelivered.The carrier or the site's system
cancelledCancelled: by you while pending or acknowledged, by the site, or by Kiuki (it says why in cancel_reason).You, the site or Kiuki
failedKiuki 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.