Track Parcels

There are two ways to know where a parcel is: ask, or be told. Being told is better — see Notifications — but polling is available and is what most integrations start with.

The current state

curl --request GET \
  --url https://logistics.api.{{BASE_ENV_URL}}/v1/parcels/{{PARCEL_ID}}/status \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Returns the state the parcel is in right now. The full list of states, and which transitions are possible, is in Parcels life cycle — and note that the sequence differs between express and cross-dock modalities.

The full history

curl --request GET \
  --url https://logistics.api.{{BASE_ENV_URL}}/v1/parcels/{{PARCEL_ID}}/timeline \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Returns every state the parcel has been through and when, which is what you want when reconstructing what happened to a delivery after the fact.

The whole parcel

curl --request GET \
  --url https://logistics.api.{{BASE_ENV_URL}}/v1/parcels/{{PARCEL_ID}} \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Returns the complete parcel: state, both locations, contacts, dimensions, price and tracking information.

Several parcels at once

curl --request GET \
  --url 'https://logistics.api.{{BASE_ENV_URL}}/v1/parcels?states=intransit' \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Returns a paginated list of your parcels, optionally filtered by state. Use this to reconcile, not to poll for a single delivery.

🚧

Do not poll tightly

Polling a single parcel in a loop will run into the rate limiter and tells you nothing that a webhook would not have told you sooner. Subscribe to a notification and use these endpoints to reconcile.

Showing tracking to your recipient

If what you want is to let the person receiving the parcel follow it, you do not need to build that: see Parcel tracker.

When it fails