Complaints about an order (Reklamation)
Read use-api.md first for API basics, sessions and response formats.
A complaint is a message of the customer about one order: something was missing, damaged, wrong or of poor quality. The customer can name the items concerned, give a reason for each, describe the problem and add a photo. The shop gets all of it in one mail and settles the case with the customer directly; the customer gets a confirmation mail.
A complaint books nothing: no credit, no return, no change of the order. It is also not the legal withdrawal from an order (Widerruf) — that is a form of its own, see cancel-form — and not the cancellation of an open order (api/client/cancelorder).
Ready-made ways
You only need the endpoint below if none of these fit.
| Way | For whom | What it does |
|---|---|---|
| Profile component | logged-on customers | The list of past orders in oo-profile has a "Reklamieren" link per order. See use-js-components |
| Complaint page | anyone with the order number | A page of the shop with its name and logo, no login needed. Address see Links to the complaint page |
| Link in a mail | customers reading a shop mail | The shop's mail texts can carry the link to that page, see Links in mails |
The endpoint
POST <base>/v3/complainOrder/<shop> — the base path of the shop (secureWebDomain, see
use-api.md) with /shop/ replaced by /complainOrder/, e.g.
https://oekobox-online.de/v3/complainOrder/schoenegge. Send it as multipart/form-data.
It needs no API key.
| Parameter | |
|---|---|
orderID |
order number, required |
description |
the customer's text. Required, unless at least one item with a reason is given |
item, reason |
optional and repeatable, always in pairs: the id of an item of the order and the id of a reason. Send an empty reason for an item without one, so that the n-th reason belongs to the n-th item |
image |
optional, one image file, up to 10 MB |
email |
an email address of the customer of the order — one of the three proofs, see Who may complain |
h |
instead of email: the hash from a link, see Links to the complaint page |
lookup |
1: send nothing, only answer what can be picked for this order, see Items and reasons |
x-oekobox-sid |
the session, when the customer is logged on and the call comes from another origin than the shop (alternatively the session cookie) |
The answer is JSON, with the HTTP status set accordingly:
{"success": true, "message": "Complaint submitted successfully", "orderID": 1216660}
{"success": false, "error": "Order does not belong to this customer", "error_code": "NOT_AUTHORIZED", "code": 403}
error_code |
Status | Meaning | What to do |
|---|---|---|---|
MISSING_ORDER_ID |
400 | no order number, or not a number | ask for it |
INVALID_ORDER_ID |
404 | no such order | ask again |
NOT_AUTHORIZED |
403 | none of the three proofs fits the order | ask for the email address |
TOO_LATE |
422 | the delivery date is more than 4 weeks back | tell the customer to contact the shop |
MISSING_DESCRIPTION |
400 | neither a text nor an item with a reason | ask for one of them |
TOO_MANY_REQUESTS |
429 | rate limit, see Things not to forget | try again later, do not loop |
EMAIL_CUSTOMER_FAILED |
500 | the confirmation mail could not be sent. The complaint has reached the shop | show success with a hint, do not send again |
INTERNAL_ERROR |
500 | anything else | try again later |
Show your own translated text per error_code; error is English and meant for logs.
Who may complain
Only the customer of the order. The endpoint takes one of three proofs, checked in this order:
- Session: the customer is logged on (api/logon4) and the order is
his. From a page of the shop the session cookie is enough; from another origin (embedded
shop, app) pass the session id as
x-oekobox-sidin the URL and send credentials. - Link hash
h: eight characters that came with the link to the complaint page. - Email address
email: an address stored for the customer of the order.
Without any of them the answer is NOT_AUTHORIZED — for the lookup too, so the items of an
order are not shown to somebody who only guessed its number.
Items and reasons
To let the customer pick what the complaint is about, ask first:
POST …/complainOrder/<shop> with orderID, lookup=1 and one of the proofs.
{
"success": true,
"orderID": 1216660,
"positions": [
{"iid": "461", "name": "Bananen", "amount": 0.75, "unit": "kg", "label": "Bananen, 0,75 kg"},
{"iid": "382", "name": "Karotten neue Ernte", "amount": 0.4, "unit": "kg", "label": "Karotten neue Ernte, 0,4 kg"}
],
"reasons": [
{"id": 1, "reason": "Artikel fehlt"},
{"id": 2, "reason": "Artikel beschädigt"}
]
}
positionsare the items of the order as ordered (name, ordered amount, unit), sorted by name.labelis ready for a select box, with the number formatted for the customer's language.iidis what you send back asitem.reasonsare the shop's own list. It can be empty: then offer the items alone. The texts are in the shop's base language and are not translated.- One reason per item. An
itemthat is not in the order is ignored, an unknownreasoncounts as none, an item named twice counts once. At most 30 items per complaint. - A lookup changes nothing and sends nothing. It answers the same errors as a complaint
(
NOT_AUTHORIZED,TOO_LATE, ...), so you can tell the customer early.
Which orders to offer at all: the customer's orders come from api/dates
and api/order (Order, see
profile-display). The standard shop shows the link for every order whose
delivery date (ddate) is at most 28 days back; the endpoint refuses older ones with TOO_LATE.
Links to the complaint page
The page lives under the base path of the shop:
| Address | Form |
|---|---|
<secureWebDomain>/complain |
empty; asks for order number and email address |
<secureWebDomain>/complain/<order number> |
order number filled in; asks for the email address |
<secureWebDomain>/complain/<order number>/<hash> |
order number filled in, no email address asked, items offered at once |
?locale=<locale> (e.g. ?locale=en_GB) picks the language, if the shop offers it.
The hash spares the customer typing the email address. It is the first 8 hex characters of the SHA-256 of
<email address, trimmed, lower case>|<order number> (UTF-8)
e.g. kunde@example.com|123456 → e28044d4. No secret is involved, so you can build such a
link yourself wherever you know the customer's email address and the order number (delivery
note, your own mails, a customer portal). It proves no more than knowing the email address
does. It belongs to that one order: with another order number it does not fit. If the customer
has changed the address since, the page falls back to asking for it.
// Node.js
const crypto = require("crypto");
const hash = crypto.createHash("sha256")
.update(email.trim().toLowerCase() + "|" + orderNumber, "utf8").digest("hex").substring(0, 8);
const link = secureWebDomain + "/complain/" + orderNumber + "/" + hash;
Links in mails
Mail texts written in the shop's admin area can carry the link as a variable; the shop fills it in per recipient (api/system/variables lists all variables):
| Variable | Result |
|---|---|
%Verweis.Reklamation% / %Verweis.ReklamationLink% |
link to the empty form / its address alone |
%Bestellung.<Nummer>.Reklamieren% / %Bestellung.<Nummer>.ReklamierenLink% |
link for that order including the hash / its address alone. Empty if the order is not one of the recipient |
What happens after a complaint
- The shop gets a mail with customer number, order number, the items with their reasons, the text and the photo as attachment. Replying to it answers the customer.
- The customer gets a confirmation mail with the same data (without the photo).
- The photo is also kept in the shop's file store, private, with the tag
complaint/<customer number>/<order number>. Staff find it in api/system/files and see it throughfs.pywith their own session; customers and callers without a session get 404. An order can have no photo or several (one per complaint). The photo is deleted after 80 days, with the event; earlier if the customer is deleted. - The complaint is recorded as event
customer_complain(code2315, see api/system/eventtypes). It can trigger a webhook and is counted in the statistics. The event carries the order number and a note{<item id>:<reason id>,...} <text>— reason id0for an item without reason, the text alone if no item was named; the note is cut at 253 characters. - Nothing else: the order, the customer's balance and the stock stay as they are.
- ..until the backend processes the complaint and notifies the customer independently.
Things not to forget
- It is not a withdrawal. If your page offers both, keep them apart in wording; the withdrawal has legal deadlines and its own form.
- 4 weeks. Hide the entry point for older orders instead of letting the customer run into
TOO_LATE. - Rate limit. There is a rate limit in place. Refused calls count too. Do not retry automatically, and look up the items once per opened form, not on every keystroke.
- Block the button while sending. The call uploads a photo and sends two mails; it can take a few seconds. A second click is a second complaint.
EMAIL_CUSTOMER_FAILEDis not a failure of the complaint. Sending again doubles it.- Photo. One file per complaint, 10 MB at most; it is scaled down to 1000 × 1000 pixels. On
a phone,
<input type="file" accept="image/*" capture="environment">opens the camera. - Pairs. A form that posts
itemwithout a matchingreasonfield shifts the reasons to the wrong items. - Reasons belong to the shop. Do not hard-code ids or texts; read them with the lookup each time.
- Customer text is free text. Escape it wherever you show it again.
- Cross-origin. The answers carry the same CORS headers as the other API calls; a shop can restrict calls to its own website.
- Privacy. The photo and the text go to the shop by mail, and the photo stays in the shop's file store for a while. Say so next to the form if your privacy notice does not cover it.
Ideas
- Print the link with the hash as a QR code on the delivery note: scan, take a photo, done — no login, no typing.
- Put
%Bestellung.<Nummer>.Reklamieren%into the delivery or invoice mail ("Something wrong with this delivery?"). - In an app, open the camera first and the form second: most complaints are a photo and one tap on a reason.
- Feed the
customer_complainwebhook into your ticket system, and count reasons per item to spot a bad batch or a packing problem early.