The UPS Track Alert API provides best in-class package tracking visibility with near real time event updates for an improved customer experience and stream line logistic management.
Updates are pushed to the user as soon as available with no constant polling required, thereby improving operational efficiency. For more information on the UPS Track Alert API, please visit the Product Info page.
Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.
- Enhanced Customer Experience: Near real-time tracking information increases transparency, leading to higher customer satisfaction and trust.
- Operational Efficiency: Eliminates the necessity for continuous polling, thus saving resources and improving system responsiveness.
- Data-Driven Decision Making: Access to near real-time data can help businesses optimize their supply chain and make informed logistics decisions.
- Optimizing Cash Flow Through Near Real-Time Delivery Tracking: Improve cash flow by knowing that deliveries occurred in near real time.
- Mitigating Fraud and Theft through Near Real-Time Package Status Monitoring: Reduce fraud and theft by knowing any time something happens to your packages.
How does it work once I am setup as a user?
You submit up to 100 UPS tracking numbers to the API at a time, using OAUTH in a JSON format. Your submission needs to include the URL where Track Alert will send a message with any events that occur to your tracking number for the next 14 days. This saves you the effort of polling UPS to determine what is the current status of your package.
**What type of packages does Track Alert support?
Track Alert supports UPS packages that have a 1Z tracking number, as well as Roadie packages (1R tracking numbers).
How do I check if a subscription to a tracking number was successful?
Once tracking number(s) is submitted to Track Alert, you will receive a response confirming successful and unsuccessful tracking numbers.
I stopped receiving event messages after 2 weeks and my package hasn’t been delivered. Why?
Each tracking number subscription is valid for 14 days. If the package has not been delivered within 14 days, you must resubscribe to the tracking number to continue receiving updates/events.
How do I get events that occurred prior to subscription?
Track Alert does not retain any history. You should use the UPS Track API to receive history about your package.
How many tracking numbers can a subscriber subscribe to in one request?
You can subscribe to up to 100 tracking numbers in each submission to the API. A reply message will be sent via the API with details showing successful and unsuccessful tracking numbers.
What types of event data does Track Alert provide?
In addition to the expected local dates and times when the event occurred (including GMT date and time), you will receive details about the event that include status-type, status-code, status-description and status-description code. Status types are: M and MV = manifest information, X = exception information (something out of the normal happened to your package, but it may still be delivered on time), I = in-progress (on the way or moving normally through the UPS network), U = update (there is an update to your package, normally the scheduled delivery has been updated, but it may still be delivered on time) D = delivery information (loaded on delivery vehicle, out for delivery, delivered) Status codes are a 2-character code that provide details about the event. There is a list of these codes and their translations elsewhere on this portal. Status descriptions are a very brief (a few words) describing the status code. Status-description code is a overly simplified description of the event. This description is intended for those who do not understand transportation.
What does the message look like?
This is what a message looks like for an event that is sent to your URL. Not every field will have a value for every message. We have converted the JSON format message to text format for clarity.
Those fields are: tracking number scheduled delivery date (this field maybe updated, example '20240905') actual delivery date (this field is blank until the delivery event occurs) actual delivery time (this field is blank until the delivery event occurs) activity location city activity location state/province activity location postal code (this field is blank until the delivery event occurs) activity location country activity status type activity status code activity status description activity status description code local activity date local activity time GMT activity date GMT activity time delivery start time (example '150000') delivery end time (example '170000') delivery time description (example 'estimated delivery window' or 'end of day') delivery photo (this field is only available for enhanced users)Can I test this process?
Yes, there are two test tracking numbers that you can submit, and resubmit that will send several events spaced 1 second apart. Those two test tracking numbers are 1ZCIETST0111111114 and 1ZCIETST0422222228. Please ensure to use UPS Production CIE(https://wwwcie.ups.com/api/track/{version}). You can submit these tracking numbers as often as you like. (no stress testing please.)
When the UPS system is unable to respond to a request, be it from a malformed request, an illegal or invalid value, or other issues, the API generates an error response.
Successful responses may or may not include warnings.
- Without warnings - Indicates the request has been processed as anticipated.
- With warnings - Indicates the request has been processed with potentially unanticipated results. The warning contains information in the response that should be passed to the end user.
The severity of an error may be transient or hard.
- Transient error - Indicates an error that is temporary in nature. Such errors may be caused by response timeouts due to high server loads or scheduled maintenance in progress. The request may be issued successfully at a later time.
- Hard error - Indicates the request has a problem that the system is not able to resolve. These errors are critical and prevent requests from processing.
The following error codes can apply to all APIs.
Code | HTTP Code | Severity | Description |
---|---|---|---|
UJ0001 | 401 | Hard | Invalid token or token is not present |
405 | 405 | Hard | Method Not Allowed. |
10004 | 500 | Transient | Something went wrong while processing your request, please try again later |
10007 | 400 | Hard | Requested Content Type is not supported |
250002 | 401 | Hard | Invalid authentication information. |
251004 | 401 | Hard | Bearer Token expired (oauth) |
VSS000 | 400 | Hard | Invalid request and The Subscription request has been rejected. |
VSS002 | 400 | Hard | Missing transId |
VSS003 | 400 | Hard | Please enter a valid Transaction ID, The Subscription request has been rejected. |
VSS004 | 400 | Hard | Missing transactionSrc |
VSS006 | 400 | Hard | Please enter a valid Transaction SRC, The Subscription request has been rejected. |
VSS100 | 500 | Transient | We're sorry, the system is temporarily unavailable. Please try again later. |
VSS110 | 400 | Hard | Subscription request is empty or not present. The Subscription request has been rejected. |
VSS200 | 400 | Hard | Tracking Number List is required. The Subscription request has been rejected. |
VSS210 | 400 | Hard | The Subscription request should have at least one valid tracking number. The Subscription request has been rejected. |
VSS215 | 400 | Hard | The tracking number that was submitted is not a valid CIE tracking number and has been rejected. |
VSS220 | 400 | Hard | You have submitted over 100 tracking numbers which is not allowed. The entire submission of tracking numbers has been rejected. Please resubmit your request again using groups of no more than 100 tracking numbers. |
VSS300 | 400 | Hard | Locale is required. The Subscription request has been rejected. |
VSS310 | 400 | Hard | Please enter a valid locale. The Subscription request has been rejected |
VSS400 | 400 | Hard | Please enter a valid country code. The Subscription request has been rejected. |
VSS500 | 400 | Hard | Destination is required. The Subscription request has been rejected |
VSS600 | 400 | Hard | URL is empty or not present. The Subscription request has been rejected. |
VSS610 | 400 | Hard | URL is too long. The Subscription request has been rejected. |
VSS700 | 400 | Hard | Credential is empty or not present. The Subscription request has been rejected. |
VSS800 | 400 | Hard | CredentialType is empty or not present. The Subscription request has been rejected. |
VSS930 | 400 | Hard | Type is missing or invalid, The Subscription request has been rejected. |
API to create subscriptions by tracking numbers.
This endpoint takes a list of tracking numbers and creates a subscription for each. Clients must provide the tracking numbers in the correct format.
Upon success it should return:
- List of valid tracking number for which subscription created.
- List of invalid tracking number for which subscription not created.
header Parameters
Request Body schema: application/json
Successful operation
Invalid Request
Unauthorized
Blocked Merchant
URL does not exist or resource not found.
Method Not Allowed
Rate Limit Exceeded
Internal Server Error
- Payload
- curl
- Node.js
- JavaScript
- PHP
- Python
- C#
- Java
{- "locale": "en_US",
- "countryCode": "US",
- "trackingNumberList": [
- "1ZCIETST0111111114",
- "1ZCIETST0422222228"
], - "destination": {
- "credentialType": "Bearer",
- "credential": "string"
}
}
- 200
- 400
- 401
- 403
- 404
- 405
- 429
- 500
Example response that contains valid tracking number for which subscription created and invalid tracking numbers.
{- "validTrackingNumbers": [
- "1Z12345678912345560"
], - "invalidTrackingNumbers": [
- "1Z1234567$8"
]
}
Tracking EventWebhook
This HTTPS POST request will send information about a new tracking event in the system. Please ensure the webhook URL provided in the subscription request is ready to receive this POST request. Note that not every field will have a value in each message. The webhook event dispatched by our API requires an acknowledgement within milliseconds to ensure optimal performance and reliability. Please ensure your endpoint is capable of handling and responding to events in this time frame.
header Parameters
Request Body schema: application/json
trackingNumber required | string^1Z[0-9A-Z]{16}$ The package's tracking number. | ||||||||||||||||||||
localActivityDate | string = 8 characters ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])... The localized date of the activity. Format: YYYYMMDD | ||||||||||||||||||||
localActivityTime | string = 6 characters ^([01]?\d|2[0-3])([0-5]?\d){2}$ The localized time of the activity. Format: HHMMSS (24 hr) | ||||||||||||||||||||
object (ActivityLocation) The container which has the current package activity location. | |||||||||||||||||||||
| |||||||||||||||||||||
required | object (ActivityStatus) The container which has the current package activity status. | ||||||||||||||||||||
| |||||||||||||||||||||
scheduledDeliveryDate | string = 8 characters ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])... Original scheduled delivery date of the package. Format: YYYYMMDD | ||||||||||||||||||||
actualDeliveryDate | string = 8 characters ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])... Actual delivery date of the package. Format: YYYYMMDD (This field is blank until the delivery event occurs) | ||||||||||||||||||||
actualDeliveryTime | string = 6 characters ^([01]?\d|2[0-3])([0-5]?\d){2}$ Actual delivery time of the package. Format: HHMMSS (24 hr) (This field is blank until the delivery event occurs) | ||||||||||||||||||||
gmtActivityDate | string = 8 characters ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])... The GMT date of the activity. Format: YYYYMMDD | ||||||||||||||||||||
gmtActivityTime | string = 6 characters ^([01]?\d|2[0-3])([0-5]?\d){2}$ The GMT time of the activity. Format: HHMMSS (24 hr) | ||||||||||||||||||||
gmtOffset | string = 6 characters ^[+-]([01]\d|2[0-3])\.[0-5]\d$ A field that shows how local time was calculated. In the format (-/+)HH.MM (24 hr) | ||||||||||||||||||||
deliveryStartTime | string = 6 characters ^([01]?\d|2[0-3])([0-5]?\d){2}$ The start time of a delivery. Format: HHMMSS (24 hr). | ||||||||||||||||||||
deliveryEndTime | string = 6 characters ^([01]?\d|2[0-3])([0-5]?\d){2}$ The end time of a window or the committed time or the delivered time. Format: HHMMSS (24 hr) | ||||||||||||||||||||
deliveryTimeDescription | string The date of this delivery detail. |
Return a 200 status to indicate that the data was received successfully
- Payload
{- "activityLocation": {
- "city": "",
- "country": "US",
- "postalCode": "",
- "stateProvince": ""
}, - "activityStatus": {
- "code": "MP",
- "description": "Shipment Ready for UPS",
- "descriptionCode": "003",
- "type": "M"
}, - "actualDeliveryDate": "",
- "actualDeliveryTime": "",
- "deliveryEndTime": "",
- "deliveryPhoto": "",
- "deliveryStartTime": "",
- "deliveryTimeDescription": "",
- "gmtActivityDate": "20240422",
- "gmtActivityTime": "041230",
- "localActivityDate": "20240422",
- "localActivityTime": "091230",
- "scheduledDeliveryDate": "",
- "trackingNumber": " 1ZABCXYZ0112346789"
}