# UPS Tracking Shipments (`matt-de-laur/ups-tracking-shipments`) Actor Track any UPS shipment by tracking number. Returns full scan history, proof of delivery, origin and destination details, customs events, and all packages in a multi-piece shipment. - **URL**: https://apify.com/matt-de-laur/ups-tracking-shipments.md - **Developed by:** [Matt de Laur](https://apify.com/matt-de-laur) (community) - **Categories:** Automation, Developer tools, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 ups tracking result retrieveds 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## UPS Tracking Shipments Track any UPS shipment by tracking number and get structured, ready-to-use data in seconds. Input one or more UPS tracking numbers and receive current status, complete scan history, proof of delivery, origin and destination details, customs events, and per-package summaries for multi-piece shipments. Ideal for logistics teams, e-commerce operations, and data pipelines that need reliable UPS tracking data at scale. ### What you get - **Current status** with progress percentage, delay flag, and next expected event - **Complete scan history** sorted oldest to newest, with UPS activity codes, GMT timestamps, and brokerage event flags - **High-level milestones** (Label Created, In Transit, Out for Delivery, Delivered) in chronological order - **Proof of delivery** including delivered date, time, recipient name, and signature details - **Origin and destination** with city, state, country, timezone offsets, and commercial address flag - **Shipment details** including service name, weight, reference numbers, PO number, and description of goods - **All packages** in the same shipment for multi-piece tracking - **Live dashboard** served at the container URL while the actor is running, with a JSON API ### Input | Field | Type | Required | Default | Description | |---|---|---|---|---| | `tracking_numbers` | string[] | Yes | | UPS tracking numbers (e.g. `1Z53F19R0498293794`) | | `fetch_pod` | boolean | No | `true` | Fetch proof of delivery for each package | | `fetch_additional_packages` | boolean | No | `true` | Fetch all packages in the same shipment | | `max_track_numbers` | integer | No | `10000` | Max additional packages to retrieve per shipment | ### Output Each tracking number produces one dataset record. #### Identity | Field | Type | Description | |---|---|---| | `trackingNumber` | string | UPS tracking number | | `trackingNumberType` | string | Format type (e.g. `1Z`) | | `senderShipperNumber` | string | Shipper account number | #### Status | Field | Type | Description | |---|---|---| | `packageStatus` | string | Status text (e.g. `Delivered`, `In Transit`, `Exception`) | | `packageStatusType` | string | Code: `D` Delivered, `I` In Transit, `X` Exception, `P` Pickup | | `packageStatusCode` | string | UPS internal status code (e.g. `011`) | | `progressBarPercentage` | integer | Delivery progress from 0 to 100 | | `isDelivered` | boolean | True when delivery is confirmed | | `isDelayedPackage` | boolean | True when UPS has flagged the shipment as delayed | | `nextExpectedEvent` | string | Next expected tracking event for in-transit packages | | `hasBrokerageEvent` | boolean | True when customs or brokerage events are present | | `alertCount` | integer | Number of active alerts on this package | #### Delivery | Field | Type | Description | |---|---|---| | `deliveredDate` | string | Delivery date in MM/DD/YYYY format, sourced from proof of delivery when available | | `deliveredTime` | string | Delivery time, sourced from proof of delivery when available | | `receivedBy` | string | Name or code of the recipient | | `signatureType` | string | Signature requirement type | | `proofOfDeliveryUrl` | string | Direct link to the UPS proof of delivery page | #### Destination | Field | Type | Description | |---|---|---| | `shipToCity` | string | Destination city | | `shipToState` | string | Destination state or province | | `shipToCountry` | string | Destination country code (e.g. `US`) | | `shipToZipCode` | string | Destination postal code | | `shipToCompany` | string | Destination company name | | `isCommercialAddress` | boolean | True when delivered to a commercial address | #### Origin | Field | Type | Description | |---|---|---| | `shipFromCity` | string | Origin city, sourced from proof of delivery | | `shipFromState` | string | Origin state or province, sourced from proof of delivery | | `shipFromCountry` | string | Origin country code, sourced from proof of delivery | | `shipFromGMTOffset` | string | Timezone offset of the origin location (e.g. `+08:00`) | | `shipToGMTOffset` | string | Timezone offset of the destination location (e.g. `-04:00`) | #### Last Scan | Field | Type | Description | |---|---|---| | `lastScanDate` | string | Date of the most recent scan | | `lastScanTime` | string | Time of the most recent scan | | `lastScanLocation` | string | Location of the most recent scan | | `lastScanActivity` | string | Activity description of the most recent scan | | `lastScanGmtDate` | string | GMT date of the most recent scan in `YYYYMMDD` format | | `lastScanGmtTime` | string | GMT time of the most recent scan in `HH:MM:SS` format | | `lastScanGmtOffset` | string | GMT offset of the scan location | | `lastScanActCode` | string | UPS activity code (e.g. `KB` = delivered, `AR` = arrived at facility, `DP` = departed, `EP` = export scan) | #### Service and Shipment Info | Field | Type | Description | |---|---|---| | `serviceName` | string | UPS service name (e.g. `UPS Worldwide Express Saver®`) | | `shippedOrBilledDate` | string | Date the shipment was created or billed | | `weight` | string | Package weight | | `weightUnit` | string | Unit of weight (`LBS` or `KGS`) | | `numberOfPieces` | integer | Number of pieces in the shipment | | `isSmallPackage` | boolean | True when UPS classifies this as a small package | | `descriptionOfGood` | string | Description of the shipped goods | | `referenceNumbers` | array | Shipper-assigned reference numbers | | `poNumber` | string | Purchase order number | | `blNumber` | string | Bill of lading number | | `alternateTrackingNumbers` | array | Postal service or alternate tracking numbers | | `additionalPackagesCount` | integer | Total number of packages in the shipment | #### Detailed History | Field | Type | Description | |---|---|---| | `milestones` | array | High-level milestone events sorted oldest to newest. Each item: `{ name, date, time, location, isCurrent, isCompleted }` | | `shipmentProgressActivities` | array | Complete scan history sorted oldest to newest. Each item: `{ date, time, location, activityScan, actCode, gmtDate, gmtTime, gmtOffset, isBrokerageEvent, milestoneName }` | #### Proof of Delivery and Related Packages | Field | Type | Description | |---|---|---| | `proofOfDelivery` | object | Proof of delivery details: `{ deliveredDate, deliveredTime, receivedBy, signatureType, weight, referenceNumbers, poNumber, shipToAddress, shipFrom, alternateTrackingNumbers }` | | `additionalPackages` | array | All packages in the same shipment. Each item: `{ trackingNumber, packageStatus, packageStatusType, packageStatusCode, isDelivered, packageStatusTime, shipperName, shipToCity, shipToState, shipToCountry }` | #### Metadata | Field | Type | Description | |---|---|---| | `trackedDateTime` | string | UPS server timestamp when the tracking data was last refreshed | | `fetchedAt` | string | ISO 8601 timestamp of when the actor fetched the data | | `error` | string | Error message if tracking failed for this number | ### Example output ```json { "trackingNumber": "1Z53F19R0498293794", "trackingNumberType": "1Z", "senderShipperNumber": "53F19R", "packageStatus": "Delivered", "packageStatusType": "D", "packageStatusCode": "011", "progressBarPercentage": 100, "isDelivered": true, "isDelayedPackage": false, "nextExpectedEvent": null, "hasBrokerageEvent": true, "alertCount": 0, "deliveredDate": "04/14/2026", "deliveredTime": "10:25 A.M.", "receivedBy": "SOF", "signatureType": null, "proofOfDeliveryUrl": "https://wwwapps.ups.com/WebTracking/processPOD?loc=en_US&tracknum=1Z53F19R0498293794", "shipToCity": "NEW STANTON", "shipToState": "PA", "shipToCountry": "US", "shipToZipCode": null, "shipToCompany": null, "isCommercialAddress": true, "shipFromCity": null, "shipFromState": null, "shipFromCountry": null, "shipFromGMTOffset": "+08:00", "shipToGMTOffset": "-04:00", "lastScanDate": "04/14/2026", "lastScanTime": "10:25 A.M.", "lastScanLocation": "NEW STANTON, PA, US", "lastScanActivity": "DELIVERED", "lastScanGmtDate": "20260414", "lastScanGmtTime": "14:25:00", "lastScanGmtOffset": "-04:00", "lastScanActCode": "KB", "serviceName": "UPS Worldwide Express Saver®", "shippedOrBilledDate": "04/07/2026", "weight": null, "weightUnit": null, "numberOfPieces": null, "isSmallPackage": true, "descriptionOfGood": null, "referenceNumbers": null, "poNumber": null, "blNumber": null, "alternateTrackingNumbers": null, "additionalPackagesCount": 19, "milestones": [ { "name": "Label Created", "date": "04/07/2026", "time": "11:53 A.M.", "location": "Hong Kong", "isCurrent": false, "isCompleted": true }, { "name": "We have your Package", "date": "04/08/2026", "time": "3:14 A.M.", "location": "Chek Lap Kok, Hong Kong", "isCurrent": false, "isCompleted": true }, { "name": "On the Way", "date": "04/13/2026", "time": "10:15 A.M.", "location": "New Stanton, PA, United States", "isCurrent": false, "isCompleted": true }, { "name": "Delivered", "date": "04/14/2026", "time": "10:25 A.M.", "location": "NEW STANTON, PA, US", "isCurrent": true, "isCompleted": true } ], "shipmentProgressActivities": [ { "date": "04/07/2026", "time": "11:53 A.M.", "location": "Hong Kong", "activityScan": "Shipper created a label, UPS has not received the package yet.", "actCode": "MP", "gmtDate": "20260407", "gmtTime": "03:53:12", "gmtOffset": "+08:00", "isBrokerageEvent": false, "milestoneName": "Label Created" }, { "date": "04/08/2026", "time": "3:14 A.M.", "location": "Chek Lap Kok, Hong Kong", "activityScan": "Arrived at Facility", "actCode": "OR", "gmtDate": "20260407", "gmtTime": "19:14:29", "gmtOffset": "+08:00", "isBrokerageEvent": false, "milestoneName": "We have your Package" }, { "...": "19 total activities, oldest to newest" }, { "date": "04/14/2026", "time": "10:25 A.M.", "location": "NEW STANTON, PA, US", "activityScan": "DELIVERED", "actCode": "KB", "gmtDate": "20260414", "gmtTime": "14:25:00", "gmtOffset": "-04:00", "isBrokerageEvent": false, "milestoneName": "Delivered" } ], "proofOfDelivery": { "deliveredDate": "04/14/2026", "deliveredTime": "10:25 A.M.", "receivedBy": "SOF", "signatureType": null, "signatureImage": null, "serviceName": "UPS Worldwide Express Saver®", "weight": null, "weightUnit": null, "shippedOrBilledDate": "04/07/2026", "referenceNumbers": null, "poNumber": null, "numberOfPieces": null, "shipToAddress": { "city": "NEW STANTON", "state": "PA", "country": "US", "zipCode": null, "companyName": "", "attentionName": "" }, "shipFrom": null, "alternateTrackingNumbers": null }, "additionalPackages": [ { "trackingNumber": "1Z53F19R0498293794", "packageStatus": "Delivered", "packageStatusType": "D", "packageStatusCode": "011", "isDelivered": true, "packageStatusTime": "10:25 A.M.", "shipperName": null, "shipToCity": "NEW STANTON", "shipToState": "PA", "shipToCountry": "US" }, { "trackingNumber": "1Z53F19R0495069667", "packageStatus": "Delivered", "packageStatusType": "D", "packageStatusCode": "011", "isDelivered": true, "packageStatusTime": "10:25 A.M.", "shipperName": null, "shipToCity": "NEW STANTON", "shipToState": "PA", "shipToCountry": "US" } ], "trackedDateTime": "04/14/2026 11:04 P.M. EST", "fetchedAt": "2026-04-15T03:00:00.000Z" } ```` ### Live view While the actor is running, a dashboard is available at the container URL with the following endpoints: | Endpoint | Description | |---|---| | `/` | HTML progress table, auto-refreshes every 5 seconds | | `/status` | JSON object with run progress (total, processed, pending, done) | | `/results` | JSON array of lightweight tracking results collected so far | | `/openapi.json` | OpenAPI 3.0 schema describing all web server endpoints | # Actor input Schema ## `tracking_numbers` (type: `array`): UPS tracking numbers to track (e.g. 1Z53F19R0498293794). ## `fetch_pod` (type: `boolean`): Fetch proof of delivery data for each delivered package. ## `fetch_additional_packages` (type: `boolean`): Fetch all packages associated with the same shipment. ## `max_track_numbers` (type: `integer`): Maximum number of additional tracking numbers to retrieve per shipment. ## Actor input object example ```json { "tracking_numbers": [ "1Z53F19R0498293794" ], "fetch_pod": true, "fetch_additional_packages": true, "max_track_numbers": 10000 } ``` # Actor output Schema ## `trackingResults` (type: `string`): Dataset items — one record per tracking number, including status, milestones, proof of delivery, and associated packages. ## `liveView` (type: `string`): HTML dashboard showing real-time run progress. Auto-refreshes every 5 seconds while the actor is running. ## `openapiSchema` (type: `string`): OpenAPI 3.0 schema describing the live-view web server endpoints (/status, /results, /openapi.json). # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "tracking_numbers": [ "1Z53F19R0498293794" ] }; // Run the Actor and wait for it to finish const run = await client.actor("matt-de-laur/ups-tracking-shipments").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "tracking_numbers": ["1Z53F19R0498293794"] } # Run the Actor and wait for it to finish run = client.actor("matt-de-laur/ups-tracking-shipments").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "tracking_numbers": [ "1Z53F19R0498293794" ] }' | apify call matt-de-laur/ups-tracking-shipments --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=matt-de-laur/ups-tracking-shipments", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "UPS Tracking Shipments", "description": "Track any UPS shipment by tracking number. Returns full scan history, proof of delivery, origin and destination details, customs events, and all packages in a multi-piece shipment.", "version": "0.1", "x-build-id": "nZWgeiUocHEirBIVt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/matt-de-laur~ups-tracking-shipments/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-matt-de-laur-ups-tracking-shipments", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/matt-de-laur~ups-tracking-shipments/runs": { "post": { "operationId": "runs-sync-matt-de-laur-ups-tracking-shipments", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/matt-de-laur~ups-tracking-shipments/run-sync": { "post": { "operationId": "run-sync-matt-de-laur-ups-tracking-shipments", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "tracking_numbers" ], "properties": { "tracking_numbers": { "title": "Tracking Numbers", "type": "array", "description": "UPS tracking numbers to track (e.g. 1Z53F19R0498293794).", "items": { "type": "string" } }, "fetch_pod": { "title": "Fetch Proof of Delivery", "type": "boolean", "description": "Fetch proof of delivery data for each delivered package.", "default": true }, "fetch_additional_packages": { "title": "Fetch Additional Packages", "type": "boolean", "description": "Fetch all packages associated with the same shipment.", "default": true }, "max_track_numbers": { "title": "Max Additional Track Numbers", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum number of additional tracking numbers to retrieve per shipment.", "default": 10000 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```