Guides
Returns
Let your customers send goods back through any Qoene Point with a paperless code, and follow the return to your door. You decide the rules; you refund from your own system.
How a return works
Your customer starts it
On the Qoene tracking page (tracking number + an SMS code to the phone the parcel was sent to, no account needed), in the Qoene Delivery app, or on your own site throughPOST /returns.You approve it
Automatically, or after your review in Business → Returns or withPOST /returns/{id}/approve. Qoene books a return parcel linked to the original.Paperless drop-off
The customer gets a QR and short code (QDR-XXXX-XXXX) by SMS, WhatsApp and email. The Qoene Point scans it and prints or attaches the label. No printer needed at home.Back to you
The return travels the network with its own promise and tracking, and you collect it at your return point with the usual collection code.You inspect and refund
Record the condition and photos in Business → Returns. Qoene sendsreturn.receivedandreturn.inspected; refund the customer from your shop.
Your return policy
| Setting | Meaning |
|---|---|
| Window | Days after delivery or collection (default 14). Later requests answer 409 WINDOW_CLOSED. |
| Reasons | CHANGED_MIND, WRONG_SIZE, WRONG_ITEM, DAMAGED, DEFECTIVE, NOT_AS_DESCRIBED, LATE, OTHER (a note is required) |
| Who pays | MERCHANT (your wallet or invoice), CUSTOMER (Mobile Money before the code works) or DEDUCT_FROM_REFUND (billed to you; deductFromRefundMinor says what to keep back) |
| Options | RELAY_POINT (drop-off at a Qoene Point), RELAY_LOCKER (when lockers go live), EXPRESS_STANDARD (a rider collects inside an Express area) |
| Approval | AUTO or MANUAL; a value above your maximum always waits for review |
| Return point | The Qoene Point where you collect returns (else your store's usual point) |
Set it per Business or per store in Business → Returns; read it with GET /returns/policy. Your Qoene contract may override the window, payer, options, approval and maximum.
Start a return from your site
A return you start is approved at once. Quote first if you want to show the price and promised date.
const { quote } = await qoene.returns.quote({ trackingNumber, dropoffPointCode: 'QD-PT-…' });
const { return: ret } = await qoene.returns.create({
trackingNumber,
items: [{ line: 1, quantity: 1 }],
reason: 'WRONG_SIZE',
productCode: 'RELAY_POINT',
dropoffPointCode: 'QD-PT-…',
prohibitedItemsDeclaration: { accepted: true, version: declaration.version },
}, { idempotencyKey: `return-${order.id}` });
console.log(ret.id, ret.status); // QD-RET-… AWAITING_DROPOFFcurl -X POST https://api.qoenedelivery.com/v1/returns \
-H "Authorization: Bearer $QOENE_API_KEY" \
-H "Idempotency-Key: return-1001" \
-H "Content-Type: application/json" \
--data '{"trackingNumber":"QDE-…","items":[{"line":1,"quantity":1}],"reason":"WRONG_SIZE","productCode":"RELAY_POINT","dropoffPointCode":"QD-PT-…","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}'$return = json_decode((string) $client->post('returns', [
'headers' => ['Idempotency-Key' => "return-{$orderId}"],
'json' => ['trackingNumber' => $tracking, 'items' => [['line' => 1, 'quantity' => 1]], 'reason' => 'WRONG_SIZE',
'productCode' => 'RELAY_POINT', 'dropoffPointCode' => $point, 'prohibitedItemsDeclaration' => ['accepted' => true, 'version' => $version]],
])->getBody(), true)['data']['return'];ret = requests.post(f"https://api.qoenedelivery.com/v1/returns", headers={**headers, "Idempotency-Key": f"return-{order_id}"}, json={
"trackingNumber": tracking, "items": [{"line": 1, "quantity": 1}], "reason": "WRONG_SIZE",
"productCode": "RELAY_POINT", "dropoffPointCode": point,
"prohibitedItemsDeclaration": {"accepted": True, "version": version},
}, timeout=30).json()["data"]["return"]items[].lineis the line number in the original order (1-based); leave outquantityto return all of it.- One open return per parcel (
409 RETURN_OPEN). Retrying with the same idempotency key returns the original. - Writes need a LIVE key with
returns.write; reading needsreturns.read. - The drop-off code is only ever sent to your customer. The API shows its state (
code.status), never the code.
Statuses
| Status | Meaning |
|---|---|
REQUESTED | Waiting for your review |
AWAITING_PAYMENT | Approved; the customer pays by Mobile Money before the code works |
AWAITING_DROPOFF | The code is active until dropoffBy (14 days) |
DROPPED_OFF, IN_TRANSIT | Qoene has it |
ARRIVED | Ready for you at your return point |
RECEIVED | Handed to you |
INSPECTED | You recorded its condition |
REJECTED, CANCELLED, EXPIRED | Closed. An unused code expires; the unused return parcel is cancelled and your charge given back. |
Webhooks
Subscribe to return.requested, return.approved, return.rejected, return.cancelled, return.expired, return.dropped_off, return.in_transit, return.arrived, return.received, return.inspected and return.refund_recorded. The body carries the return, the original and return parcels and your order, never the customer's phone or code. The return parcel also sends the usual shipment.* events.
Review customer returns from your server
GET /returns?status=REQUESTED, then approve or reject with a reason (the customer gets it by SMS). Cancel before drop-off with POST /returns/{id}/cancel.