Tracking & Notifications

Community Edition

Core Feature

Every Karrio project comes with comprehensive tracking capabilities, providing real-time shipment monitoring, automated status updates, webhook notifications, and customer communication tools across all connected carriers.

Features

Universal Tracking API

You don’t have to learn multiple carrier tracking systems to monitor packages. Our tracking API makes monitoring FedEx, UPS, DHL, and other carrier shipments as simple as a single API call.

Package Tracking Dashboard

Rate comparison interface with carrier options and pricing

Real-time Status Updates

Get instant tracking updates as packages move through the carrier networks with automatic background polling and synchronization.

Webhook Notifications

Receive real-time webhook notifications for delivery milestones, exceptions, and status changes across all carriers.

Intelligent Event Processing

Our system automatically normalizes tracking events from different carriers into consistent, meaningful status updates.

Background Monitoring

Karrio workers automatically poll carriers for tracking updates, keeping your package statuses synchronized without manual intervention.

Additional features

Karrio extends tracking with proactive exception detection and alerts.
Every tracking request includes comprehensive event history and delivery details.
Karrio manages automatic tracking number validation and carrier detection.
Support for bulk tracking operations and batch status updates.

Data Flow

Package Tracking Flow

API Reference

REST API

Create Tracker

1curl -X POST "https://api.karrio.io/v1/trackers" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "tracking_number": "1Z12345E0205271688",
6    "carrier_name": "ups",
7    "info": {
8      "customer_name": "John Doe",
9      "order_id": "ORDER-12345"
10    }
11  }'

Response:

1{
2  "id": "trk_1234567890",
3  "tracking_number": "1Z12345E0205271688",
4  "carrier_name": "ups",
5  "carrier_id": "ups_production",
6  "status": "in_transit",
7  "estimated_delivery": "2024-01-18",
8  "events": [
9    {
10      "code": "DEPARTED_FACILITY",
11      "description": "Departed from facility",
12      "date": "2024-01-15",
13      "time": "08:30",
14      "location": "Atlanta, GA, US"
15    },
16    {
17      "code": "ARRIVED_AT_FACILITY",
18      "description": "Arrived at destination facility",
19      "date": "2024-01-15",
20      "time": "14:25",
21      "location": "Los Angeles, CA, US"
22    }
23  ],
24  "delivered": false,
25  "info": {
26    "customer_name": "John Doe",
27    "order_id": "ORDER-12345"
28  },
29  "created_at": "2024-01-15T10:30:00Z",
30  "updated_at": "2024-01-15T14:30:00Z"
31}

Get Tracker Status

1curl -X GET "https://api.karrio.io/v1/trackers/trk_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "id": "trk_1234567890",
3  "tracking_number": "1Z12345E0205271688",
4  "carrier_name": "ups",
5  "status": "delivered",
6  "estimated_delivery": "2024-01-18",
7  "delivery_date": "2024-01-17",
8  "delivery_time": "15:30",
9  "events": [
10    {
11      "code": "DELIVERED",
12      "description": "Package delivered to recipient",
13      "date": "2024-01-17",
14      "time": "15:30",
15      "location": "Los Angeles, CA, US",
16      "signed_by": "J. SMITH"
17    },
18    {
19      "code": "OUT_FOR_DELIVERY",
20      "description": "Out for delivery",
21      "date": "2024-01-17",
22      "time": "09:15",
23      "location": "Los Angeles, CA, US"
24    }
25  ],
26  "delivered": true
27}

List Trackers

1curl -X GET "https://api.karrio.io/v1/trackers?status=in_transit&limit=10" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "count": 45,
3  "next": "/v1/trackers?status=in_transit&limit=10&offset=10",
4  "previous": null,
5  "results": [
6    {
7      "id": "trk_1234567890",
8      "tracking_number": "1Z12345E0205271688",
9      "carrier_name": "ups",
10      "status": "in_transit",
11      "estimated_delivery": "2024-01-18",
12      "created_at": "2024-01-15T10:30:00Z"
13    },
14    {
15      "id": "trk_0987654321",
16      "tracking_number": "1234567890123456",
17      "carrier_name": "fedex",
18      "status": "in_transit",
19      "estimated_delivery": "2024-01-19",
20      "created_at": "2024-01-15T11:15:00Z"
21    }
22  ]
23}

Bulk Create Trackers

1curl -X POST "https://api.karrio.io/v1/batches/trackers" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "trackers": [
6      {
7        "tracking_number": "1Z12345E0205271688",
8        "carrier_name": "ups"
9      },
10      {
11        "tracking_number": "1234567890123456",
12        "carrier_name": "fedex"
13      },
14      {
15        "tracking_number": "9405511206213025290016",
16        "carrier_name": "usps"
17      }
18    ]
19  }'

Response:

1{
2  "batch_id": "batch_tracking_001",
3  "status": "processing",
4  "total_count": 3,
5  "created_count": 3,
6  "failed_count": 0,
7  "created_trackers": [
8    {
9      "id": "trk_1234567890",
10      "tracking_number": "1Z12345E0205271688",
11      "carrier_name": "ups",
12      "status": "pending"
13    },
14    {
15      "id": "trk_0987654321",
16      "tracking_number": "1234567890123456",
17      "carrier_name": "fedex",
18      "status": "pending"
19    }
20  ]
21}

GraphQL API

Query Trackers

