# Multi-Carrier Package Tracking (`muhammadafzal/multi-carrier-package-tracking`) Actor

Track public USPS, UPS, and FedEx shipments with normalized status, delivery estimates, latest events, and masked diagnostics for operations and AI workflows.

- **URL**: https://apify.com/muhammadafzal/multi-carrier-package-tracking.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Automation, Other
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 package tracking results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Multi-Carrier Package Tracking (USPS, UPS, FedEx)

Track public USPS, UPS, and FedEx shipments in one Apify Actor and receive a normalized dataset for ecommerce operations, support workflows, delivery monitoring, and AI agents.

The Actor accepts a mixed list of tracking numbers, detects unambiguous carrier formats, opens each carrier's public tracking flow in a consistent browser and residential-proxy session, and converts the available status into one stable JSON contract. It requires no carrier login or developer account. It does not solve CAPTCHAs or expose authenticated shipment documents.

### What it extracts

Each active public shipment produces one dataset item. Missing carrier fields are returned as `null`; the Actor never guesses them.

| Field | Meaning |
| --- | --- |
| `trackingNumber` | Normalized tracking number |
| `carrier` | `USPS`, `UPS`, or `FedEx` |
| `status` | Cross-carrier category such as `in_transit`, `out_for_delivery`, or `delivered` |
| `statusText` | Current carrier-provided status text |
| `terminal` | Whether the package is delivered or returned |
| `delivered` / `delayed` | Automation-friendly state flags |
| `estimatedDelivery` | Public delivery estimate when available |
| `actualDelivery` | Public delivery date or timestamp when available |
| `service` | Public carrier service name when available |
| `origin` / `destination` | Public location summaries when exposed |
| `lastEvent` | Latest scan or progress event |
| `events` | Public tracking history when requested and exposed |
| `sourceUrl` / `scrapedAt` | Carrier page and UTC extraction time |

Invalid, ambiguous, inactive, challenged, or failed lookups are not inserted as fake shipment rows. Masked diagnostics are stored in the `OUTPUT` key-value-store record with an outcome of `DATA`, `EMPTY`, `BLOCKED`, `REJECTED`, or `FAILED`.

### When to use it

Use this Actor for small, current batches of shipments you own, administer, or are authorized to monitor. Common workflows include checking fulfillment exceptions, enriching helpdesk tickets, monitoring orders on a schedule, feeding normalized status into Make, Zapier, or n8n, and giving an AI agent one contract across three US carriers.

Do not use it to create labels, calculate rates, change delivery instructions, submit claims, retrieve proof-of-delivery signatures, or run a high-volume carrier integration. Those workflows belong on the carriers' authenticated APIs. Public tracking records can expire, and carrier sites can suppress details based on shipment age, service, or destination.

### Input

| Field | Required | Default | Notes |
| --- | --- | --- | --- |
| `trackingNumbers` | Yes | Public inactive UPS sample | 1–25 numbers; spaces, hyphens, and duplicates are removed |
| `carrier` | No | `auto` | Use an explicit carrier for ambiguous numeric formats |
| `includeDetailedEvents` | No | `true` | Return public event history where extractable |
| `requestTimeoutSecs` | No | `45` | 20–90 seconds per lookup |
| `proxyConfiguration` | No | Apify Residential, US | Recommended because public carrier pages reject many datacenter sessions |

Automatic detection is conservative. UPS numbers beginning with `1Z`, common USPS domestic and international formats, and 12- or 15-digit FedEx numbers are recognized. Some all-numeric formats overlap between carriers; the Actor rejects those as ambiguous instead of querying the wrong company. Set `carrier` explicitly when a whole batch belongs to one carrier.

#### Mixed-carrier Console input

