Developers
API referenceBusiness sign in

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"])
Tracking fields
FieldMeaning
milestone, milestoneLabelThe current step code and its plain label
milestonesThe product's main steps, each { code, label, state, at } with state done, current or upcoming
viewModeWhich layout fits now: IN_TRANSIT, OUT_FOR_DELIVERY, READY_AT_POINT, READY_IN_LOCKER, DELIVERED, EXCEPTION or RETURNING
exceptionnull, or { code, title, nextSteps, at } while the parcel is off its main track
returnTracknull, or the return steps while the parcel goes back to you
status, eventsDetailed internal status and timeline, for your support team

Steps by product

Milestones by product
ProductMain steps
Express Standard and PriorityBOOKED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED
Relay PointBOOKED → DROPPED_OFF → IN_TRANSIT → ARRIVING_AT_POINT → READY_FOR_PICKUP → COLLECTED
Relay LockerBOOKED → DROPPED_OFF → IN_TRANSIT → ARRIVING_AT_LOCKER → READY_FOR_PICKUP ("Ready in locker") → COLLECTED
Relay HomeBOOKED → 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 as shipment.ready_for_pickup) and refresh tracking when one arrives. See Webhooks.
  • shipment.pickup_expiring tells 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 BOOKED as its current step with no time. Use the payment APIs for payment state.