Returns
Start a return for your customer
POST/returns
Scope returns.writeLIVE keys onlyIdempotency-Key required
For a delivered or collected LIVE parcel inside your return window (409 WINDOW_CLOSED after it), one open return per parcel (409 RETURN_OPEN). A return you start is approved at once: Qoene books the return parcel (billed to your wallet or invoice unless your policy makes the customer pay) and sends your customer a paperless drop-off code by SMS, WhatsApp and email. Customers can also start returns themselves from the Qoene tracking page; those follow your policy (automatic or your review).
Request
Headers
| Name | In | Type | Description |
|---|---|---|---|
AuthorizationRequired | header | string | Bearer <API key> |
Idempotency-KeyRequired | header | string | 8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409. See Idempotency.Pattern ^[A-Za-z0-9._:-]{8,160}$ |
Body ReturnCreateRequest
| Field | Type | Description |
|---|---|---|
trackingNumberRequired | string | Tracking number or shipment ID of the delivered LIVE parcel.Pattern ^(?:QDE-[A-F0-9]{24}|QDE[A-Z0-9]{10,33}|QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31})$ |
itemsRequired | array of object | Lines from the original order (all of them when you omit quantity).1–50 items |
lineRequired | integer | |
quantityOptional | integer | |
reasonRequired | ReturnReason | Why the goods come back. |
noteOptional | string or null | Required for OTHER (5–1000 characters). |
productCodeOptional | ReturnProduct | RELAY_POINT: dropped off at a Qoene Point. RELAY_LOCKER: locker drop-off (not live until lockers are deployed). EXPRESS_STANDARD: a rider collects it inside an Express area. |
dropoffPointCodeOptional | string | The Qoene Point where the customer plans to drop off (they may use another point of the same price). |
pickupAddressTextOptional | string | EXPRESS_STANDARD: where the rider collects. |
emailOptional | string | Optional email to send the code to. |
declaredValueMinorOptional | integer | Only when the order lines have no prices. |
prohibitedItemsDeclarationRequired | object | |
acceptedRequired | true | |
versionRequired | string |
Response
| Status | Meaning |
|---|---|
200 | Replay |
201 | Started |
The body is { "status": "success", "data": … }. Fields of data (ReturnCreateResult):
| Field | Type | Description |
|---|---|---|
returnRequired | Return | An e-commerce return: a reverse parcel linked to the original. The customer's phone and the drop-off code are never returned. |
replayedRequired | boolean |
Errors
Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.
| Status | When |
|---|---|
400 | The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed. |
401 | Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked. |
403 | The key lacks the scope, or the operation needs a LIVE key. The key lacks the scope, or this call needs a LIVE key (LIVE_KEY_REQUIRED), or the Business owner is not verified (SENDER_VERIFICATION_REQUIRED). |
404 | Not found for this Business and environment. IDs from another Business or environment are always 404. Not found for this Business and environment. IDs from another Business or the other environment are always 404. |
409 | Idempotency key reused with another body, or the resource changed state. The idempotency key was used with a different body, a reference is already taken, or the resource changed state. |
422 | Eligibility or business rule refused the request; details.reason explains why. A business rule refused the request. details.reason.code says why (for example OVER_PRODUCT_WEIGHT_LIMIT or a point exclusion reason). |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |