How to Track a Shipment

Which tracking do I need?

Track Easyship shipments

Track shipments from other providers

1. Check that the courier is supported

   You can filter by umbrella_name (e.g. DHL) and origin_country_alpha2.

   cURLGET /2024-09/trackings/supported_couriers

   curl "https://public-api.easyship.com/2024-09/trackings/supported_couriers?umbrella_name=DHL&origin_country_alpha2=US" \ -H "Authorization: Bearer $EASYSHIP_TOKEN"

   Response200 OK

   { "courier_services": [ { "id": "137a79e8-ae1c-4369-9855-44cf8ff784c4", "name": "DHL Express", "umbrella_name": "DHL", "origin_country_alpha2": "US" } ] }

   Pass the id you get back as courier_service_id in the next step.

   Courier not in that list? If Easyship doesn't generate labels for the courier, send courier_service_name instead of courier_service_id. Get the exact name from GET /trackings/external_courier_services.
2. Register the tracking number

   cURLPOST /2024-09/trackings

   curl -X POST https://public-api.easyship.com/2024-09/trackings \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tracking_number": "0114827", "courier_service_id": "137a79e8-ae1c-4369-9855-44cf8ff784c4", "platform_order_number": "ORDER-1001", "origin_address_id": "01563646-58c1-4607-8fe0-cae3e33c0001", "destination_address": { "line_1": "123 Test Street", "city": "Singapore", "state": "Singapore", "postal_code": "247964", "country_alpha2": "SG", "contact_name": "Foo Bar", "contact_phone": "+65 6910 1185", "contact_email": "[email protected]" }, "items": [{ "description": "iPhone", "quantity": 1 }] }'

   Field	Notes
   tracking_number	Required. The courier's tracking number
   courier_service_id or courier_service_name	One is required: the ID from step 1, or the name from /trackings/external_courier_services
   platform_order_number	Your order number. It makes it easy to match webhooks to orders
   origin_address_id or origin_address	A saved address ID, or the full address
   destination_address	The full delivery address
   items	description and quantity

3. Check status

   cURLGET /2024-09/trackings

   # One tracking curl https://public-api.easyship.com/2024-09/trackings/{tracking_id} \ -H "Authorization: Bearer $EASYSHIP_TOKEN" # Many, filtered (origin_country_alpha2, destination_country_alpha2, source=easyship|external, tracking_state) curl "https://public-api.easyship.com/2024-09/trackings?tracking_state=active" \ -H "Authorization: Bearer $EASYSHIP_TOKEN"

   Each tracking in the response has two status fields:

   • status: the latest courier status in plain words, e.g. In Transit or Delivered. Show this to your users.
   • tracking_state: the state of Easyship's tracking for this number. Use it to filter, e.g. ?tracking_state=active.

   Each tracking also includes eta_date and a tracking_page_url.

   tracking_state	Meaning
   active	Easyship is tracking the number and recording courier updates. Trackings created with POST /trackings start here.
   completed	The courier reported a final event (e.g. delivered). No more updates.
   pending	Multi-leg shipments only: a later leg that is waiting for the previous leg to complete. It becomes active automatically.
   created	Registered but tracking hasn't started yet. Rarely seen through the API.
   overwritten_by_admin	Replaced or switched off by Easyship, e.g. after a tracking number correction. No longer updated.

Get updates by webhook

Every poll counts against your API rate limits. In production, subscribe to these events with the Webhooks API instead:

FAQ and testing

Related