Skip to main content

Trackers

Karrio exposes API endpoints that forwards tracking requests to the carrier's API.

Trackers Management APIs​

The trackers management APIs offer a set of endpoints around the karrio unified tracking details object.

Create a tracker

POST /v1/trackers

You can use this endpoint to create a tracker object in the karrio system and get the latest tracking details of the shipment.

tip

The karrio tracker is periodically updated by the karrio worker to stay up to date with the package throughout it's journey.

curl --request POST \
  --url 'https://api.karrio.io/v1/trackers' \
  --header 'Authorization: Token [API_KEY]' \
  --data '{
	"tracking_number": "397538144353",
	"carrier_name": "fedex"
}'

Proxy Request API​

The proxy APIs allow you to send tracking requests to carriers without creating any objects in karrio.

info

In that schenario, karrio is just a proxy that forward requests.

Get tracking details

POST /v1/proxy/tracking

You can use this endpoint to retrieve tracking details from the issuing carrier.

curl --request POST \
  --url 'https://api.karrio.io/v1/proxy/tracking' \
  --header 'Authorization: Token [API_KEY]' \
  --data '{
	"tracking_number": "397538144353",
	"carrier_name": "fedex"
}'

Tracking & Webhooks​

Karrio provides a simple way to track packages and get notified of changes. You can use our Tracking API to track packages and get notified via Webhooks when the status of a package changes.

  • To leverage that combination, create a webhook and subscribe to tracker related events
curl --request POST \
  --url 'https://api.karrio.io/v1/webhooks' \
  --header 'Authorization: Token [API_KEY]' \
  --data '{
  "url": "http://example.com",
  "description": "tracking events webhook",
  "enabled_events": [
    "tracker_created",
    "tracker_updated"
  ]
}'
  • Process the events sent to your webhook
info

The following events samples illustrate the typical payload you will receive.

You can determine your code's behavior based on the event.type, event.data.status.

Note that the event will only be sent when there is a data change (e.g. status change and new milestone event).

{
  "id": "evt_f31270d74fb94e3cb534bdfbf904ccb1",
  "type": "tracker_created",
  "data": {
    "carrier_id": "FEDX",
    "carrier_name": "fedex",
    "delivered": false,
    "events": [
      {
        "code": "CREATED",
        "date": "2023-05-25",
        "description": "Label created and ready for shipment",
        "time": "16:44"
      }
    ],
    "id": "trk_d34e7d3759ee4a2e8694c5affb90c62f",
    "info": {
      "carrier_tracking_link": "https://www.fedex.com/fedextrack/?trknbr=398779539840",
      "customer_name": "DCO MOTORS EAGLE ADI, LLC",
      "shipment_destination_country": "US",
      "shipment_destination_postal_code": "11901-2051",
      "shipment_origin_country": "CA",
      "shipment_origin_postal_code": "T1H5H3",
      "shipment_package_count": "2",
      "shipment_service": "FEDEX INTERNATIONAL ECONOMY",
      "shipping_date": "2023-05-25",
      "source": "api"
    },
    "meta": {
      "carrier": "fedex"
    },
    "metadata": {},
    "object_type": "tracker",
    "status": "pending",
    "test_mode": false,
    "tracking_number": "398779539840"
  },
  "test_mode": false,
  "pending_webhooks": 0,
  "created_at": "2023-05-25T16:44:18.307063+00:00"
}

Learn more about the supported tracking statuses

`pending` - pending
`unknown` - unknown
`delivered` - delivered
`on_hold` - on_hold
`in_transit` - in_transit
`delivery_delayed` - delivery_delayed
`out_for_delivery` - out_for_delivery
`ready_for_pickup` - ready_for_pickup
`delivery_failed` - delivery_failed
tip

For more advanced use cases, you can access the carrier's events details and raw event code.

...
{
  "code": "OD",
  "date": "2023-05-25",
  "description": "On FedEx vehicle for delivery",
  "location": "LOUISVILLE, CO, 80027, US",
  "time": "07:53"
},
...

Next steps​