1query GetTrackers($filter: TrackerFilter) {
2  trackers(filter: $filter) {
3    edges {
4      node {
5        id
6        tracking_number
7        carrier_name
8        status
9        estimated_delivery
10        delivered
11        events {
12          code
13          description
14          date
15          time
16          location
17        }
18        created_at
19      }
20    }
21    pageInfo {
22      hasNextPage
23      hasPreviousPage
24    }
25  }
26}

Variables:

1{
2  "filter": {
3    "status": "in_transit",
4    "carrier_name": "fedex"
5  }
6}

Response:

1{
2  "data": {
3    "trackers": {
4      "edges": [
5        {
6          "node": {
7            "id": "trk_0987654321",
8            "tracking_number": "1234567890123456",
9            "carrier_name": "fedex",
10            "status": "in_transit",
11            "estimated_delivery": "2024-01-19",
12            "delivered": false,
13            "events": [
14              {
15                "code": "IN_TRANSIT",
16                "description": "Package in transit",
17                "date": "2024-01-16",
18                "time": "12:45",
19                "location": "Memphis, TN, US"
20              }
21            ],
22            "created_at": "2024-01-15T11:15:00Z"
23          }
24        }
25      ],
26      "pageInfo": {
27        "hasNextPage": true,
28        "hasPreviousPage": false
29      }
30    }
31  }
32}

Create Tracker Mutation

1mutation CreateTracker($data: CreateTrackerMutationInput!) {
2  create_tracker(data: $data) {
3    id
4    tracking_number
5    carrier_name
6    status
7    estimated_delivery
8    events {
9      code
10      description
11      date
12      time
13      location
14    }
15  }
16}

Variables:

1{
2  "data": {
3    "tracking_number": "1Z12345E0205271688",
4    "carrier_name": "ups",
5    "info": {
6      "customer_name": "John Doe",
7      "order_id": "ORDER-12345"
8    }
9  }
10}

Response:

1{
2  "data": {
3    "create_tracker": {
4      "id": "trk_1234567890",
5      "tracking_number": "1Z12345E0205271688",
6      "carrier_name": "ups",
7      "status": "in_transit",
8      "estimated_delivery": "2024-01-18",
9      "events": [
10        {
11          "code": "IN_TRANSIT",
12          "description": "Package in transit",
13          "date": "2024-01-15",
14          "time": "14:30",
15          "location": "Atlanta, GA, US"
16        }
17      ]
18    }
19  }
20}

Tracking Statuses

Standard Statuses

Karrio normalizes carrier-specific statuses into these standard values:

pending - Tracking number created but no carrier data yet
in_transit - Package is moving through carrier network
delivered - Package successfully delivered to recipient
delivery_delayed - Delivery delayed due to various reasons
delivery_failed - Delivery attempt failed
exception - Package encountered an exception or issue
unknown - Status cannot be determined

Webhook Events

Webhook Payload Structure

All tracking webhooks follow this structure:

1{
2  "type": "tracker.updated",
3  "data": {
4    "id": "trk_1234567890",
5    "tracking_number": "1Z12345E0205271688",
6    "carrier_name": "ups",
7    "status": "delivered",
8    "delivered": true,
9    "delivery_date": "2024-01-17",
10    "events": [
11      {
12        "code": "DELIVERED",
13        "description": "Package delivered",
14        "date": "2024-01-17",
15        "time": "15:30",
16        "location": "Los Angeles, CA, US"
17      }
18    ]
19  },
20  "created_at": "2024-01-17T15:35:00Z"
21}

Event Types

tracker.created - New tracker created
tracker.updated - Tracking status updated
tracker.delivered - Package delivered
tracker.exception - Delivery exception occurred

Use Cases

E-commerce Order Tracking

Perfect for online stores providing customer visibility:

Order Status Updates: Automatically update order status based on tracking
Customer Notifications: Send tracking updates via email or SMS
Delivery Confirmation: Confirm deliveries and update order status
Exception Handling: Alert customers about delivery issues

Logistics Operations

Designed for shipping and logistics companies:

Fleet Monitoring: Track packages across entire logistics network
Performance Analytics: Analyze delivery performance and carrier SLAs
Exception Management: Proactively handle delivery exceptions
Customer Service: Provide accurate tracking information to customers

Multi-Tenant Platforms

Handle tracking for multiple organizations:

Isolated Tracking: Each tenant’s tracking data is completely separate
Custom Webhooks: Configure different webhook endpoints per tenant
Branded Notifications: Send tracking updates with tenant branding
Usage Analytics: Track API usage and performance per tenant

Getting Started

Ready to start tracking packages with Karrio? Follow these steps:

Connect your carriers using carrier connections
Create trackers for your shipments or existing tracking numbers
Set up webhooks to receive real-time status updates
Monitor deliveries through the dashboard or API

Next Steps

Configure webhooks for real-time tracking notifications
Learn about shipments to create trackable packages
Explore batch processing for bulk tracking operations
Set up events for comprehensive activity monitoring

Questions? Join our community Discord or contact our support team for tracking implementation guidance.

Product Guides

Control Plane

Developer Tools

Tracking & Notifications

Features

Universal Tracking API

Real-time Status Updates

Webhook Notifications

Intelligent Event Processing

Background Monitoring

Additional features

Data Flow

Package Tracking Flow

API Reference

REST API

Create Tracker

Get Tracker Status

List Trackers

Bulk Create Trackers

GraphQL API

Query Trackers

Create Tracker Mutation

Tracking Statuses

Standard Statuses

Webhook Events

Webhook Payload Structure

Event Types

Use Cases

E-commerce Order Tracking

Logistics Operations

Multi-Tenant Platforms

Getting Started

Next Steps