UPS
App · 20 actions
Track shipments, quote rates, validate addresses, manage labels and shipments, and schedule or cancel pickups.
Actions
| Action | What it does |
|---|---|
| Cancel delivery intercept | Cancel a previously applied intercept on the package. |
| Cancel pickup | Cancel a booked UPS on-demand pickup by its pickup request number, and get confirmation it was cancelled. |
| Create pickup | Book a UPS pickup at an address, with the date, time window, packages and weight, and get its pickup request number. |
| Create shipment | Create a UPS shipment and get its tracking number, charges and shipping label. |
| Find locations | Find UPS drop-off points, stores and Access Points near an address, filtered by services offered, with each one's address, distance and opening hours. |
| Find pickup service centers | Find UPS service centers near an address, with each one's address, phone number, location code and drop-off and pickup hours. |
| Get delivery intercept charges | Find what it would cost to redirect, reschedule or return a package, by its tracking number and the kind of change. |
| Get delivery intercept eligibility | Check whether a package can still be redirected, held or returned to sender, by its tracking number. |
| Get pickup countries | List the states or provinces of a country or territory that UPS pickups can be booked in. |
| Get pickup rates | Find what a UPS on-demand pickup would cost for an address, date and time window, before booking it. |
| Get pickup status | Check the status of an account's pending pickups: received, dispatched, completed, incomplete, an updated arrival time, or cancelled. |
| Get shipping rates | Compare prices for a shipment across UPS services, given the addresses, packages and weights. |
| Get transit times | Find how many days each UPS service takes between two places for a ship date, with the expected delivery date for each. |
| Recover label | Get the shipping or return label for a shipment again by its tracking number or reference, as an image or a link. |
| Request return to sender | Return a package to the original shipper prior to delivery. |
| Track by reference number | Find and track shipments by a reference number you put on them, such as an order or invoice number, optionally narrowed by pickup dates, destination or shipper number. |
| Track each package in shipment | Get the tracking status of every package in a multi-package shipment from one tracking number, a page at a time. |
| Track package | Get a package's tracking history by its tracking number: its status, each scan with time and place, and the delivery date. |
| Validate address | Check a US or Puerto Rico street address against the US Postal Service's database and get it corrected or suggestions back. |
| Void shipment | Cancel a shipment that hasn't been picked up yet, by its shipment ID or a package's tracking number. |
Cancel delivery intercept
Cancel a previously applied intercept on the package.
Inputs
- Tracking number
tracking_numbertextRequired - The number being tracked. Each method defines if required.
- Loc
loctext - The locale of the client application to ensure that translations on the response are in the proper language.
- Request type
request_typetext - Returned value.
- Requester contact info name
requester_contact_info_nametextRequired - Contact Name
- Requester contact info telephone
requester_contact_info_telephonetextRequired - Contact phone number
- Requester contact info phone ext
requester_contact_info_phone_exttext - Contact phone extension
- Requester contact info email address
requester_contact_info_email_addresstext - Contact email address
- Requester contact info alt telephone
requester_contact_info_alt_telephonetext - Alternate Contact phone number
- Requester contact info alt phone ext
requester_contact_info_alt_phone_exttext - Alternate Contact phone extension
- Requester contact info display phone number
requester_contact_info_display_phone_numbertrue/false - Indicates if the phone number of a UAP can be displayed to external clients.
- Reason for return
reason_for_returntext - Returned value.
- Delivery date
delivery_datetext - Original scheduled date of delivery. Required olny for FD intercept type.
- Special instructions
special_instructionstextRequired - Special Instructions sent to the driver. Available only to AA intercept type
- New delivery address
new_delivery_addressobject - New delivery address. Required olny for AA intercept type.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"errors": [],
"statusCode": "example",
"statusMsg": "example",
"subStatusCode": "example",
"success": false,
"transactionId": "example",
"warnings": {}
}
}Cancel pickup
Cancel a booked UPS on-demand pickup by its pickup request number, and get confirmation it was cancelled.
Inputs
- Pickup request number
prntextRequired - The PRN returned when the pickup was scheduled. Only this pickup is cancelled.
Outputs
dataobject- N/A
Example output
{
"data": {
"PickupCancelResponse": {
"GWNStatus": {
"Code": "example",
"Description": "example"
},
"PickupType": "example",
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
}
}
}
}Create pickup
Book a UPS pickup at an address, with the date, time window, packages and weight, and get its pickup request number. This may incur carrier charges; use Sandbox when testing.
Inputs
- Request
pickup_creation_request_requestobjectRequired - Common element for all services
- Rate pickup indicator
pickup_creation_request_rate_pickup_indicatortextRequired - Indicates whether to rate the on-callpickup or not. Valid values: Y = Rate this pickup N = Do not rate this pickup (default)
- Rate chart type
pickup_creation_request_rate_chart_typetext - Rate Type with which pickup is rated. Possible RateChart values for different regions will be: US 48 origin: - 1 - Daily Rates - 3 - Standard List Rates - 4 - Retail Rates. Alaska/Hawaii origin: - 1 - Daily Rates - 3 - Standard List Rates - 4 - Retail Rates. All Other origins: - 1 - Rates - 5 - Regional Rates - 6 - General List Rates. 3 and 4 do not apply
- Tax information indicator
pickup_creation_request_tax_information_indicatortext - Indicates whether to return detailed taxes for the on-callpickups. Valid values: Y = Rate this pickup with taxes N = Do not rate this pickup with taxes (default)
- User level discount indicator
pickup_creation_request_user_level_discount_indicatortext - Indicates whether to return user level promo discount for the on-callpickups. Valid values: Y = Rate this pickup with user level promo discount N = Do not rate this pickup with user level promo discount(default)
- Shipper
pickup_creation_request_shipperobject - On-call pickup shipper or requestor information. Must provide when choose to pay the pickup by shipper account number, BillThirdParty account number, or BillReceiver account number. It is optional if the shipper chooses any other payment method. However, it is highly recommended to provide if available.
- Pickup address
pickup_creation_request_pickup_addressobjectRequired - The container of pickup address.
- Alternate address indicator
pickup_creation_request_alternate_address_indicatortextRequired - Indicates if pickup address is a different address than that specified in a customer's profile. Valid values: Y = Alternate address N = Original pickup address (default)
- Pickup piece
pickup_creation_request_pickup_piecelistRequired - Returned value.
- Total weight
pickup_creation_request_total_weightobject - Container for the total weight of all the items.
- Overweight indicator
pickup_creation_request_overweight_indicatortext - Indicates if at least any package is over 70 lbs or 32 kgs. Valid values: Y = Over weight N = Not over weight (default) Not required for WWEF service.
- Tracking data
pickup_creation_request_tracking_datalist - Returned value.
- Tracking data with reference number
pickup_creation_request_tracking_data_with_reference_numberobject - Container for Tracking Number with its associated reference numbers. This container should be populated to provide visibility into shipment tied to pickup being scheduled. TrackingDataWithReferenceNumber and TrackingData container cannot be present at the same time.
- Payment method
pickup_creation_request_payment_methodtextRequired - The payment method to pay for this on call pickup. 00 = No payment needed 01 = Pay by shipper account 03 = Pay by charge card 04 = Pay by 1Z tracking number 05 = Pay by check or money order 06 = Cash(applicable only for these countries - BE,FR,DE,IT,MX,NL,PL,ES,GB,CZ,HU,FI,NO) 07=Pay by PayPal Refer to Appendix # for valid payment methods for CZ, HU, FI and NO For countries and (or) zip codes where pickup is free of charge, please submit 00, means no payment needed as payment method. - If 01 is the payment method, then ShipperAccountNumber and ShipperAccount CountryCode must be provided. - If 03 is selected, then CreditCard information should be provided. - If 04 is selected, then the shipper agreed to pay for the pickup packages. - If 05 is selected, then the shipper will pay for the pickup packages with a check or money order.
- Special instruction
pickup_creation_request_special_instructiontext - Special handling instruction from the customer
- Reference number
pickup_creation_request_reference_numbertext - Information entered by a customer for Privileged reference
- Freight options
pickup_creation_request_freight_optionsobject - Container will be used to indicate Service options, add optional Original service center, destination address and shipment details related to the UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday.
- Service category
pickup_creation_request_service_categorytext - Service Category. Applicable to the following countries: BE, FR, DE, IT, MX, NL, PL, ES, GB Valid values: 01 - domestic (default) 02 - international 03 - transborder
- Cash type
pickup_creation_request_cash_typetext - Describes the type of cash funds that the driver will collect. Applicable to the following countries: BE,FR,DE,IT,MX,NL,PL,ES,GB Valid values: 01 - Pickup only (default) 02 - Transportation only 03 - Pickup and Transportation
- Shipping labels available
pickup_creation_request_shipping_labels_availabletext - This element should be set to "Y" in the request to indicate that user has pre-printed shipping labels for all the packages, otherwise this will be treated as false.
- Premier indicator
pickup_creation_request_premier_indicatortext - Indicates that the pickup includes one or more Premier service package. Accepted values: - Y = Includes Premier-eligible packages - N = Does not include Premier-eligible packages (default)
- Notification
pickup_creation_request_notificationobject - Container for pickup notification
- Pickup date
pickup_datedateRequired - The pickup date at the pickup location.
- Ready time
ready_timetimeRequired - The earliest pickup time at the pickup location.
- Close time
close_timetimeRequired - The latest pickup time at the pickup location.
Outputs
dataobject- See the documented object structure in the API reference.
Example output
{
"data": {}
}Create shipment
Create a UPS shipment and get its tracking number, charges and shipping label. This may incur carrier charges; use Sandbox when testing.
Inputs
- Additionaladdressvalidation
additionaladdressvalidationtext - Valid Values: city = validation will include city.Length 15
- Shipment request request
shipment_request_requestobjectRequired - Request Container
- Shipment request shipment
shipment_request_shipmentobjectRequired - Shipment Container
- Shipment request label specification
shipment_request_label_specificationobject - Container used to define the properties required by the user to print and/or display the UPS shipping label. Required for shipment without return service or shipments with PRL return service. Required for Electronic Return Label or Electronic Import Control Label shipments with SubVersion greater than or equal to 1707.
- Shipment request receipt specification
shipment_request_receipt_specificationobject - Container used to allow the user to choose to print a thermal receipt.
Outputs
dataobject- N/A
Example output
{
"data": {
"ShipmentResponse": {
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"ShipmentResults": {
"BarCodeImage": "example",
"BillOfLading": "example",
"BillableWeightCalculationMethod": "example",
"BillingWeight": {
"UnitOfMeasurement": {
"Code": "example",
"Description": "example"
},
"Weight": "example"
},
"CODTurnInPage": {
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"ControlLogReceipt": [],
"DGPaperImage": [],
"Disclaimer": [],
"FRSShipmentData": {
"FreightDensityRate": {
"Density": "example",
"TotalCubicFeet": "example"
},
"HandlingUnits": [],
"TransportationCharges": {
"DiscountAmount": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"DiscountPercentage": "example",
"GrossCharge": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"NetCharge": {
"CurrencyCode": "example",
"MonetaryValue": "example"
}
}
},
"Form": {
"Code": "example",
"Description": "example",
"FormGroupId": "example",
"FormGroupIdName": "example",
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"GCCN": "example",
"HighValueReport": {
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"LabelURL": "example",
"LocalLanguageLabelURL": "example",
"LocalLanguageReceiptURL": "example",
"MIDualReturnShipmentKey": "example",
"MasterCartonID": "example",
"Message": "example",
"NegotiatedRateCharges": {
"ItemizedCharges": [],
"RateModifier": [],
"TaxCharges": [],
"TotalCharge": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"TotalChargesWithTaxes": {
"CurrencyCode": "example",
"MonetaryValue": "example"
}
},
"PackageResults": [],
"PalletLabel": {
"PalletLabel": "example"
},
"RatingMethod": "example",
"ReceiptURL": "example",
"RoarRatedIndicator": "example",
"ShipmentCharges": {
"BaseServiceCharge": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"ItemizedCharges": [],
"RateChart": "example",
"ServiceOptionsCharges": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"TaxCharges": [],
"TotalCharges": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"TotalChargesWithTaxes": {
"CurrencyCode": "example",
"MonetaryValue": "example"
},
"TransportationCharges": {
"CurrencyCode": "example",
"MonetaryValue": "example"
}
},
"ShipmentIdentificationNumber": "example",
"SubProNumber": "example",
"USI": "example"
}
}
}
}Find locations
Find UPS drop-off points, stores and Access Points near an address, filtered by services offered, with each one's address, distance and opening hours.
Inputs
- Locale
localetext - Locale of request
- Locator request request
locator_request_requestobjectRequired - N/A
- Locator request origin address
locator_request_origin_addressobjectRequired - Container for origin address information.
- Locator request translate
locator_request_translateobjectRequired - Contains the locale information for the request.
- Locator request unit of measurement
locator_request_unit_of_measurementobject - Distance unit of measurement. This is required for location requests (request option 1).
- Locator request location ID
locator_request_location_idlist - Location ID is the identification number of the UPS affiliated location.
- Locator request location search criteria
locator_request_location_search_criteriaobject - The Location search criteria container allows the user to further define the basis to which they wish to receive the UPS locations. Only relevant when the user requests a Location search (request option 1).
- Locator request sort criteria
locator_request_sort_criteriaobject - Container for Sort Criteria
- Locator request allow all confidence levels
locator_request_allow_all_confidence_levelstext - Indicator to allow confidence level in search.
- Locator request search option code
locator_request_search_option_codetext - Valid values: 01-Proximity Search Details 02-Address Search Details 03-Proximity Search Summary 04-Address Search Summary 05-Freight Will Call Search. Either OptionType 03 or 04 is required.
- Locator request service geo unit
locator_request_service_geo_unitobject - ServiceGeoUnit Container. Required to search for the freight facility information
- Locator request freight indicator
locator_request_freight_indicatortext - FreightIndicator. Required for Freight Location Search.
Outputs
dataobject- N/A
Example output
{
"data": {
"LocatorResponse": {
"AllowAllConfidenceLevels": "example",
"Geocode": {
"Latitude": "example",
"Longitude": "example"
},
"Response": {
"Error": {
"ErrorCode": "example",
"ErrorDescription": "example",
"ErrorDigest": [],
"ErrorLocation": [],
"ErrorSeverity": "example",
"MinimumRetrySeconds": "example"
},
"ResponseStatusCode": "example",
"ResponseStatusDescription": "example",
"TransactionReference": {
"CustomerContext": "example",
"XpciVersion": "example"
}
},
"SearchResults": {
"ActiveAvailableAccessPointIndicator": "example",
"AvailableLocationAttributes": [],
"Disclaimer": "example",
"DropLocation": [],
"GeocodeCandidate": []
}
}
}
}Find pickup service centers
Find UPS service centers near an address, with each one's address, phone number, location code and drop-off and pickup hours.
Inputs
- Pickup get service center facilities request request
pickup_get_service_center_facilities_request_requestobjectRequired - Container for the Request.
- Pickup get service center facilities request pickup piece
pickup_get_service_center_facilities_request_pickup_piecetextRequired - Returned value.
- Pickup get service center facilities request origin address
pickup_get_service_center_facilities_request_origin_addressobject - Indicates the address of the shipper to allow for the nearest Drop off facility Search. Conditionally required for drop off location search.
- Pickup get service center facilities request destination address
pickup_get_service_center_facilities_request_destination_addressobject - DestinationAddress container. Conditionally required for pickup location search.
- Pickup get service center facilities request locale
pickup_get_service_center_facilities_request_localetextRequired - Origin Country or Territory Locale. Locale should be Origin Country. Example: en_US. The Last 50 instruction will be send based on this locale. Locale is required if PoximityIndicator is present for Drop Off facilities.
- Pickup get service center facilities request proximity search indicator
pickup_get_service_center_facilities_request_proximity_search_indicatortext - Proximity Indicator. Indicates the user requested the proximity search for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday locations for the origin address and/or the airport code, and the sort code for destination address.
Outputs
dataobject- N/A
Example output
{
"data": {
"PickupGetServiceCenterFacilitiesResponse": {
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"ServiceCenterLocation": {
"DropOffFacilities": [],
"PickupFacilities": {
"Address": {
"AddressLine": "example",
"City": "example",
"CountryCode": "example",
"PostalCode": "example",
"ResidentialIndicator": "example",
"StateProvince": "example"
},
"AirportCode": "example",
"FacilityTime": {
"DayOfWeek": []
},
"Fax": "example",
"Name": "example",
"Phone": "example",
"SLIC": "example",
"SortCode": "example",
"Timezone": "example",
"Type": "example"
}
}
}
}
}Get delivery intercept charges
Find what it would cost to redirect, reschedule or return a package, by its tracking number and the kind of change.
Inputs
- Tracking number
tracking_numbertextRequired - The number being tracked. Each method defines if required.
- Loc
loctext - The locale of the client application to ensure that translations on the response are in the proper language.
- Client ip
client_iptext - IP address of the requesting device
- Rating request
rating_requestlistRequired - List of rating request data. If you want to find out the accessory and transportation charges of a "redirect" request for a specified Tracking number then this array list must contain one rating request. This array is unbounded.
Outputs
dataobject- Response schema for Delivery Change Charge request
Example output
{
"data": {
"response": {
"chargeInfo": [],
"errors": [],
"statusCode": "example",
"statusMsg": "example",
"subStatusCode": "example",
"success": false,
"transactionId": "example",
"warnings": {}
}
}
}Get delivery intercept eligibility
Check whether a package can still be redirected, held or returned to sender, by its tracking number.
Inputs
- Tracking number
tracking_numbertextRequired - The number being tracked. Each method defines if required.
- Loc
loctext - The locale of the client application to ensure that translations on the response are in the proper language.
Outputs
dataobject- Response schema for Delivery Change Eligibility request
Example output
{
"data": {
"response": {
"commonEligibilityMap": {
"eligibilityValue": {
"cancelEligibility": "ELIGIBLE",
"createEligibility": "ELIGIBLE",
"dateOptionsforFutureDelivery": [],
"modifyEligibility": "ELIGIBLE",
"reasonOptionsForRTS": []
},
"interceptFeature": "example"
},
"errors": [],
"statusCode": "example",
"statusMsg": "example",
"subStatusCode": "example",
"success": false,
"transactionId": "example",
"warnings": {}
}
}
}Get pickup countries
List the states or provinces of a country or territory that UPS pickups can be booked in.
Inputs
- Countrycode
countrycodetextRequired - Country or terrirtory for which the list will represent.Length 2
Outputs
dataobject- N/A
Example output
{
"data": {
"PickupGetPoliticalDivision1ListResponse": {
"PoliticalDivision1": [],
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
}
}
}
}Get pickup rates
Find what a UPS on-demand pickup would cost for an address, date and time window, before booking it.
Inputs
- Pickup type
pickuptypetextRequired - Type of pickup. Valid values: oncall smart both. Length 6One of:
oncall,smart,both. - Request
pickup_rate_request_requestobjectRequired - Common element for all services
- Shipper account
pickup_rate_request_shipper_accountobject - Shipper account information.
- Pickup address
pickup_rate_request_pickup_addressobjectRequired - The address to pickup the packages
- Alternate address indicator
pickup_rate_request_alternate_address_indicatortextRequired - Indicates if the pickup address is different than the address specified in the customer's profile. Valid values: Y = Alternate address N = Original pickup address (default)
- Service date option
pickup_rate_request_service_date_optiontextRequired - Indicates the pickup timeframe. - 01 = Same-Day Pickup - 02 = Future-Day Pickup - 03 = A Specific-Day Pickup If 03 is selected, then PickupDate, EarliestReadyTime, and LatestClosetime must be specified.One of:
01(Same-day pickup),02(Future-day pickup),03(Choose a pickup date). - Rate chart type
pickup_rate_request_rate_chart_typetext - Rate Type with which pickup is rated. Possible RateChart values for different regions will be: US 48 origin: 1 - Daily Rates 3 - Standard List Rates 4 - Retail Rates. Alaska/Hawaii origin: 1 - Daily Rates 3 - Standard List Rates 4 - Retail Rates. All Other origins: 1 - Rates 5 - Regional Rates 6 - General List Rates. 3 and 4 do not apply
- Tax information indicator
pickup_rate_request_tax_information_indicatortext - Indicates whether to return detailed taxes for on-callpickups. Valid values: - Y = Rate this pickup with taxes - N = Do not rate this pickup with taxes (default)
- User level discount indicator
pickup_rate_request_user_level_discount_indicatortext - Indicates whether to return user level promo discount for the on-callpickups. Valid values: Y = Rate this pickup with user level promo discount N = Do not rate this pickup with user level promo discount(default)
- Pickup date
pickup_datedate - The pickup date at the pickup location.
- Ready time
ready_timetime - The earliest pickup time at the pickup location.
- Close time
close_timetime - The latest pickup time at the pickup location.
Outputs
dataobject- N/A
Example output
{
"data": {
"PickupRateResponse": {
"RateResult": {
"ChargeDetail": [],
"CurrencyCode": "example",
"Disclaimer": {
"Code": "example",
"Description": "example"
},
"GrandTotalOfAllCharge": "example",
"GrandTotalOfAllIncentedCharge": "example",
"PreTaxTotalCharge": "example",
"PreTaxTotalIncentedCharge": "example",
"RateType": "example",
"TaxCharges": [],
"TotalTax": "example"
},
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"WeekendServiceTerritory": {
"SatWST": "example",
"SunWST": "example"
},
"WeekendServiceTerritoryIndicator": "example"
}
}
}Get pickup status
Check the status of an account's pending pickups: received, dispatched, completed, incomplete, an updated arrival time, or cancelled.
Inputs
- Pickup type
pickuptypetextRequired - Type of pickup. Valid values: oncall smart both. Length 6One of:
oncall,smart,both. - Account number
account_numbertextRequired - The specific account number that belongs to the shipper.Length 6 or 10
Outputs
dataobject- N/A
Example output
{
"data": {
"PickupPendingStatusResponse": {
"PendingStatus": [],
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
}
}
}
}Get shipping rates
Compare prices for a shipment across UPS services, given the addresses, packages and weights. Returns each service's charges and delivery estimate.
Inputs
- Additionalinfo
additionalinfotext - Valid Values: timeintransit = The server rates with transit time information combined with requestoption in URL.Rate is the only valid request option for Ground Freight Pricing requests. Length 15
- Rate request request
rate_request_requestobjectRequired - Request container. N/A
- Rate request pickup type
rate_request_pickup_typeobject - Pickup Type container tag.
- Rate request customer classification
rate_request_customer_classificationobject - Customer classification container. Valid if ShipFrom country or territory is "US"
- Rate request shipment
rate_request_shipmentobjectRequired - Container for Shipment Information.
Outputs
dataobject- N/A
Example output
{
"data": {
"RateResponse": {
"RatedShipment": [],
"Response": {
"Alert": [],
"AlertDetail": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
}
}
}
}Get transit times
Find how many days each UPS service takes between two places for a ship date, with the expected delivery date for each.
Inputs
- Origin country code
origin_country_codetextRequired - The country code of the origin shipment. Valid Values: Must conform to the ISO-defined, two-letter country or territory codes. Refer to Country or Territory Codes in the Appendix above for valid values.
- Origin state province
origin_state_provincetext - The shipment origin state or province. For U.S. addresses, the value must be a valid 2-character value (per U.S. Mail standards) For non-U.S. addresses the full State or Province name should be provided.
- Origin city name
origin_city_nametext - The shipment origin city. Required for International requests for those countries that do not utilize postal codes.
- Origin town name
origin_town_nametext - The shipment origin town. Town is a subdivision of city.
- Origin postal code
origin_postal_codetext - Required for Domestic requests. The shipment origin postal code. Either the 5, or 9-digit US zip codes must be used for U.S. addresses. For non-U.S. addresses, this is recommended for all countries that utilize postal codes.
- Destination country code
destination_country_codetext - The country code of the destination. Valid values: Must conform to ISO-defined country codes.
- Destination state province
destination_state_provincetext - The shipment destination state or province. For U.S. addresses, the value must be a valid 2-character value (per U.S. Mail standards). For non-U.S. addresses the full State or Province name should be provided.
- Destination city name
destination_city_nametext - The shipment destination city. Required for International Requests for those countries that do not utilize postal codes.
- Destination town name
destination_town_nametext - The shipment destination town. Town is a subdivision of city.
- Destination postal code
destination_postal_codetext - The shipment destination postal code. Required for Domestic requests. Either 5, or 9-digit U.S. zip codes must be used for U.S. addresses. For non-U.S. addresses, this is recommended for all countries that utilize postal codes.
- Residential indicator
residential_indicatortext - Indicates if address is residential or commercial. Required for Domestic requests. Valid values: "01", "02" 01 = Residential 02 = Commercial Defaults to commercial for International Requests.
- Ship date
ship_datedate - The date the shipment is tendered to UPS for shipping (can be dropped off at UPS or picked up by UPS). Allowed range is up to 60 days in future and 35 days in past. This date may or may not be the UPS business date. Format is YYYY-MM-DD. YYYY = 4 digit year; MM = 2 digit month, valid values 01-12; DD = 2 digit day of month, valid values 01-31 If no value is provided, defaults to current system date.
- Ship time
ship_timetime - The time the shipment is tendered to UPS for shipping (can be dropped off at UPS or picked up by UPS). Format is HH:MM:SS Defaults to current time if not provided.
- Weight
weightnumber - The weight of the shipment. Required for International requests. Note: If decimal values are used, valid values will be rounded to the tenths. Note: Maximum value is 70 kilograms or 150 pounds.At most 1.
- Weight unit of measure
weight_unit_of_measuretext - Required for International requests and when weight value is provided. Valid Values: "LBS", "KGS"
- Shipment contents value
shipment_contents_valuenumber - The monetary value of shipment contents. Required when origin country does not equal destination country and BillType is 03 (non-documented) or 04 (WWEF) Required when origin country does not equal destination country, and destination country = CA, and BillType = 02 (document). Note: If decimal values are used, valid values will be rounded to the tenths.At most 3.
- Shipment contents currency code
shipment_contents_currency_codetext - The unit of currency used for values. Required if ShipmentContentsValue is populated. Valid value: must conform to ISO standards.
- Bill type
bill_typetext - Required for International Requests. Valid values: "02","03","04" 02 - Document 03 - Non Document 04 - WWEF (Pallet)
- Avv flag
avv_flagtrue/false - Used to bypass address validation when the address has already been validated by the calling application. Valid values: true, false Defaults to true Note: not to be exposed to external customers.
- Number of packages
number_of_packagesnumber - Sets the number of packages in shipment. Default value is 1.At most 1.
- Drop off at facility indicator
drop_off_at_facility_indicatornumber - Sets the indicator for an international Freight Pallet shipment that is going to be dropped off by shipper to a UPS facility. The indicator is used when the Bill Type is "04". Valid values: "0", "1". 0 = WWDTProcessIF.PICKUP_BY_UPS 1 = WWDTProcessIf.DROPOFF_BY_SHIPPER The default value is "0"At most 1.
- Hold for pickup indicator
hold_for_pickup_indicatornumber - Sets the indicator for an international Freight Pallet shipment that is going to be pick-up by consignee in a destination facility. The indicator is used when the Bill Type is "04". Valid values: "0", "1". 0 = WWDTProcessIF.DELIVERY_BY_UPS 1 = WWDTProcessIf.PICKUP_BY_CONSIGNEE The default value is "0"At most 1.
- Return unfilterd services
return_unfilterd_servicestrue/false - Used to get back a full list of services - bypassing current WWDT business rules to remove services from the list being returned to clients for US domestic that are slower than UPS Ground. Default value is false.
- Max list
max_listnumber - Sets the limit for the number of candidates returned in candidate list. Default value is 200.At most 1.
- Premier indicator
premier_indicatortext - Sets the indicator for premier time in transit when the shipment contains a premier package. Valid values: “00”, “01”. 00 = Non-premier time in transit. 01 = Premier time in transit. The default value is “00”.
Outputs
dataobject- N/A
Example output
{
"data": {
"destinationPickList": [],
"emsResponse": {
"billType": "example",
"destinationCityName": "example",
"destinationCountryCode": "example",
"destinationCountryName": "example",
"destinationPostalCode": "example",
"destinationPostalCodeHigh": "example",
"destinationPostalCodeLow": "example",
"destinationStateProvince": "example",
"dutyType": "example",
"guaranteeSuspended": false,
"numberOfServices": 1,
"originCityName": "example",
"originCountryCode": "example",
"originCountryName": "example",
"originPostalCode": "example",
"originPostalCodeHigh": "example",
"originPostalCodeLow": "example",
"originStateProvince": "example",
"residentialIndicator": "example",
"serviceLevel": "example",
"services": [],
"shipDate": "example",
"shipTime": "example",
"shipmentContentsCurrencyCode": "example",
"shipmentContentsValue": "example",
"weight": "example",
"weightUnitOfMeasure": "example"
},
"originPickList": [],
"validationList": {
"destinationAmbiguous": false,
"invalidFieldList": [],
"invalidFieldListCodes": [],
"originAmbiguous": false
}
}
}Recover label
Get the shipping or return label for a shipment again by its tracking number or reference, as an image or a link.
Inputs
- Label recovery request request
label_recovery_request_requestobjectRequired - Request Container.
- Label recovery request label specification
label_recovery_request_label_specificationobject - Container that is used to define the properties required by the user to print and/ or display the UPS shipping label. Required for the shipment without return service, or shipment with PRL return service.
- Label recovery request translate
label_recovery_request_translateobject - Translate container allows the user to specify the language he/she would like a specific portion of response to return. The language is specified by the combination of language code and dialect code. Valid combinations are: LanguageCode + DialectCode. Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request. Combinations: eng GB = Queen's English Spa 97 = Castilian Spanish ita 97 = Italian fra 97 = France French fra CA = Canadian French deu 97 = German por 97 = Portugal Portuguese nld 97 = Dutch dan 97 = Danish fin 97 = Finnish swe 97 = Swedish eng CA = Canadian English Eng US = US English Default language is Queen's English If the Ship from country or territory is Canada, the Language defaults to Canadian English. If the ship from country or territory is US, the language defaults to US English. If shipping from some other country or territory, the language defaults to Queens English.
- Label recovery request label delivery
label_recovery_request_label_deliveryobject - Container for the Label Delivery accessorial. One Label Delivery per shipment.
- Label recovery request tracking number
label_recovery_request_tracking_numbertext - Small Package Tracking Number. Required if Mail Innovations Tracking Number or ReferenceNumber/Value and ShipperNumber is not provided. If only TrackingNumber is provided, the request will be treated as Small Package Shipment. Label Recovery will return label for Small Package Tracking Number. If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.
- Label recovery request tracking numbers
label_recovery_request_tracking_numberslistRequired - List of Roadie (1R) tracking numbers associated with the label recovery request. Each tracking number must start with "1R" or "1r" and must be either 16 characters (offline) or 28 characters (online) in length.
- Label recovery request mail innovations tracking number
label_recovery_request_mail_innovations_tracking_numbertext - Mail Innovations Tracking Number. Required if Tracking Number or ReferenceNumber/Value is not populated. If only MailInnovationsTrackingNumber is provided, the request will be treated as Single Mail Innovations Return Shipment. Label Recovery will return label for Mail Innovations Return Tracking Number. If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.
- Label recovery request reference values
label_recovery_request_reference_valuesobjectRequired - Container that holds reference number and shipper number If tracking number is not present use reference Number. This is mandatory for only Roadie shipments.
- Label recovery request locale
label_recovery_request_localetext - Represents 5 character ISO Locale that allows the user to request Reference Number Code on Label, Label instructions, Receipt instructions (if available for given tracking number) and High Value Report (if available for given tracking number) in desired language. Locale is specified by the combination of language code and country or territory code - 2 character language code and 2 character country code seperated by an underscore ('_') character. Example - de_DE. Please refer to Appendix for supported values for Locale. Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request.
- Label recovery request upspremium care form
label_recovery_request_upspremium_care_formobject - UPS Premium Care Form container. Default is PDF when container is not provided. Valid only for Canada to Canada movements. UPS Premium Care Form will be returned in both US English and Canadian French language.
Outputs
dataobject- N/A
Example output
{
"data": {
"LabelRecoveryResponse": {
"CODTurnInPage": {
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"Form": {
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"HighValueReport": {
"Image": {
"GraphicImage": "example",
"ImageFormat": {
"Code": "example",
"Description": "example"
}
}
},
"LabelResults": [],
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"ShipmentIdentificationNumber": "example",
"TrackingCandidate": []
}
}
}Request return to sender
Return a package to the original shipper prior to delivery. This operation may incur carrier charges; use Sandbox when testing.
Inputs
- Tracking number
tracking_numbertextRequired - The number being tracked. Each method defines if required.
- Loc
loctext - The locale of the client application to ensure that translations on the response are in the proper language.
- Request type
request_typetext - Returned value.
- Requester contact info name
requester_contact_info_nametextRequired - Contact Name
- Requester contact info telephone
requester_contact_info_telephonetextRequired - Contact phone number
- Requester contact info phone ext
requester_contact_info_phone_exttext - Contact phone extension
- Requester contact info email address
requester_contact_info_email_addresstext - Contact email address
- Requester contact info alt telephone
requester_contact_info_alt_telephonetext - Alternate Contact phone number
- Requester contact info alt phone ext
requester_contact_info_alt_phone_exttext - Alternate Contact phone extension
- Requester contact info display phone number
requester_contact_info_display_phone_numbertrue/false - Indicates if the phone number of a UAP can be displayed to external clients.
- Reason for return
reason_for_returntext - Returned value.
- Delivery date
delivery_datetext - Original scheduled date of delivery. Required olny for FD intercept type.
- Special instructions
special_instructionstextRequired - Special Instructions sent to the driver. Available only to AA intercept type
- New delivery address
new_delivery_addressobject - New delivery address. Required olny for AA intercept type.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"errors": [],
"statusCode": "example",
"statusMsg": "example",
"subStatusCode": "example",
"success": false,
"transactionId": "example",
"warnings": {}
}
}Track by reference number
Find and track shipments by a reference number you put on them, such as an order or invoice number, optionally narrowed by pickup dates, destination or shipper number.
Inputs
- Reference number
reference_numbertextRequired - The reference number for which tracking information is requested.
- Locale
localetext - Language and country code of the user, separated by an underscore. Default value is 'en_US'
- From pick up date
from_pick_up_datedate - The tracking information for the above reference number will be searched from this date
- To pick up date
to_pick_up_datedate - The tracking information for the above reference number will be searched till this date
- Dest country
dest_countrytext - The Destination Country associated with above reference number
- Dest zip
dest_ziptext - The Destination Zip associated with above reference number
- Shipper num
shipper_numtext - The Shipper Number (Account Number) associated with above reference number
- Ref num type
ref_num_typetext - The Reference number type which will define the tracking information is related to small package or fgv
Outputs
dataobject- Returned value.
Example output
{
"data": {
"trackResponse": {
"shipment": []
}
}
}Track each package in shipment
Get the tracking status of every package in a multi-package shipment from one tracking number, a page at a time.
Inputs
- Inquiry number
inquiry_numbertextRequired - The tracking number for which tracking information is requested. Each inquiry number must be between 7 and 34 characters in length.
- Locale
localetext - Language and country code of the user, separated by an underscore. Default value is 'en_US'
- Offset
offsettext - This is used to support pagination of package results. The offset is a 0-based index which defines the starting record to be returned.
- Count
counttext - This is used to support pagination of package results. The count is the maximum number of packages to return starting with the offset.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"trackResponse": {
"shipment": []
}
}
}Track package
Get a package's tracking history by its tracking number: its status, each scan with time and place, and the delivery date. Can also return the delivery signature, milestones and proof of delivery.
Inputs
- Inquiry number
inquiry_numbertextRequired - The tracking number for which tracking information is requested. Each inquiry number must be between 7 and 34 characters in length.
- Locale
localetext - Language and country code of the user, separated by an underscore. Default value is 'en_US'
- Return signature
return_signaturetext - Indicator requesting that the delivery signature image be included as part of the response (by default the image will not be returned). Returns image bytecodes of the signature.
- Return milestones
return_milestonestext - returnMilestones
- Return pod
return_podtext - Return Proof of Delivery
Outputs
dataobject- Returned value.
Example output
{
"data": {
"trackResponse": {
"shipment": []
},
"tracking_records": []
}
}Validate address
Check a US or Puerto Rico street address against the US Postal Service's database and get it corrected or suggestions back. In the test environment it only checks addresses in New York and California.
Inputs
- City
citytextRequired - City.
- State
statetext - State.
- Postal code
postal_codetextRequired - Postal code.
- Country code
country_codetextRequired - Returned value.One of:
US(United States),PR(Puerto Rico). - Street lines
street_lineslist - Returned value.
Outputs
dataobject- N/A
Example output
{
"data": {
"XAVResponse": {
"AddressClassification": {
"Code": "example",
"Description": "example"
},
"AmbiguousAddressIndicator": "example",
"Candidate": [],
"NoCandidatesIndicator": "example",
"Response": {
"Alert": [],
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"ValidAddressIndicator": "example"
}
}
}Void shipment
Cancel a shipment that hasn't been picked up yet, by its shipment ID or a package's tracking number.
Inputs
- Trackingnumber
trackingnumbertext - The package's tracking number. You may have up to 20 different tracking numbers listed. If more than one tracking number, pass this value as: trackingnumber= ["1ZISUS010330563105","1ZISUS01033056310 8"] with a coma separating each number. Alpha-numeric. Must pass 1Z rules. Must be upper case. Length 18
- Shipmentidentificationnumber
shipmentidentificationnumbertextRequired - The shipment's identification number Alpha-numeric. Must pass 1Z rules. Must be upper case. Length 18
- Shipper number
shipper_numbertext - Shipper Number Required only for Roadie Shipments
Outputs
dataobject- N/A
Example output
{
"data": {
"VoidShipmentResponse": {
"PackageLevelResults": [],
"Response": {
"Alert": {
"Code": "example",
"Description": "example"
},
"ResponseStatus": {
"Code": "example",
"Description": "example"
},
"TransactionReference": {
"CustomerContext": "example"
}
},
"SummaryResult": {
"Status": {
"Code": "example",
"Description": "example"
}
}
}
}
}