Claims
File a claim for a parcel
POST/claims
Scope claims.writeLIVE keys onlyIdempotency-Key required
Loss, damage, missing items, delay (the delivery promise was missed) or a wrong delivery, inside the product's claim window (409 CLAIM_WINDOW_CLOSED after it). One open claim per parcel and reason (409 CLAIM_ALREADY_OPEN). Qoene checks the parcel's custody record automatically; a supervisor decides and you receive claim.* events. Add photos or documents with POST /claims/{claimId}/evidence.
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 ClaimCreateRequest
| Field | Type | Description |
|---|---|---|
trackingNumberRequired | string | Tracking number or shipment ID of your 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})$ |
reasonRequired | ClaimReason | LOSS, DAMAGE, MISSING_ITEMS, DELAY (the delivery promise was missed) or WRONG_DELIVERY. |
descriptionRequired | string | What happened, 20–3000 characters.20–3000 characters |
declaredValueMinorRequired | integer | Value of the contents in pesewas; required above 0 except for DELAY.0 to 100000000 |
Response
| Status | Meaning |
|---|---|
200 | Replay |
201 | Filed |
The body is { "status": "success", "data": … }. Fields of data (ClaimCreateResult):
| Field | Type | Description |
|---|---|---|
claimRequired | Claim | A parcel claim. Internal liability findings and staff names 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. |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |