Skip to content
KiukiPlatform
Documentation

API reference

Every endpoint, schema and webhook, from openapi.json.

Kiuki platform API, version 1.0.0. Drawn from /v1/openapi.json (OpenAPI 3.1), so it always says what the API does. Address: https://platform.kiuki.com.

The Kiuki platform API lets aggregators (kiuki.com, other shops and AI assistants) sell packs from many sellers, shipped by the sites that hold them.

How buying works:

  1. GET /v1/markets, then GET /v1/catalogue?market=GB for what is on sale: packs, food labels, unit prices and availability.
  2. POST /v1/quotes with listing ids, quantities and the delivery country and postcode. The quote is itemised per origin (one shipment per origin site and temperature: chilled and frozen travel apart from ambient) and holds for 10 minutes.
  3. POST /v1/orders with the quote id, your own order reference (external_ref) and the address. Sending the same external_ref again returns the same order, so retries are safe. kiuki.com also sends payment_ref, the PaymentIntent its shopper paid with; other aggregators are charged by Kiuki per shipment and leave it out.
  4. GET /v1/orders/{id} for status and tracking; POST /v1/orders/{id}/cancel while its shipments haven't started.
  5. POST /v1/complaints when a shopper reports a problem with a line whose shipment has left the site (allergen, label, safety, damaged, missing); Kiuki follows it up with the seller.

Prices: a unit price is the seller's own price per pack plus Kiuki's 10% distribution fee (VAT included), rounded half up per pack. Fulfilment is each origin's rate card, at cost. Money is always integer minor units with an ISO 4217 currency, never a float.

Authentication: send Authorization: Bearer kp_... with a platform API key. Each operation names the scope it needs (catalogue:read, quote:write, order:write, order:read, webhooks:write, complaint:write); a key without it gets HTTP 403 with a message naming the scope. A key whose organisation isn't approved (or is suspended) gets 403 on every operation. Each key may send 20 requests a second on average, in bursts of up to 100; beyond that it gets 429 rate_limited.

Sandbox: a sandbox key works exactly like a live one, at the same address, in a world of its own: invented producers and a site whose orders move on by themselves within minutes, paid with a pretend card. It never sees live listings, and live keys never see it. Make sandbox keys in the developer portal (/dashboard).

Webhooks: register https endpoints (POST /v1/webhook-endpoints) to be told as your orders and shipments move, in signed POSTs (Kiuki-Signature). The webhooks section of this document lists the events. Guides: /docs.

Errors are JSON: {"error": "<code>", "message": "<plain English>"}. Branch on error; show message to people. A 503 means nothing was done: send the same request again in a moment.

Contents

catalogue

Markets and what is on sale in them.

GET /v1/catalogue

What is on sale in a market scope: catalogue:read

Live listings in a market, a page at a time: pack name, brand, size, GTINs, temperature, alcohol, food labels for the market, unit price per pack and availability. Listings without a current price aren't shown. Alcohol from an origin in Scotland or Wales has a legal minimum price (minimum unit pricing): the platform keeps unit_price at or above it, and takes a listing off sale before a new rate would put it below. An aggregator that sells to its shoppers at any other price is responsible for its own compliance with minimum pricing law.

Parameters
NameInTypeDescription
market requiredquerystringMarket code, e.g. GB.
cursorquerystringnext_cursor from the previous page.
limitqueryintegerItems per page, 1 to 200 (default 50).
Responses
StatusDescriptionBody
200OKCataloguePage
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: listCatalogue

GET /v1/catalogue/{listing_id}

One listing scope: catalogue:read

A live listing with its labels, unit price and availability.

Parameters
NameInTypeDescription
listing_id requiredpathstringThe listing's id.
Responses
StatusDescriptionBody
200OKCatalogueItem
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getCatalogueItem

GET /v1/markets

Markets any valid key

Every market with its country, currency, languages and time zone. Only active markets can be quoted and ordered. Any valid key may call it.

Responses
StatusDescriptionBody
200OKMarketList
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: listMarkets

quotes

Itemised prices for a basket, delivered.

POST /v1/quotes

Price a basket, delivered scope: quote:write

Prices listings for delivery to a country and postcode. Each pack costs its unit price (the seller's price plus Kiuki's 10% fee). Lines are grouped into future shipments, one per origin site and temperature, and each is charged fulfilment from its origin's rate card, at cost: itemised charges, parcels and the delivery service. The quote holds for 10 minutes. A line above the available quantity, or from an origin whose stock data is over an hour old, is refused with a 409 naming the line; an origin that refuses its shipment (its minimum order isn't met, it can't deliver to the postcode, it has no rate card in force) is marked blocked with the reason, and the quote can't be ordered. The quote says how many parcels the basket makes and, when its shipments come from more than one site, offers its one-origin alternatives (see QuoteWithAlternatives).

Request body (required): QuoteRequest

Responses
StatusDescriptionBody
201CreatedQuoteWithAlternatives
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: createQuote

POST /v1/quotes/{id}/one-origin

Quote a basket again from one origin scope: quote:write

