← API Index

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:

  1. 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-sid in the URL and send credentials.
  2. Link hash h: eight characters that came with the link to the complaint page.
  3. 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"}
  ]
}

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.

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;

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

Things not to forget

Ideas