Developers
API referenceBusiness sign in

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

  1. 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 through POST /returns.
  2. You approve it

    Automatically, or after your review in Business → Returns or with POST /returns/{id}/approve. Qoene books a return parcel linked to the original.
  3. 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.
  4. 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.
  5. You inspect and refund

    Record the condition and photos in Business → Returns. Qoene sends return.received and return.inspected; refund the customer from your shop.

Your return policy

Return policy
SettingMeaning
WindowDays after delivery or collection (default 14). Later requests answer 409 WINDOW_CLOSED.
ReasonsCHANGED_MIND, WRONG_SIZE, WRONG_ITEM, DAMAGED, DEFECTIVE, NOT_AS_DESCRIBED, LATE, OTHER (a note is required)
Who paysMERCHANT (your wallet or invoice), CUSTOMER (Mobile Money before the code works) or DEDUCT_FROM_REFUND (billed to you; deductFromRefundMinor says what to keep back)
OptionsRELAY_POINT (drop-off at a Qoene Point), RELAY_LOCKER (when lockers go live), EXPRESS_STANDARD (a rider collects inside an Express area)
ApprovalAUTO or MANUAL; a value above your maximum always waits for review
Return pointThe 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_DROPOFF
curl -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[].line is the line number in the original order (1-based); leave out quantity to 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 needs returns.read.
  • The drop-off code is only ever sent to your customer. The API shows its state (code.status), never the code.

Statuses

Return statuses
StatusMeaning
REQUESTEDWaiting for your review
AWAITING_PAYMENTApproved; the customer pays by Mobile Money before the code works
AWAITING_DROPOFFThe code is active until dropoffBy (14 days)
DROPPED_OFF, IN_TRANSITQoene has it
ARRIVEDReady for you at your return point
RECEIVEDHanded to you
INSPECTEDYou recorded its condition
REJECTED, CANCELLED, EXPIREDClosed. 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.