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:
GET /v1/markets, then GET /v1/catalogue?market=GB for what is on sale: packs, food labels, unit prices and availability.
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.
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.
GET /v1/orders/{id} for status and tracking; POST /v1/orders/{id}/cancel while its shipments haven't started.
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.
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.
This 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.
rate_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.
This 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.
rate_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.
This 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.
rate_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.
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).
This 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.
rate_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.
Quote a basket again from one originscope: 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.
This 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.
rate_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.
This 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.
rate_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.
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.
This 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.
rate_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.
A 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.
This 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.
rate_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.
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.
This 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.
rate_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.
POST /v1/orders/{id}/shipments/{shipment_id}/cancel
Cancel one shipment of an orderscope: 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.
This 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.
rate_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.
This 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.
rate_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.
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).
This 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.
rate_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.
This 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.
rate_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.
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.
This 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.
rate_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.
This 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.
rate_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.
This 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.
rate_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.
This 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.
rate_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.
POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/resend
Send a delivery againscope: 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).
This 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.
rate_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.
This 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.
rate_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.
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 linescope: 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.
This 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.
rate_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.
This 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.
rate_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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The shopper's delivery address. It goes to the sites that ship the order, never to sellers.
Field
Type
Description
cityrequired
string
countryrequired
string
Must match the quote's country.
linesrequired
array of string
namerequired
string
postcoderequired
string
Must match the quote's postcode.
phone
string
CancelRequest
Field
Type
Description
reason
string
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.
Field
Type
Description
alcoholrequired
boolean
availablerequired
integer
Packs that can be ordered now. 0 when the origin's stock data is over an hour old.
Per pack: the seller's price plus Kiuki's 10% fee.
units_per_packrequired
integer
Size: consumer units in one pack.
vat_rate_bprequired
integer
VAT rate in basis points (2000 = 20%).
alcohol_abv
number
Alcohol by volume, percent. Present only for alcohol.
country_of_origin
string
gtin
string
The consumer unit's GTIN, if it has one.
hs_code
string
net_quantity
string
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.
string: allergen, label, safety, damaged, missing, other
listing_idrequired
string (uuid)
listing_pausedrequired
boolean
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_idrequired
string (uuid)
order_line_idrequired
string (uuid)
reported_atrequired
string (date-time)
statusrequired
string: open, disputed, resolved
open: Kiuki is looking into it. disputed: the seller answered it and Kiuki is deciding. resolved: Kiuki decided (outcome, resolution).
date_mark
string (date)
external_ref
string
lot_code
string
outcome
string: upheld, not_upheld
Once resolved: upheld (the problem was real) or not_upheld.
resolution
string
Once resolved: what Kiuki found and what happens next.
resolved_at
string (date-time)
ComplaintRequest
Field
Type
Description
descriptionrequired
string
What the shopper found, in a sentence or two. No names or contact details: the seller reads it.
kindrequired
string: 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_idrequired
string (uuid)
A line of one of your orders (lines[].id in GET /v1/orders/{id}).
date_mark
string (date)
The best-before or use-by date printed on the pack, if the shopper gave it.
external_ref
string
Your own reference for the complaint (your ticket number, say). Makes retries safe.
lot_code
string
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.
Field
Type
Description
email
string (email)
phone
string
Destination
Where to deliver: country and postcode only.
Field
Type
Description
countryrequired
string
postcoderequired
string
Dimensions
Field
Type
Description
heightrequired
integer
lengthrequired
integer
widthrequired
integer
Error
Field
Type
Description
errorrequired
string
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).
messagerequired
string
What is wrong and what to do about it, in plain English. Safe to show to a person.
An amount in integer minor units of a currency (pence for GBP). Never a float.
Field
Type
Description
currencyrequired
string
minorrequired
integer (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.
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.
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.
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_id
string (uuid)
The version of the origin's rate card priced on. The order keeps it.
service
string
The delivery service priced, as the origin's rate card names it. Absent when the origin is blocked.
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.
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.
parcelsrequired
integer
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).
Field
Type
Description
ack_deadlinerequired
string (date-time)
The site acknowledges within its working hours by then. Counted again when a shipment awaiting payment goes to its site.
awaiting_paymentrequired
boolean
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).
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.
temperaturerequired
string: ambient, chilled, frozen
acknowledged_at
string (date-time)
cancel_reason
string
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_at
string (date-time)
carrier
string
delivered_at
string (date-time)
dispatched_at
string (date-time)
service
string
The delivery service the shipment was priced with, as the origin's rate card names it.
site_name
string
tracking_number
string
tracking_url
string
ShipmentSummary
Field
Type
Description
idrequired
string (uuid)
statusrequired
string
temperaturerequired
string: ambient, chilled, frozen
carrier
string
tracking_number
string
tracking_url
string
ShipmentWithAgeCheck
A shipment, as an order shows it: everything in Shipment, plus whether it is delivered with an age check.
Field
Type
Description
age_checkedrequired
boolean
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
Field
Type
Description
atrequired
string (date-time)
attemptrequired
integer
duration_msrequired
integer
error
string
response
string
The start of the endpoint's answer.
status_code
integer
WebhookDelivery
One event's delivery to one endpoint.
Field
Type
Description
attemptsrequired
integer
created_atrequired
string (date-time)
endpoint_idrequired
string (uuid)
event_idrequired
string (uuid)
event_typerequired
string
idrequired
string (uuid)
statusrequired
string: 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_at
string (date-time)
last_attempt_at
string (date-time)
last_error
string
Why the last attempt failed, in plain words.
last_status
integer
The HTTP status of the last answer, when there was one.
https:// and a public host name. No user name or password in it.
description
string
events
array of string
The events to send; leave out (or ["*"]) for all. An empty list is refused.
WebhookEndpointUpdate
Field
Type
Description
description
string
enabled
boolean
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.
events
array of string
The events to send instead (["*"] for all). Left out, they stay as they are; an empty list is refused.
url
string
WebhookOrder
The order as GET /v1/orders/{id} shows it, without addresses and lines. order.placed, order.completed and order.cancelled add its shipments.
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.
Field
Type
Description
created_atrequired
string (date-time)
When it happened.
datarequired
object
idrequired
string (uuid)
The event's id: the same in every delivery of it. Handle each id once.
shipment.cancelled only: who cancelled it (aggregator: you).
carrier
string
delivered_at
string (date-time)
dispatched_at
string (date-time)
parcels
integer
reason
string
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.
service
string
site_name
string
tracking_number
string
tracking_url
string
WebhookShipmentEvent
shipment.released, shipment.acknowledged, shipment.dispatched, shipment.delivered, shipment.cancelled or shipment.failed.
Field
Type
Description
created_atrequired
string (date-time)
datarequired
object
idrequired
string (uuid)
The event's id: the same in every delivery of it. Handle each id once.