Quotes the basket of one of your quotes again with every pack from one site (one of its one_origin_alternatives): the same packs, listed live at that site, in the same quantities, for delivery to the same country and postcode. Lines of the same pack become one, under the number of the first; every line keeps the number it had on the quote. The answer is a new quote, priced and checked as POST /v1/quotes prices one (it holds for 10 minutes): order that one with POST /v1/orders. The quote asked from may have expired. A pack the site doesn't sell, or can't sell now, is refused with a 409 naming the line; a site that isn't taking orders is a 409 origin_unavailable.

Parameters
NameInTypeDescription
id requiredpathstringThe id of one of your quotes.

Request body (required): OneOriginRequest

Responses
StatusDescriptionBody
201CreatedQuoteWithAlternatives
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: quoteOneOrigin

orders

Placing, following and cancelling orders.

GET /v1/orders

Your orders scope: order:read

Your organisation's orders, newest first, with each shipment's status and tracking.

Parameters
NameInTypeDescription
external_refquerystringOnly the order with your reference.
statusquerystringOnly orders with this status: placed, paid, in_progress, completed or cancelled.
cursorquerystringnext_cursor from the previous page.
limitqueryintegerOrders per page, 1 to 200 (default 50).
Responses
StatusDescriptionBody
200OKOrderPage
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: listOrders

POST /v1/orders

Place an order from a quote scope: order:write

Places an order from one of your quotes before it expires, with your own reference and the delivery address (same country and postcode as the quote). Stock is allocated for every shipment, or nothing is ordered (409 out_of_stock). Idempotent on external_ref: sending the same request again returns the same order with 200 instead of 201. A quote can be ordered once.

kiuki.com sends payment_ref, the PaymentIntent its shopper paid with on kiuki.com's checkout: it is checked before anything is ordered (402 payment_refused when it can't pay for the order, 409 payment_used when it already paid for another), and an order without it is refused (400). Other aggregators must leave it out: Kiuki takes their payment per shipment.

Each shipment starts out awaiting payment (awaiting_payment true): its site gets it only once its payment is secured, and its deadlines then count from that moment.

Request body (required): PlaceOrderRequest

Responses
StatusDescriptionBody
200OKOrderWithAgeChecks
201CreatedOrderWithAgeChecks
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
402The payment named can't pay for this. The message says why.Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error
503A service the request needs couldn't be reached (stripe_unavailable), or isn't set up on this server (payments_unavailable), so nothing was done. Safe to retry in a moment with the same request.Error

operationId: placeOrder

GET /v1/orders/{id}

One order scope: order:read

An order with its shipments: status, deadlines, charges, lines and tracking.

Parameters
NameInTypeDescription
id requiredpathstringThe order's id.
Responses
StatusDescriptionBody
200OKOrderWithAgeChecks
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getOrder

POST /v1/orders/{id}/cancel

Cancel an order scope: order:write