```json
{
  "trackingNumbers": [
    "1Z999AA10123456784",
    "9400111899223856928499",
    "794644790138"
  ],
  "carrier": "auto",
  "includeDetailedEvents": true,
  "requestTimeoutSecs": 45,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

#### Explicit-carrier input

```json
{
  "trackingNumbers": ["YOUR_AMBIGUOUS_NUMERIC_TRACKING_NUMBER"],
  "carrier": "FedEx",
  "includeDetailedEvents": false
}
```

#### API call

```bash
curl -X POST "https://api.apify.com/v2/actors/YOUR_USERNAME~multi-carrier-package-tracking/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumbers":["YOUR_TRACKING_NUMBER"],"carrier":"auto"}'
```

Keep Apify tokens in authorization headers or secret stores. Tracking numbers and delivery details can be sensitive, so avoid placing them in public logs, issue reports, or URLs outside the intended carrier flow.

### Output example

```json
{
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS",
  "status": "delivered",
  "statusText": "Delivered",
  "terminal": true,
  "delivered": true,
  "delayed": false,
  "estimatedDelivery": null,
  "actualDelivery": null,
  "service": null,
  "origin": null,
  "destination": null,
  "lastEvent": {
    "timestamp": null,
    "status": "Delivered",
    "description": null,
    "location": "Austin, TX"
  },
  "events": [],
  "sourceUrl": "https://www.ups.com/track?loc=en_US&tracknum=1Z999AA10123456784",
  "scrapedAt": "2026-09-09T12:00:00.000Z"
}
```

### Pay per event pricing

| Event | Price | Trigger |
| --- | ---: | --- |
| Tracking run start | $0.005 | Once when a run starts |
| Package tracking result | $0.020 | Each schema-valid dataset item |

An inactive, invalid, ambiguous, or blocked number produces no result-item charge. A run with one found shipment costs about `$0.025` in events; ten found shipments cost about `$0.205`. The Actor checks the run's maximum charge before crawling additional potential results and never manually charges Apify's synthetic start or dataset-item events.

### Reliability and failure behavior

USPS, UPS, and FedEx all restrict automated datacenter traffic on parts of their public tracking sites. The Actor therefore uses a real browser, one coherent user agent, cookie jar, US locale, timezone, and sticky proxy identity. Images, fonts, media, and common analytics are blocked to reduce bandwidth while retaining tracking scripts. Lookups run sequentially, and an access challenge gets one bounded retry with a fresh session.

The Actor does not bypass a CAPTCHA or authentication wall. A repeated carrier challenge becomes `BLOCKED` with zero fabricated rows and zero result-item events. An inactive or expired number becomes `EMPTY`; a malformed or ambiguous number becomes `REJECTED`; a rendering or upstream defect becomes `FAILED`. Valid results from other numbers are preserved when one lookup fails. Carrier markup and page-owned JSON can change, so business-critical or high-volume users should use official authenticated carrier APIs.

### Privacy, legal use, and compliance

Run this Actor only for shipments you own, operate, support, or have permission to monitor. Keep runs and datasets private, apply short retention, and avoid publishing recipient names, precise delivery locations, or tracking numbers. The Actor masks tracking numbers in diagnostics and intentionally excludes proof-of-delivery images and signatures. You are responsible for applicable carrier terms, privacy law, contractual duties, and data-retention rules.

This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by the United States Postal Service, United Parcel Service, or FedEx. Carrier names and trademarks are used descriptively to identify public sources.

### Support

When reporting a problem, share the Apify run ID, outcome, carrier, and timestamp. Do not post a complete tracking number or recipient data in a public issue; the first two and last four characters are sufficient for most diagnostics.

# Actor input Schema

## `trackingNumbers` (type: `array`):

Use this for 1–25 USPS, UPS, or FedEx tracking numbers. Enter one value per row, for example 1Z999AA10123456784. Duplicates, spaces, and hyphens are removed.

## `carrier` (type: `string`):

Use Auto detect for mixed batches. Choose USPS, UPS, or FedEx when every number belongs to one carrier or an all-numeric format is ambiguous.

## `includeDetailedEvents` (type: `boolean`):

Use this to include the public scan or progress events exposed by the carrier. Disable it for smaller output; current status is always returned.

## `requestTimeoutSecs` (type: `integer`):

Use this to limit each carrier lookup. Accepted range is 20–90 seconds; default is 45 seconds.

## `proxyConfiguration` (type: `object`):

Use this to control network routing. Apify Residential US is the default because carrier pages often reject datacenter traffic; this is not a carrier API credential.

## Actor input object example

```json
{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ],
  "carrier": "auto",
  "includeDetailedEvents": true,
  "requestTimeoutSecs": 45,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Schema-validated tracking records in the default dataset.

## `output` (type: `string`):

Outcome counts and masked diagnostics for the run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "trackingNumbers": [
        "1Z999AA10123456784"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/multi-carrier-package-tracking").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "trackingNumbers": ["1Z999AA10123456784"] }

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/multi-carrier-package-tracking").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ]
}' |
apify call muhammadafzal/multi-carrier-package-tracking --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/multi-carrier-package-tracking"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QXKrnDz1DPcAsyGp9/builds/hz7evpkxtYFPfpcir/openapi.json