Guides
Tracking with milestones
Show buyers a small set of stable milestones instead of internal statuses. Routes, hubs and internal statuses can change; milestone codes do not.
Read tracking
const { tracking } = await qoene.shipments.tracking(shipmentId);
console.log(tracking.milestoneLabel); // "Ready for pickup"
for (const step of tracking.milestones) {
console.log(step.state === 'done' ? '✓' : step.state === 'current' ? '●' : '○', step.label, step.at ?? '');
}
if (tracking.exception) console.log(tracking.exception.title, tracking.exception.nextSteps);curl https://api.qoenedelivery.com/v1/shipments/QD-SHP-…/tracking \
-H "Authorization: Bearer $QOENE_API_KEY"$tracking = json_decode((string) $client->get("shipments/{$shipmentId}/tracking")->getBody(), true)['data']['tracking'];
echo $tracking['milestoneLabel'];tracking = requests.get(f"https://api.qoenedelivery.com/v1/shipments/{shipment_id}/tracking", headers=headers, timeout=30).json()["data"]["tracking"]
print(tracking["milestoneLabel"])| Field | Meaning |
|---|---|
milestone, milestoneLabel | The current step code and its plain label |
milestones | The product's main steps, each { code, label, state, at } with state done, current or upcoming |
viewMode | Which layout fits now: IN_TRANSIT, OUT_FOR_DELIVERY, READY_AT_POINT, READY_IN_LOCKER, DELIVERED, EXCEPTION or RETURNING |
exception | null, or { code, title, nextSteps, at } while the parcel is off its main track |
returnTrack | null, or the return steps while the parcel goes back to you |
status, events | Detailed internal status and timeline, for your support team |
Steps by product
| Product | Main steps |
|---|---|
| Express Standard and Priority | BOOKED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED |
| Relay Point | BOOKED → DROPPED_OFF → IN_TRANSIT → ARRIVING_AT_POINT → READY_FOR_PICKUP → COLLECTED |
| Relay Locker | BOOKED → DROPPED_OFF → IN_TRANSIT → ARRIVING_AT_LOCKER → READY_FOR_PICKUP ("Ready in locker") → COLLECTED |
| Relay Home | BOOKED → DROPPED_OFF → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED |
| Relay Home, attempt failed | … → OUT_FOR_DELIVERY → DELIVERY_ATTEMPT_FAILED, then the Relay Point steps: IN_TRANSIT → ARRIVING_AT_POINT → READY_FOR_PICKUP → COLLECTED at the fallback point |
Relay Home gets one home attempt from the destination hub's daily run. If it fails, the parcel goes to the fallback Qoene Point chosen at booking (send fallbackLocationCode with the quote, or let Qoene pick the nearest suitable point) and the receiver gets the point, its hours and a pickup code by SMS. Subscribe to shipment.home_attempt_failed and shipment.redirected_to_point to follow it.
Receiver choices and overstay
After verifying with the tracking number and a code sent to their phone, the receiver can change the destination Qoene Point or locker (until the parcel leaves the origin hub), change a Relay Home fallback point (before the home attempt) and extend the hold. Each change revises the promise (reason RECEIVER_CHANGE) and sends shipment.receiver_changed; GET /shipments/{shipmentId} and its tracking list them in receiverChanges.
A parcel waits free for the hold the sender booked. After that, overstay is charged per day up to a cap and the receiver pays it by Mobile Money at pickup: the locker opens, and a point releases the parcel, only once the payment is confirmed. If your contract covers overstay, your wallet pays it automatically up to the contract limit and the receiver pays the rest. Read overstay on the shipment and subscribe to shipment.overstay_started and shipment.overstay_paid.
Exceptions: PICKUP_ATTEMPT_FAILED, DELIVERY_ATTEMPT_FAILED, ON_HOLD, DAMAGED, LOST, CANCELLED. Returns: RETURN_REQUESTED, RETURNING, BACK_AT_DROPOFF_POINT, RETURNED.
Keep it up to date
- Subscribe to
shipment.status_changed(or specific events such asshipment.ready_for_pickup) and refresh tracking when one arrives. See Webhooks. shipment.pickup_expiringtells you a buyer has less than 24 hours left to collect from a point, so you can remind them.- To find parcels in a state, list with a filter:
GET /shipments?milestone=READY_FOR_PICKUP. - An unpaid or not-yet-dropped-off parcel shows
BOOKEDas its current step with no time. Use the payment APIs for payment state.