Cancels the order's shipments that are still pending or acknowledged and gives their stock back. Shipments already being picked, or gone, can't be cancelled and stay as they are; when every shipment is cancelled, so is the order. Payment for a cancelled shipment is released (or, for kiuki.com, its sellers and site aren't paid for it). Cancelling a cancelled order returns it unchanged. 409 not_cancellable when nothing can be cancelled.

Parameters
NameInTypeDescription
id requiredpathstringThe order's id.

Request body (optional): CancelRequest

Responses
StatusDescriptionBody
200OKOrderWithAgeChecks
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: cancelOrder

POST /v1/orders/{id}/shipments/{shipment_id}/cancel

Cancel one shipment of an order scope: order:write

Cancels one shipment of the order while it is still pending or acknowledged, and gives its stock back. The order's other shipments go on as they are. The rules are those of cancelling the whole order: a shipment already being picked, or gone, can't be cancelled (409 not_cancellable); payment for a cancelled shipment is released (or, for kiuki.com, its sellers and site aren't paid for it, and kiuki.com refunds its shopper for it); when no shipment of the order is left that isn't cancelled, the order is cancelled too. Cancelling a cancelled shipment returns the order unchanged, so sending the request again is safe. 404 when the order isn't yours or the shipment isn't the order's.

Parameters
NameInTypeDescription
id requiredpathstringThe order's id.
shipment_id requiredpathstringThe id of the order's shipment to cancel.

Request body (optional): CancelRequest

Responses
StatusDescriptionBody
200OKOrderWithAgeChecks
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: cancelShipment

webhooks

Endpoints that are told as orders and shipments move, and their deliveries.

GET /v1/webhook-endpoints

Your webhook endpoints scope: webhooks:write

Every endpoint of your organisation (a sandbox key's: the sandbox's), oldest first. Secrets are never shown again.

Responses
StatusDescriptionBody
200OKWebhookEndpointList
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: listWebhookEndpoints

POST /v1/webhook-endpoints

Register a webhook endpoint scope: webhooks:write

Registers an https address to be sent the events it wants (all of them when events is left out; an empty list is refused, 400). The address must be public: one that can't be found, or that leads to a private, loopback, link-local or other non-public address, is refused (400). The answer holds the endpoint's secret, which signs every delivery (the Kiuki-Signature header): it is shown this once only. An organisation has at most 10 endpoints (409).

Request body (required): WebhookEndpointRequest

Responses
StatusDescriptionBody
201CreatedWebhookEndpointCreated
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: createWebhookEndpoint

GET /v1/webhook-endpoints/{id}

One webhook endpoint scope: webhooks:write

An endpoint, whether it is on, and how its deliveries are going.

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.
Responses
StatusDescriptionBody
200OKWebhookEndpoint
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getWebhookEndpoint

PATCH /v1/webhook-endpoints/{id}

Change a webhook endpoint scope: webhooks:write

Changes the fields sent and leaves the others. enabled false turns the endpoint off: nothing is sent to it, its waiting deliveries are skipped, and the events from while it is off wait in its delivery log, skipped. enabled true turns it on again, afresh, after you or Kiuki turned it off, and sends it up to 100 of the deliveries skipped in the last 30 days, the oldest first, each with a day of retries (only the events it still wants). Any more stay skipped: send the ones you need again one by one (resend), or read GET /v1/orders. An empty events list is refused (400): leave events out to keep them as they are.

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.

Request body (required): WebhookEndpointUpdate

Responses
StatusDescriptionBody
200OKWebhookEndpoint
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: updateWebhookEndpoint

DELETE /v1/webhook-endpoints/{id}

Delete a webhook endpoint scope: webhooks:write

Deletes the endpoint and its delivery log.

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.
Responses
StatusDescriptionBody
200OKWebhookEndpointDeleted
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: deleteWebhookEndpoint

GET /v1/webhook-endpoints/{id}/deliveries

An endpoint's deliveries scope: webhooks:write

The endpoint's most recent deliveries, newest first: each event sent to it, whether it was delivered, and its last attempt. Kept 30 days.

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.
limitqueryintegerHow many, 1 to 200 (default 50).
Responses
StatusDescriptionBody
200OKWebhookDeliveryList
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: listWebhookDeliveries

GET /v1/webhook-endpoints/{id}/deliveries/{delivery_id}

One delivery, with its attempts scope: webhooks:write

What the delivery sends (the event, exactly as each attempt sent it) and every attempt: when, the answer's status, and the start of its body.

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.
delivery_id requiredpathstringThe delivery's id.
Responses
StatusDescriptionBody
200OKWebhookDeliveryDetail
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getWebhookDelivery

POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/resend

Send a delivery again scope: webhooks:write

Sends the event again now, with a day of retries from now: one that failed, was skipped while the endpoint was off, or was delivered and needs handling again. The endpoint must be on (409), and a delivery is sent again at most 20 times (409).

Parameters
NameInTypeDescription
id requiredpathstringThe endpoint's id.
delivery_id requiredpathstringThe delivery's id.
Responses
StatusDescriptionBody
202AcceptedWebhookDelivery
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: resendWebhookDelivery

meta

The key in use, health, and this description.

GET /healthz

Health check no key needed

Answers "ok" while the API is up.

Responses
StatusDescriptionBody
200OKtext
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: health

GET /v1/openapi.json

This API description (OpenAPI 3.1) no key needed

Describes every endpoint, its scope, request and response. Needs no key.

Responses
StatusDescriptionBody
200OKOpenAPIDocument
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getOpenAPI

GET /v1/whoami

The organisation and key in use any valid key

Shows which organisation the key acts for and the scopes it holds. Any valid key may call it.

Responses
StatusDescriptionBody
200OKWhoAmI
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: whoAmI

complaints

Reporting a problem with a line of one of your orders, and following what Kiuki decides.

POST /v1/complaints

Report a problem with an order line scope: complaint:write

Reports what a shopper found wrong with a line of one of your orders, once its shipment has left the site (dispatched or delivered; 409 before that). kind is one of allergen, label, safety, damaged, missing or other.

An allergen, label or safety report takes the listing off sale at once (listing_paused true), alerts Kiuki and tells the seller, who may answer it; Kiuki staff then resolve it (status resolved, with an outcome: upheld or not_upheld, and what Kiuki found in resolution). Other kinds are recorded and dealt with the same way, without taking the listing off sale. Don't put the shopper's name or contact details in description: the seller reads it.

Idempotent on external_ref, your own reference for the complaint: sending it again returns the complaint already recorded with 200 instead of 201 (409 if that reference is a complaint about another line or of another kind). One open complaint of a kind per line: another of the same kind is refused with 409 until Kiuki resolves the first.

Request body (required): ComplaintRequest

Responses
StatusDescriptionBody
200OKComplaint
201CreatedComplaint
400The request is malformed. The message says what to fix.Error
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
409The request is valid but can't be done now. The error code and message say why.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: reportComplaint

GET /v1/complaints/{id}

One of your complaints scope: complaint:write

A complaint you reported, with where it stands: open, disputed (the seller answered it; Kiuki is deciding) or resolved, with Kiuki's outcome.

Parameters
NameInTypeDescription
id requiredpathstringThe complaint's id.
Responses
StatusDescriptionBody
200OKComplaint
401No API key was sent, or it isn't a valid one. Send Authorization: Bearer kp_...Error
403This key can't do this: it lacks the scope the message names, or its organisation can't use the API (not approved yet, or suspended), or it is another app's key. The message says which.Error
404There is no such record for your organisation.Error
429rate_limited: this key sent requests faster than its rate (20 a second on average, in bursts of up to 100), so nothing was done. Send it again once as many seconds as Retry-After says have passed.Error
500Something went wrong on Kiuki's side. It has been logged; try again later.Error

operationId: getComplaint

Webhooks

Kiuki POSTs these to your endpoints, signed (how to check them). Headers on every delivery: Kiuki-Signature, Kiuki-Event-Id, Kiuki-Event-Type, Kiuki-Delivery-Id, Kiuki-Delivery-Attempt.

order.placed

An order was placed. Its shipments wait for their payment (awaiting_payment is true).

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookOrderEvent

order.paid

The order's payment is secured.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookOrderEvent

shipment.released

A shipment's payment is secured and it has gone to its site.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

shipment.acknowledged

The site has the shipment and will pick it.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

shipment.dispatched

The shipment left the site; carrier and tracking are set when the site gave them.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

shipment.delivered

The shipment was delivered.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

shipment.cancelled

The shipment was cancelled: cancelled_by (aggregator, site or kiuki) and reason say by whom and why.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

shipment.failed

Kiuki gave up on the shipment: it won't be sent, as if it had been cancelled. reason says so in plain words; Kiuki's own notes about it aren't shared.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookShipmentEvent

order.completed

Every shipment of the order went, was cancelled or failed, and at least one went. shipments says which.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookOrderEvent

order.cancelled

Every shipment of the order was cancelled or failed. shipments says which, and why.

Kiuki POSTs it to each of your endpoints that wants it, signed. Answer 2xx within 10 seconds; anything else (or no answer) is tried again later, for a day. The same event can come more than once: handle each id once.

Body: WebhookOrderEvent

Schemas

Address

The shopper's delivery address. It goes to the sites that ship the order, never to sellers.

FieldTypeDescription
city requiredstring
country requiredstring

Must match the quote's country.

lines requiredarray of string
name requiredstring
postcode requiredstring

Must match the quote's postcode.

phonestring

CancelRequest

FieldTypeDescription
reasonstring

Why, in a sentence. Optional. The site and the sellers whose packs were in the order see it with the cancellation, which tells them it was the shop that sold it (never which shop): leave out the shopper's name and details.

CatalogueItem

A live listing: a pack offered in a market from one origin.

FieldTypeDescription
alcohol requiredboolean
available requiredinteger

Packs that can be ordered now. 0 when the origin's stock data is over an hour old.

brand requiredstring
dimensions_mm requiredDimensions
gross_weight_g requiredinteger
labels requiredarray of Label
listing_id requiredstring (uuid)

Quote and order with this id.

market requiredstring
origin requiredOrigin
pack_name requiredstring
product_name requiredstring
sku requiredstring
stock_fresh requiredboolean

False when the origin's stock data is over an hour old.

temperature requiredstring: ambient, chilled, frozen
unit_price requiredMoney

Per pack: the seller's price plus Kiuki's 10% fee.

units_per_pack requiredinteger

Size: consumer units in one pack.

vat_rate_bp requiredinteger

VAT rate in basis points (2000 = 20%).

alcohol_abvnumber

Alcohol by volume, percent. Present only for alcohol.

country_of_originstring
gtinstring

The consumer unit's GTIN, if it has one.

hs_codestring
net_quantitystring

The net quantity of one unit, as its label states it: 40 g for a case of 12 bars of 40 g, where units_per_pack is 12. Food sold by number gives a count, such as 6 eggs.

pack_gtinstring

The pack's own GTIN, if it has one.

CataloguePage

FieldTypeDescription
currency requiredstring
items requiredarray of CatalogueItem
market requiredstring
next_cursorstring

Pass as cursor for the next page. Absent on the last page.

Charge

FieldTypeDescription
amount requiredMoney
code requiredstring
label requiredstring

Complaint

FieldTypeDescription
description requiredstring
id requiredstring (uuid)
kind requiredstring: allergen, label, safety, damaged, missing, other
listing_id requiredstring (uuid)
listing_paused requiredboolean

The listing was taken off sale for this complaint (allergen, label and safety reports). It comes back on sale only when Kiuki says so.

order_id requiredstring (uuid)
order_line_id requiredstring (uuid)
reported_at requiredstring (date-time)
status requiredstring: open, disputed, resolved

open: Kiuki is looking into it. disputed: the seller answered it and Kiuki is deciding. resolved: Kiuki decided (outcome, resolution).

date_markstring (date)
external_refstring
lot_codestring
outcomestring: upheld, not_upheld

Once resolved: upheld (the problem was real) or not_upheld.

resolutionstring

Once resolved: what Kiuki found and what happens next.

resolved_atstring (date-time)

ComplaintRequest

FieldTypeDescription
description requiredstring

What the shopper found, in a sentence or two. No names or contact details: the seller reads it.

kind requiredstring: allergen, label, safety, damaged, missing, other

allergen: an allergen the label doesn't declare, or a reaction. label: the label is wrong, unreadable or missing mandatory information. safety: something in the food that shouldn't be, spoiled or unsafe food, or another risk to health. damaged: arrived damaged or leaking. missing: not in the parcel, or the parcel never arrived. other: anything else.

order_line_id requiredstring (uuid)

A line of one of your orders (lines[].id in GET /v1/orders/{id}).

date_markstring (date)

The best-before or use-by date printed on the pack, if the shopper gave it.

external_refstring

Your own reference for the complaint (your ticket number, say). Makes retries safe.

lot_codestring

The lot or batch code printed on the pack, if the shopper gave it.

Contact

For delivery updates: an email, a phone number, or both.

FieldTypeDescription
emailstring (email)
phonestring

Destination

Where to deliver: country and postcode only.

FieldTypeDescription
country requiredstring
postcode requiredstring

Dimensions

FieldTypeDescription
height requiredinteger
length requiredinteger
width requiredinteger

Error

FieldTypeDescription
error requiredstring

A stable code to branch on: bad_request, not_signed_in, forbidden, not_found, conflict, market_closed, unavailable, quote_expired, quote_blocked, quote_used, external_ref_used, origin_unavailable, out_of_stock, payment_refused, payment_used, not_cancellable, too_large, internal, stripe_unavailable, payments_unavailable. too_large comes with 413 (a body over the endpoint's limit). The last two come with 503: nothing was done, and the same request can be sent again. rate_limited comes with 429: the key sent requests faster than its rate (Retry-After says when to send it again).

message requiredstring

What is wrong and what to do about it, in plain English. Safe to show to a person.

linesarray of LineProblem

Quotes only: every line that can't be bought, and why.

Label

Mandatory food information for one market, in one language.

FieldTypeDescription
allergens requiredarray of string: celery, cereals_gluten, crustaceans, eggs, fish, lupin, milk, molluscs, mustard, nuts, peanuts, sesame, soya, sulphites
business_name_address requiredstring
ingredients requiredstring

Allergens are emphasised with **...**.

legal_name requiredstring

The name of the food.

locale requiredstring
net_quantity requiredstring

The net quantity of one unit, as printed on it (40 g, not the 12 x 40 g of a case of 12).

country_of_origin_statementstring
may_containstring
nutritionobject

Per 100 g or ml: energy_kj, energy_kcal, fat and so on.

storagestring
use_instructionsstring

LineProblem

FieldTypeDescription
code requiredstring: invalid, duplicate, not_on_sale, wrong_market, no_price, stock_stale, not_enough_stock
line requiredinteger

1-based position of the line in the request.

listing_id requiredstring
message requiredstring

Market

FieldTypeDescription
active requiredboolean

Only active markets can be quoted and ordered.

code requiredstring

Great Britain and Northern Ireland are separate markets.

country requiredstring
currency requiredstring
locales requiredarray of string
name requiredstring
timezone requiredstring

MarketList

FieldTypeDescription
markets requiredarray of Market

Money

An amount in integer minor units of a currency (pence for GBP). Never a float.

FieldTypeDescription
currency requiredstring
minor requiredinteger (int64)

OneOriginAlternative

A quote's basket with every pack from one site, priced in full: that site's unit prices for the same packs, and its fulfilment from its rate card (one shipment per temperature). Lines asking for the same pack from different sites become one line here.

FieldTypeDescription
dispatch_days requiredinteger

The site's dispatch promise, in working days.

fulfilment requiredMoney
goods requiredMoney
lines requiredarray of OneOriginLine
parcels requiredinteger

Parcels the site would pack the basket into. Compare with the quote's parcels.

saving requiredMoney

The quote's total less this total: what taking this alternative saves. Negative when it costs more.

shipments requiredinteger

One per temperature: chilled and frozen travel apart from ambient.

site_id requiredstring (uuid)

Send it to POST /v1/quotes/{id}/one-origin to quote this alternative.

site_name requiredstring
total requiredMoney

goods + fulfilment.

OneOriginLine

FieldTypeDescription
line_total requiredMoney
listing_id requiredstring (uuid)

The pack's listing at the alternative's site.

name requiredstring
pack_id requiredstring (uuid)
qty requiredinteger

Packs.

quote_lines requiredarray of integer

The quote's lines this one takes the place of: one, or several lines of the same pack.

sku requiredstring
unit_price requiredMoney

Per pack at that site: its seller's price + Kiuki's fee.

OneOriginRequest

FieldTypeDescription
site_id requiredstring (uuid)

The site to take every pack from: the site_id of one of the quote's one_origin_alternatives.

OpenAPIDocument

An OpenAPI 3.1 document: this one.

Order

FieldTypeDescription
contact requiredContact
currency requiredstring
external_ref requiredstring
fee requiredMoney

Kiuki's distribution fee, included in goods.

fulfilment requiredMoney
goods requiredMoney
id requiredstring (uuid)
market requiredstring
placed_at requiredstring (date-time)
ship_to requiredAddress
shipments requiredarray of Shipment
status requiredstring: placed, paid, in_progress, completed, cancelled

placed, then paid once payment is taken; in_progress once any shipment is acknowledged; completed once every shipment is dispatched, delivered or cancelled and at least one went; cancelled once every shipment is. Never moves back.

total requiredMoney
cancelled_atstring (date-time)
paid_atstring (date-time)
payment_refstring

The payment the order was placed with (kiuki.com's orders: the shopper's PaymentIntent).

quote_idstring (uuid)

OrderLine

FieldTypeDescription
cancelled_qty requiredinteger
id requiredstring (uuid)
line_total requiredMoney
listing_id requiredstring (uuid)
qty requiredinteger
unit_price requiredMoney
vat_rate_bp requiredinteger
namestring
skustring

OrderPage

FieldTypeDescription
orders requiredarray of OrderSummary
next_cursorstring

Pass as cursor for the next page. Absent on the last page.

OrderSummary

FieldTypeDescription
currency requiredstring
external_ref requiredstring
fulfilment requiredMoney
goods requiredMoney
id requiredstring (uuid)
placed_at requiredstring (date-time)
shipments requiredarray of ShipmentSummary
status requiredstring
total requiredMoney
cancelled_atstring (date-time)

OrderWithAgeChecks

An order, as placing, reading and cancelling it answer: everything in Order, each shipment saying whether it is delivered with an age check.

FieldTypeDescription
shipmentsarray of ShipmentWithAgeCheck

Origin

The site a listing ships from.

FieldTypeDescription
country requiredstring
dispatch_days requiredinteger

The site's dispatch promise in working days (at most 3).

name requiredstring
site_id requiredstring (uuid)

PlaceOrderRequest

FieldTypeDescription
contact requiredContact
external_ref requiredstring

Your own order id. Sending it again returns the same order.

quote_id requiredstring (uuid)
ship_to requiredAddress
payment_refstring

kiuki.com only, and required from it: the PaymentIntent the shopper paid with on kiuki.com's checkout, on the platform's Stripe account. It is checked (succeeded, same currency, covers the quote's total, not used for another order) before anything is ordered; a refusal is 402 payment_refused or 409 payment_used. Every other aggregator leaves it out (400 if sent): Kiuki takes their payment from their saved payment method, per shipment.

Quote

FieldTypeDescription
created_at requiredstring (date-time)
currency requiredstring
expires_at requiredstring (date-time)

10 minutes after created_at.

fulfilment requiredMoney
goods requiredMoney
id requiredstring (uuid)

Order with this id before expires_at.

market requiredstring
orderable requiredboolean

False when an origin is blocked.

origins requiredarray of QuoteOrigin
ship_to requiredDestination
total requiredMoney

goods + fulfilment: what the order will cost.

QuoteLine

FieldTypeDescription
brand requiredstring
fee requiredMoney

Per pack: Kiuki's 10% distribution fee, VAT included.

line requiredinteger
line_total requiredMoney
listing_id requiredstring (uuid)
name requiredstring
pack_id requiredstring (uuid)
price_id requiredstring (uuid)
qty requiredinteger
seller_org_id requiredstring (uuid)
seller_price requiredMoney

Per pack: what the seller receives.

sku requiredstring
unit_price requiredMoney

Per pack: seller_price + fee.

vat_rate_bp requiredinteger

QuoteOrigin

One future shipment: one origin site and one temperature.

FieldTypeDescription
charges requiredarray of Charge

Itemised fulfilment charges from the origin's rate card, at cost: order handling, picking, packaging, coolant, carriage, surcharges.

dispatch_days requiredinteger
fulfilment requiredMoney
lines requiredarray of QuoteLine
parcels requiredinteger

Parcels the origin will pack this shipment into.

site_id requiredstring (uuid)
site_name requiredstring
subtotal requiredMoney

Goods from this origin.

temperature requiredstring: ambient, chilled, frozen
total requiredMoney

subtotal + fulfilment.

blockedstring

Present when the origin refuses this shipment: its minimum order isn't met, it has no delivery service to the address or no rate card in force, a pack is too big for its boxes. The quote can't be ordered until the basket changes.

rate_card_idstring (uuid)

The version of the origin's rate card priced on. The order keeps it.

servicestring

The delivery service priced, as the origin's rate card names it. Absent when the origin is blocked.

service_namestring

QuoteRequest

FieldTypeDescription
lines requiredarray of QuoteRequestLine

One line per listing.

market requiredstring
ship_to requiredDestination

QuoteRequestLine

FieldTypeDescription
listing_id requiredstring (uuid)
qty requiredinteger

Packs.

QuoteWithAlternatives

A quote, as POST /v1/quotes and POST /v1/quotes/{id}/one-origin answer it: everything in Quote, plus how many parcels the basket makes (show it in the cart before checkout) and, when its shipments come from more than one site, its one-origin alternatives: the same basket with every pack from one site, so one delivery instead of several. An alternative is offered only when that site lists every pack live in the market, has fresh stock for the whole quantity of each, sells each at a price it may (the legal minimum price of alcohol included) and takes the whole basket (no shipment blocked by its rate card); it is priced in full, at that site's own unit prices and fulfilment. At most 3 are offered, the cheapest total first. Only this quote can be ordered: to take an alternative, send its site_id to POST /v1/quotes/{id}/one-origin, which quotes the basket again from that site, and order the quote that returns.

FieldTypeDescription
one_origin_alternatives requiredarray of OneOriginAlternative

The same basket from one site each, the cheapest total first. Empty when the quote's shipments all come from one site, or no other single site can send the whole basket.

parcels requiredinteger

Parcels the basket makes: every origin's parcels added up.

Shipment

One origin's part of an order. pending -> acknowledged -> picking -> packed -> dispatched -> delivered; or cancelled, or failed. A shipment starts out awaiting payment: its site doesn't have it until its payment is secured (your payment authorised; for kiuki.com, the shopper's payment recorded).

FieldTypeDescription
ack_deadline requiredstring (date-time)

The site acknowledges within its working hours by then. Counted again when a shipment awaiting payment goes to its site.

awaiting_payment requiredboolean

true while the shipment is held because its payment isn't secured yet: it stays pending, its site doesn't have it, and nothing leaves the site. It goes to the site once the payment is secured, and its deadlines are then counted again from that moment. A declined payment keeps it held until the payment succeeds, the order is cancelled, or 24 hours after the order, when Kiuki cancels it (see status).

charges requiredarray of Charge
dispatch_deadline requiredstring (date-time)

The site dispatches by then (its promise, in working days). Counted again when a shipment awaiting payment goes to its site.

fulfilment requiredMoney
id requiredstring (uuid)
lines requiredarray of OrderLine
parcels requiredinteger
site_id requiredstring (uuid)
status requiredstring: pending, acknowledged, picking, packed, dispatched, delivered, cancelled, failed

pending -> acknowledged -> picking -> packed -> dispatched -> delivered. cancelled: by you (while pending or acknowledged), by the site, or by Kiuki, which says why in cancel_reason. Kiuki cancels your shipment when its payment isn't secured within 24 hours of the order (cancel_reason "payment not secured within 24 hours"): its stock goes back on sale and nothing is taken from your card. kiuki.com's shipments are never cancelled that way. failed: Kiuki staff gave up on it.

temperature requiredstring: ambient, chilled, frozen
acknowledged_atstring (date-time)
cancel_reasonstring

Why Kiuki cancelled the shipment, when it did: "payment not secured within 24 hours"; for kiuki.com's own orders also "the shopper's payment was refunded" or "the shopper's payment was disputed" (still unpaid 10 minutes after Stripe said so, and its site hadn't started picking it). Absent otherwise.

cancelled_atstring (date-time)
carrierstring
delivered_atstring (date-time)
dispatched_atstring (date-time)
servicestring

The delivery service the shipment was priced with, as the origin's rate card names it.

site_namestring
tracking_numberstring
tracking_urlstring

ShipmentSummary

FieldTypeDescription
id requiredstring (uuid)
status requiredstring
temperature requiredstring: ambient, chilled, frozen
carrierstring
tracking_numberstring
tracking_urlstring

ShipmentWithAgeCheck

A shipment, as an order shows it: everything in Shipment, plus whether it is delivered with an age check.

FieldTypeDescription
age_checked requiredboolean

true when the shipment holds alcohol: it is delivered with an age check, and the courier hands it over only to someone 18 or over. Tell your shopper before checkout. The site's rate card may charge for it, per parcel holding alcohol (charge code alcohol).

WebhookAttempt

FieldTypeDescription
at requiredstring (date-time)
attempt requiredinteger
duration_ms requiredinteger
errorstring
responsestring

The start of the endpoint's answer.

status_codeinteger

WebhookDelivery

One event's delivery to one endpoint.

FieldTypeDescription
attempts requiredinteger
created_at requiredstring (date-time)
endpoint_id requiredstring (uuid)
event_id requiredstring (uuid)
event_type requiredstring
id requiredstring (uuid)
status requiredstring: pending, delivered, failed, skipped

pending: waiting for its next attempt; delivered: answered 2xx; failed: no attempt succeeded within a day; skipped: not sent because the endpoint is or was off. Turning the endpoint on sends up to 100 of those skipped in the last 30 days, the oldest first; any other can be sent again (resend).

delivered_atstring (date-time)
last_attempt_atstring (date-time)
last_errorstring

Why the last attempt failed, in plain words.

last_statusinteger

The HTTP status of the last answer, when there was one.

next_attempt_atstring (date-time)

WebhookDeliveryDetail

FieldTypeDescription
attempt_log requiredarray of WebhookAttempt
attempts requiredinteger
created_at requiredstring (date-time)
endpoint_id requiredstring (uuid)
event_id requiredstring (uuid)
event_type requiredstring
id requiredstring (uuid)
payload requiredstring

The body every attempt sends, exactly.

status requiredstring: pending, delivered, failed, skipped
delivered_atstring (date-time)
last_attempt_atstring (date-time)
last_errorstring
last_statusinteger
next_attempt_atstring (date-time)

WebhookDeliveryList

FieldTypeDescription
deliveries requiredarray of WebhookDelivery

WebhookEndpoint

An https address Kiuki sends events to, signed with its secret.

FieldTypeDescription
consecutive_failures requiredinteger

Failed attempts since the last success.

created_at requiredstring (date-time)
enabled requiredboolean

false: nothing is sent to it.

events requiredarray of string: *, order.placed, order.paid, shipment.released, shipment.acknowledged, shipment.dispatched, shipment.delivered, shipment.cancelled, shipment.failed, order.completed, order.cancelled

The events it wants; * is all of them, including any added later.

id requiredstring (uuid)
sandbox requiredboolean

true for the sandbox's endpoints, which get the sandbox's events.

secret_hint requiredstring

The last characters of its secret, to tell secrets apart.

turned_off_by_kiuki requiredboolean

Kiuki turned it off because every attempt to deliver to it failed for a day (and 10 in a row). Turn it on again once it is fixed.

url requiredstring
descriptionstring
disabled_atstring (date-time)
disabled_reasonstring

Who turned it off, and, when Kiuki did, why.

last_failure_atstring (date-time)
last_success_atstring (date-time)

WebhookEndpointCreated

A new endpoint, with its secret. The secret is shown this once only: store it now.

FieldTypeDescription
created_at requiredstring (date-time)
enabled requiredboolean
events requiredarray of string
id requiredstring (uuid)
sandbox requiredboolean
secret requiredstring

Signs every delivery to this endpoint (Kiuki-Signature). Shown once.

secret_hint requiredstring
url requiredstring
consecutive_failuresinteger
descriptionstring
turned_off_by_kiukiboolean

WebhookEndpointDeleted

FieldTypeDescription
deleted requiredboolean
id requiredstring (uuid)

WebhookEndpointList

FieldTypeDescription
endpoints requiredarray of WebhookEndpoint

WebhookEndpointRequest

FieldTypeDescription
url requiredstring

https:// and a public host name. No user name or password in it.

descriptionstring
eventsarray of string

The events to send; leave out (or ["*"]) for all. An empty list is refused.

WebhookEndpointUpdate

FieldTypeDescription
descriptionstring
enabledboolean

false turns the endpoint off; true turns it on again and sends it up to 100 of the deliveries skipped meanwhile, the oldest of the last 30 days. Any more stay skipped.

eventsarray of string

The events to send instead (["*"] for all). Left out, they stay as they are; an empty list is refused.

urlstring

WebhookOrder

The order as GET /v1/orders/{id} shows it, without addresses and lines. order.placed, order.completed and order.cancelled add its shipments.

FieldTypeDescription
currency requiredstring
external_ref requiredstring
id requiredstring (uuid)
placed_at requiredstring (date-time)
status requiredstring: placed, paid, in_progress, completed, cancelled
total requiredMoney
cancelled_atstring (date-time)
fulfilmentMoney
goodsMoney
marketstring
paid_atstring (date-time)
shipmentsarray of WebhookShipment

order.placed, order.completed and order.cancelled: every shipment of the order as it stands, so the end of an order says which shipments went and which were cancelled or failed.

WebhookOrderEvent

order.placed, order.paid, order.completed or order.cancelled.

FieldTypeDescription
created_at requiredstring (date-time)

When it happened.

data requiredobject
id requiredstring (uuid)

The event's id: the same in every delivery of it. Handle each id once.

sandbox requiredboolean

true for the sandbox's events.

type requiredstring: order.placed, order.paid, order.completed, order.cancelled

WebhookShipment

The shipment as GET /v1/orders/{id} shows it, without its lines and charges.

FieldTypeDescription
awaiting_payment requiredboolean
id requiredstring (uuid)
order_id requiredstring (uuid)
site_id requiredstring (uuid)
status requiredstring: pending, acknowledged, picking, packed, dispatched, delivered, cancelled, failed
temperature requiredstring: ambient, chilled, frozen
acknowledged_atstring (date-time)
cancel_reasonstring

Why Kiuki cancelled it, when it did.

cancelled_atstring (date-time)
cancelled_bystring: aggregator, site, kiuki

shipment.cancelled only: who cancelled it (aggregator: you).

carrierstring
delivered_atstring (date-time)
dispatched_atstring (date-time)
parcelsinteger
reasonstring

shipment.cancelled and shipment.failed only. shipment.cancelled: why, in plain words. shipment.failed: that Kiuki gave up on it, in plain words; Kiuki's own notes about it aren't shared.

servicestring
site_namestring
tracking_numberstring
tracking_urlstring

WebhookShipmentEvent

shipment.released, shipment.acknowledged, shipment.dispatched, shipment.delivered, shipment.cancelled or shipment.failed.

FieldTypeDescription
created_at requiredstring (date-time)
data requiredobject
id requiredstring (uuid)

The event's id: the same in every delivery of it. Handle each id once.

sandbox requiredboolean
type requiredstring: shipment.released, shipment.acknowledged, shipment.dispatched, shipment.delivered, shipment.cancelled, shipment.failed

WhoAmI

FieldTypeDescription
key requiredstring

The key's name.

org_id requiredstring (uuid)
sandbox requiredboolean

true for a sandbox key: it sees only the sandbox's listings and orders.

scopes requiredarray of string: catalogue:read, quote:write, order:write, order:read, webhooks:write, complaint:write