Skip to main content
After an order is created, Yonne provides two mechanisms to track it: a tracking link you surface to customers, and webhooks that push status changes to your backend in real time.

​
The two tracking tools

ToolWho it’s forHow it works
tracking_linkYour customerA hosted Yonne page showing live rider location
WebhooksYour serverHTTP POST to your endpoint on every status change
Use both. The tracking link gives customers a zero-effort view. Webhooks let your backend react to status changes without polling.
Every successful create-order response includes a tracking_link: 
{
  "tracking_id": "YON-TRK-123456",
  "tracking_link": "https://yonne.app/track/YON-TRK-123456"
}
Show this on your order confirmation page and in your post-purchase email: 
<a href="{{ tracking_link }}">Track your delivery in real time →</a>

​
Polling (fallback only)

If you need order status and missed a webhook event, poll the tracking endpoint: 
curl --request GET "https://api.yonne.app/api/v1/external/track/YON-TRK-123456" \
  --header "X-API-Key: yonne_live_xxxxxxxxx"
Do not poll on a tight interval. Use webhooks as your primary update mechanism and polling only for reconciliation or support lookups.

​
Webhooks as the primary update source

Configure a webhook endpoint in your Yonne dashboard. Yonne will POST a JSON payload to your URL on every order status change. Example payload: 
{
  "event": "order.status_updated",
  "order_id": "ORD-123456",
  "tracking_id": "YON-TRK-123456",
  "status": "In Transit",
  "merchant_reference_id": "WEB-100245",
  "metadata": {
    "channel": "woocommerce"
  },
  "timestamp": "2025-05-18T10:32:00Z"
}
Your webhook handler should:
  1. Verify the HMAC-SHA256 signature (see Webhook Setup & Security)
  2. Look up the order by order_id or merchant_reference_id
  3. Update the order status in your database
  4. Trigger any downstream logic (customer notification, OMS update, support tool refresh)
  5. Return 200 OK

​
Order status lifecycle

searching → assigned → picked_up → in_transit → delivered
                                                      │
                                              (terminal state)
                                              
Any state → cancelled (if eligible)
StatusWhat it meansSuggested UX
searchingLooking for an available rider”Finding your rider…”
assignedRider confirmed”Rider is heading to the store”
picked_upItem collected from merchant”Your order is on the way!”
in_transitRider en route to customerShow real-time tracking link
deliveredOrder handed to customer”Delivered — enjoy!”
cancelledOrder cancelledRefund or retry flow

​
Testing your webhook handler

Use the simulate-status endpoint to push status changes in test mode without waiting for a real rider: 
curl --request POST "https://api.yonne.app/api/v1/external/test/simulate-status" \
  --header "X-API-Key: yonne_test_xxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "order_id": "ORD-123456",
    "status": "In Transit"
  }'
Walk through every status in sequence during QA to confirm your handler updates state correctly at each transition.

​
Reconciliation strategy

If your webhook receiver goes down and misses events:
  1. On recovery, query GET /api/v1/external/track/:tracking_id for any orders in a non-terminal state.
  2. Update your database to match the current Yonne status.
  3. Trigger any missed downstream actions (notifications, OMS updates).
Keep both order_id and tracking_id in your database from the moment the order is created — you’ll need them for this reconciliation.