API Reference | ReDoc

UPS Track Alert

Product Info

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.

Run In Postman Open in GitHub

Business Values

  • 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.

Reference

FAQs

  • 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.)

Overview

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.

  1. Without warnings - Indicates the request has been processed as anticipated.
  2. 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.

  1. 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.
  2. 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.

Error Codes

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.
SecurityOAuth2
Request
path Parameters
version
required
string
Default: "v1"

version

Value: "v1"
header Parameters
transId
required
string

An identifier unique to the request.

transactionSrc
required
string

Identifies the client/source application that is calling.

Request Body schema: application/json
locale
required
string^[a-z]{2}_[A-Z]{2}$

Locale setting is composed of language code and country code, separated by an underscore. Currently only english US(en_US) is accepted.

countryCode
string

Represents the country code. This field is reserved for future use.

trackingNumberList
required
Array of strings <= 100 items

Represents list of tracking numbers in request.

required
object (Destination)

The destination container related to the clients endpoint API. To which messages would be sent on an event on the package.

url
required
string <url>

It is an HTTPS-based callback end point that is exposed by the client to receive event notification. This endpoint must be operational around the clock to ensure no event notifications are missed. If this endpoint is not continuously available, incoming events will be lost.

credentialType
required
string

It is an open-entry field that indicates type of credentials supported by the client.

credential
required
string

It is an opaque string meant for client authentication. If for any reason this credential changes then any event notification will fail until a new subscription is made.

Responses
200

Successful operation

400

Invalid Request

401

Unauthorized

403

Blocked Merchant

404

URL does not exist or resource not found.

405

Method Not Allowed

429

Rate Limit Exceeded

500

Internal Server Error

post/track/{version}/subscription/standard/package
Request samples
application/json
{
  • "locale": "en_US",
  • "countryCode": "US",
  • "trackingNumberList": [
    ],
  • "destination": {}
}
Response samples
application/json

Example response that contains valid tracking number for which subscription created and invalid tracking numbers.

{
  • "validTrackingNumbers": [
    ],
  • "invalidTrackingNumbers": [
    ]
}

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.

Request
header Parameters
credential
required
string

It is an opaque string meant for client authentication. Shared in Subscription request.

User-Agent
required
string

Represents Track Alert application with value 'UPSPubSubTrackingService'.

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.

city
string

The physical address city.

stateProvince
string = 2 characters ^[A-Z]{2}$

The physical address state or province.

postalCode
string [ 5 .. 9 ] characters ^\d{5}(?:[-\s]\d{4})?$

The physical address postal code (This field is blank until the delivery event occurs).

country
string = 2 characters ^[A-Z]{2}

The physical address country.

required
object (ActivityStatus)

The container which has the current package activity status.

type
string

The current activity status type.

Code Type
D Delivery
I On the Way
M Manifest
MV Manifest Void
U Updated Delivery Date or Time
X Package Exception
code
string

The current activity status code. See the 'Status Codes' document for more details.

description
string

The current activity status description.

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.

Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "activityLocation": {
    },
  • "activityStatus": {
    },
  • "actualDeliveryDate": "",
  • "actualDeliveryTime": "",
  • "deliveryEndTime": "",
  • "deliveryPhoto": "",
  • "deliveryStartTime": "",
  • "deliveryTimeDescription": "",
  • "gmtActivityDate": "20240422",
  • "gmtActivityTime": "041230",
  • "localActivityDate": "20240422",
  • "localActivityTime": "091230",
  • "scheduledDeliveryDate": "",
  • "trackingNumber": " 1ZABCXYZ0112346789"
}