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

{
  "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