UPS APIups.com ↗
Track UPS shipments by tracking number. Returns current status, delivery address, milestones, weight, and full activity history via a single endpoint.
What is the UPS API?
The UPS tracking API exposes 1 endpoint — track_shipment — that returns 10 structured fields for any UPS shipment, including current status, delivery address, package weight, recipient name, and a milestone array covering every key event from pickup through delivery. It accepts standard 1Z tracking numbers as well as UPS Mail Innovations and freight formats, with optional locale support for localized responses.
curl -X GET 'https://api.parse.bot/scraper/a30637a6-b61c-455a-9522-230c551c9adf/track_shipment?tracking_number=1Z999AA10123456784' \ -H 'X-API-Key: $PARSE_API_KEY'
Track a UPS shipment by its tracking number. Returns the current status, delivery information, milestones, and detailed shipment progress activities. Supports UPS tracking number formats (1Z, mail innovations, freight, etc). Each call tracks one shipment; for invalid numbers UPS returns input_format_invalid, for valid-format numbers not found in their system it returns input_not_found.
| Param | Type | Description |
|---|---|---|
| locale | string | Locale for the response language and formatting (e.g. en_US, nl_NL, de_DE). When omitted, defaults to en_US. |
| tracking_numberrequired | string | UPS tracking number (e.g. 1Z999AA10123456784). Supports standard 1Z format and other UPS tracking number formats. |
{
"type": "object",
"fields": {
"status": "Current package status (e.g. Delivered, In Transit, Out for Delivery)",
"weight": "Package weight as string",
"left_at": "Where the package was left, if applicable",
"milestones": "Array of milestone objects showing key shipment events with date, time, location, and name",
"received_by": "Name of person who received the package, if delivered",
"status_code": "Numeric status code from UPS",
"status_type": "Status type code (e.g. D for Delivered, I for In Transit, P for Pickup)",
"ship_to_address": "Destination address object with city, state, country fields",
"tracking_number": "The UPS tracking number",
"delivery_address": "Delivery address object with country and zipCode",
"progress_bar_type": "Progress bar category (e.g. Delivered, InTransit)",
"ship_from_address": "Origin address object, if available",
"service_information": "Object with service_name describing the UPS service used",
"shipped_or_billed_date": "Date the shipment was shipped or billed (MM/DD/YYYY format)",
"progress_bar_percentage": "Progress bar percentage as string (0-100)",
"shipment_progress_activities": "Array of detailed activity objects showing all tracking scans with date, time, location, and activityScan description"
},
"sample": {
"data": {
"status": "Delivered",
"weight": "",
"left_at": "Other",
"milestones": [
{
"date": "",
"name": "Label Created",
"time": "",
"nameKey": "cms.stapp.orderReceived",
"category": null,
"isFuture": false,
"location": "Germany",
"isCurrent": false,
"isRFIDIcon": false,
"isCompleted": true,
"subMilestone": null,
"cTrackingNumber": null,
"pTrackingNumber": null,
"returnTrackingNumber": null
}
],
"received_by": "TAYLOR",
"status_code": "011",
"status_type": "D",
"ship_to_address": {
"city": "LONGVIEW",
"state": "TX",
"country": "US",
"zipCode": "",
"province": null,
"companyName": "",
"attentionName": "",
"isHoldAddress": false,
"streetAddress1": "",
"streetAddress2": "",
"streetAddress3": "",
"isReturnAddress": false,
"isAddressCorrected": false
},
"tracking_number": "1Z999AA10123456784",
"delivery_address": {
"country": "US",
"zipCode": null
},
"progress_bar_type": "Delivered",
"ship_from_address": null,
"service_information": {
"service_name": "UPS Express™ 12:00"
},
"shipped_or_billed_date": "02/16/2026",
"progress_bar_percentage": "100",
"shipment_progress_activities": [
{
"date": "12/05/2025",
"time": "10:29 A.M.",
"actCode": "9E",
"gmtDate": "20251205",
"gmtTime": "16:29:38",
"trailer": "",
"location": "LONGVIEW, TX, US",
"gmtOffset": "-06:00",
"activityScan": "DELIVERED ",
"milestoneName": {
"name": "Delivered",
"nameKey": "cms.stapp.delivered"
},
"exceptionCodes": null,
"isRFIDIconEvent": false,
"isBrokerageEvent": false,
"isDisplayPodLink": true,
"isInOverViewTable": false,
"alternateTrackingNumbers": null,
"activityAdditionalDescription": null
}
]
},
"status": "success"
}
}About the UPS API
What the API Returns
The track_shipment endpoint accepts a tracking_number and an optional locale parameter, then returns a structured object for that shipment. Core fields include status (e.g. "Delivered", "In Transit", "Out for Delivery"), status_type (single-letter code such as D, I, or P), and status_code (numeric UPS status code). Address data comes back in two forms: ship_to_address with city, state, and country, and delivery_address with country and zip code.
Milestones and Delivery Detail
The milestones array contains ordered shipment events, each with a date, time, location, and event name — covering the full journey from pickup to final delivery. On delivered shipments, received_by returns the name of the person who signed or accepted the package, and left_at indicates where it was left when no signature was obtained (e.g. "Front Door"). weight returns the package weight as a string in the carrier-reported unit.
Tracking Number Formats and Locale
The tracking_number input supports UPS standard 1Z format (e.g. 1Z999AA10123456784) as well as Mail Innovations and freight tracking numbers. The locale parameter accepts IETF-style locale strings such as en_US, nl_NL, or de_DE, which controls the language and regional formatting of the response. When omitted, the response defaults to en_US. Each call resolves exactly one tracking number; batch tracking is not supported in the current endpoint.
The UPS API is a managed, monitored endpoint for ups.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ups.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ups.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display real-time delivery status in an order management dashboard using the
statusandstatus_typefields - Send automated delivery notifications when
statustransitions to "Out for Delivery" or "Delivered" - Build a post-purchase tracking page that renders the full
milestonestimeline for customers - Log
received_byandleft_atdata for proof-of-delivery records in logistics software - Populate destination details in a warehouse management system using
ship_to_addressanddelivery_address - Support multi-language storefronts by passing the appropriate
localefor each customer's region - Monitor freight and Mail Innovations shipments alongside standard 1Z parcels in a unified tracking tool
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does UPS have an official developer API for tracking?+
What does the milestones array contain versus the status field?+
status field gives the single current state of the shipment. The milestones array returns every key event in sequence — each with a date, time, location, and event name — so you can reconstruct the full shipment timeline rather than just the latest state.Can I track multiple shipments in one API call?+
track_shipment endpoint resolves one tracking number per request. To track multiple shipments you need to make one call per tracking number. You can fork this API on Parse and revise it to accept a list of tracking numbers and fan out requests if you need batch behavior.