Skip to content
KiukiPlatform
Documentation

Complaints

Reporting a problem a shopper found with an order line, and following what Kiuki decides.

When a shopper tells you something was wrong with what they received, report it to Kiuki about the order line it concerns. Kiuki follows it up with the seller and tells you what it decided. You need a key with the complaint:write scope (authentication).

Reporting a problem

Once the line's shipment has left its site (dispatched or delivered), send POST /v1/complaints. Before that the answer is 409.

curl -s https://platform.kiuki.com/v1/complaints -H "Authorization: Bearer $KIUKI_KEY" -H "Content-Type: application/json" -d '{
  "order_line_id": "ORDER_LINE_ID",
  "kind": "damaged",
  "description": "Two of the jars arrived broken.",
  "external_ref": "ticket-5512"
}'
  • order_line_id is a line of one of your orders: lines[].id in GET /v1/orders/{id}.
  • description says what the shopper found, in a sentence or two. Never put the shopper's name or contact details in it: the seller reads it.
  • external_ref is your own reference for it, such as your ticket number. It makes sending it again safe.
  • lot_code and date_mark (the best-before or use-by date) are what is printed on the pack, if the shopper can tell you: they help find the batch.

The answer is 201 Created with the complaint, open.

Kinds, and what happens

kindFor
allergenAn allergen the label doesn't declare, or a reaction.
labelThe label is wrong, unreadable or lacks mandatory information.
safetySomething in the food that shouldn't be there, spoiled or unsafe food, or another risk to health.
damagedIt arrived damaged or leaking.
missingIt wasn't in the parcel, or the parcel never arrived.
otherAnything else.

An allergen, label or safety report takes the listing off sale at once (listing_paused: true): nobody can order it until Kiuki puts it back. Kiuki is alerted and the seller is told, and may answer. The other kinds are recorded and followed up the same way, without taking the listing off sale.

Following it

GET /v1/complaints/{id} says where it stands:

curl -s https://platform.kiuki.com/v1/complaints/COMPLAINT_ID -H "Authorization: Bearer $KIUKI_KEY"
statusMeans
openKiuki is looking into it.
disputedThe seller answered it, and Kiuki is deciding.
resolvedKiuki decided: outcome is upheld (the problem was real) or not_upheld, and resolution says what Kiuki found and what happens next.

Sending it again

  • The same external_ref again returns the complaint already recorded, with 200 OK instead of 201 Created. A reference already used for a complaint about another line, or of another kind, is refused with 409.
  • A line has one open complaint of each kind at a time: another of the same kind is refused with 409 until Kiuki resolves the first.