UPS

App · 20 actions

Track shipments, quote rates, validate addresses, manage labels and shipments, and schedule or cancel pickups.

Actions

ActionWhat it does
Cancel delivery interceptCancel a previously applied intercept on the package.
Cancel pickupCancel a booked UPS on-demand pickup by its pickup request number, and get confirmation it was cancelled.
Create pickupBook a UPS pickup at an address, with the date, time window, packages and weight, and get its pickup request number.
Create shipmentCreate a UPS shipment and get its tracking number, charges and shipping label.
Find locationsFind 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 centersFind UPS service centers near an address, with each one's address, phone number, location code and drop-off and pickup hours.
Get delivery intercept chargesFind what it would cost to redirect, reschedule or return a package, by its tracking number and the kind of change.
Get delivery intercept eligibilityCheck whether a package can still be redirected, held or returned to sender, by its tracking number.
Get pickup countriesList the states or provinces of a country or territory that UPS pickups can be booked in.
Get pickup ratesFind what a UPS on-demand pickup would cost for an address, date and time window, before booking it.
Get pickup statusCheck the status of an account's pending pickups: received, dispatched, completed, incomplete, an updated arrival time, or cancelled.
Get shipping ratesCompare prices for a shipment across UPS services, given the addresses, packages and weights.
Get transit timesFind how many days each UPS service takes between two places for a ship date, with the expected delivery date for each.
Recover labelGet the shipping or return label for a shipment again by its tracking number or reference, as an image or a link.
Request return to senderReturn a package to the original shipper prior to delivery.
Track by reference numberFind 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 shipmentGet the tracking status of every package in a multi-package shipment from one tracking number, a page at a time.
Track packageGet a package's tracking history by its tracking number: its status, each scan with time and place, and the delivery date.
Validate addressCheck a US or Puerto Rico street address against the US Postal Service's database and get it corrected or suggestions back.
Void shipmentCancel 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 numbertracking_numbertextRequired
The number being tracked. Each method defines if required.
Locloctext
The locale of the client application to ensure that translations on the response are in the proper language.
Request typerequest_typetext
Returned value.
Requester contact info namerequester_contact_info_nametextRequired
Contact Name
Requester contact info telephonerequester_contact_info_telephonetextRequired
Contact phone number
Requester contact info phone extrequester_contact_info_phone_exttext
Contact phone extension
Requester contact info email addressrequester_contact_info_email_addresstext
Contact email address
Requester contact info alt telephonerequester_contact_info_alt_telephonetext
Alternate Contact phone number
Requester contact info alt phone extrequester_contact_info_alt_phone_exttext
Alternate Contact phone extension
Requester contact info display phone numberrequester_contact_info_display_phone_numbertrue/false
Indicates if the phone number of a UAP can be displayed to external clients.
Reason for returnreason_for_returntext
Returned value.
Delivery datedelivery_datetext
Original scheduled date of delivery. Required olny for FD intercept type.
Special instructionsspecial_instructionstextRequired
Special Instructions sent to the driver. Available only to AA intercept type
New delivery addressnew_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 numberprntextRequired
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

Requestpickup_creation_request_requestobjectRequired
Common element for all services
Rate pickup indicatorpickup_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 typepickup_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 indicatorpickup_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 indicatorpickup_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)
Shipperpickup_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 addresspickup_creation_request_pickup_addressobjectRequired
The container of pickup address.
Alternate address indicatorpickup_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 piecepickup_creation_request_pickup_piecelistRequired
Returned value.
Total weightpickup_creation_request_total_weightobject
Container for the total weight of all the items.
Overweight indicatorpickup_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 datapickup_creation_request_tracking_datalist
Returned value.
Tracking data with reference numberpickup_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 methodpickup_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 instructionpickup_creation_request_special_instructiontext
Special handling instruction from the customer
Reference numberpickup_creation_request_reference_numbertext
Information entered by a customer for Privileged reference
Freight optionspickup_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 categorypickup_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 typepickup_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 availablepickup_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 indicatorpickup_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)
Notificationpickup_creation_request_notificationobject
Container for pickup notification
Pickup datepickup_datedateRequired
The pickup date at the pickup location.
Ready timeready_timetimeRequired
The earliest pickup time at the pickup location.
Close timeclose_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

Additionaladdressvalidationadditionaladdressvalidationtext
Valid Values: city = validation will include city.Length 15
Shipment request requestshipment_request_requestobjectRequired
Request Container
Shipment request shipmentshipment_request_shipmentobjectRequired
Shipment Container
Shipment request label specificationshipment_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 specificationshipment_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

Localelocaletext
Locale of request
Locator request requestlocator_request_requestobjectRequired
N/A
Locator request origin addresslocator_request_origin_addressobjectRequired
Container for origin address information.
Locator request translatelocator_request_translateobjectRequired
Contains the locale information for the request.
Locator request unit of measurementlocator_request_unit_of_measurementobject
Distance unit of measurement. This is required for location requests (request option 1).
Locator request location IDlocator_request_location_idlist
Location ID is the identification number of the UPS affiliated location.
Locator request location search criterialocator_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 criterialocator_request_sort_criteriaobject
Container for Sort Criteria
Locator request allow all confidence levelslocator_request_allow_all_confidence_levelstext
Indicator to allow confidence level in search.
Locator request search option codelocator_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 unitlocator_request_service_geo_unitobject
ServiceGeoUnit Container. Required to search for the freight facility information
Locator request freight indicatorlocator_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 requestpickup_get_service_center_facilities_request_requestobjectRequired
Container for the Request.
Pickup get service center facilities request pickup piecepickup_get_service_center_facilities_request_pickup_piecetextRequired
Returned value.
Pickup get service center facilities request origin addresspickup_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 addresspickup_get_service_center_facilities_request_destination_addressobject
DestinationAddress container. Conditionally required for pickup location search.
Pickup get service center facilities request localepickup_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 indicatorpickup_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 numbertracking_numbertextRequired
The number being tracked. Each method defines if required.
Locloctext
The locale of the client application to ensure that translations on the response are in the proper language.
Client ipclient_iptext
IP address of the requesting device
Rating requestrating_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 numbertracking_numbertextRequired
The number being tracked. Each method defines if required.
Locloctext
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

CountrycodecountrycodetextRequired
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 typepickuptypetextRequired
Type of pickup. Valid values: oncall smart both. Length 6One of: oncall, smart, both.
Requestpickup_rate_request_requestobjectRequired
Common element for all services
Shipper accountpickup_rate_request_shipper_accountobject
Shipper account information.
Pickup addresspickup_rate_request_pickup_addressobjectRequired
The address to pickup the packages
Alternate address indicatorpickup_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 optionpickup_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 typepickup_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 indicatorpickup_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 indicatorpickup_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 datepickup_datedate
The pickup date at the pickup location.
Ready timeready_timetime
The earliest pickup time at the pickup location.
Close timeclose_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 typepickuptypetextRequired
Type of pickup. Valid values: oncall smart both. Length 6One of: oncall, smart, both.
Account numberaccount_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

Additionalinfoadditionalinfotext
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 requestrate_request_requestobjectRequired
Request container. N/A
Rate request pickup typerate_request_pickup_typeobject
Pickup Type container tag.
Rate request customer classificationrate_request_customer_classificationobject
Customer classification container. Valid if ShipFrom country or territory is "US"
Rate request shipmentrate_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 codeorigin_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 provinceorigin_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 nameorigin_city_nametext
The shipment origin city. Required for International requests for those countries that do not utilize postal codes.
Origin town nameorigin_town_nametext
The shipment origin town. Town is a subdivision of city.
Origin postal codeorigin_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 codedestination_country_codetext
The country code of the destination. Valid values: Must conform to ISO-defined country codes.
Destination state provincedestination_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 namedestination_city_nametext
The shipment destination city. Required for International Requests for those countries that do not utilize postal codes.
Destination town namedestination_town_nametext
The shipment destination town. Town is a subdivision of city.
Destination postal codedestination_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 indicatorresidential_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 dateship_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 timeship_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.
Weightweightnumber
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 measureweight_unit_of_measuretext
Required for International requests and when weight value is provided. Valid Values: "LBS", "KGS"
Shipment contents valueshipment_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 codeshipment_contents_currency_codetext
The unit of currency used for values. Required if ShipmentContentsValue is populated. Valid value: must conform to ISO standards.
Bill typebill_typetext
Required for International Requests. Valid values: "02","03","04" 02 - Document 03 - Non Document 04 - WWEF (Pallet)
Avv flagavv_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 packagesnumber_of_packagesnumber
Sets the number of packages in shipment. Default value is 1.At most 1.
Drop off at facility indicatordrop_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 indicatorhold_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 servicesreturn_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 listmax_listnumber
Sets the limit for the number of candidates returned in candidate list. Default value is 200.At most 1.
Premier indicatorpremier_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 requestlabel_recovery_request_requestobjectRequired
Request Container.
Label recovery request label specificationlabel_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 translatelabel_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 deliverylabel_recovery_request_label_deliveryobject
Container for the Label Delivery accessorial. One Label Delivery per shipment.
Label recovery request tracking numberlabel_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 numberslabel_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 numberlabel_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 valueslabel_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 localelabel_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 formlabel_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 numbertracking_numbertextRequired
The number being tracked. Each method defines if required.
Locloctext
The locale of the client application to ensure that translations on the response are in the proper language.
Request typerequest_typetext
Returned value.
Requester contact info namerequester_contact_info_nametextRequired
Contact Name
Requester contact info telephonerequester_contact_info_telephonetextRequired
Contact phone number
Requester contact info phone extrequester_contact_info_phone_exttext
Contact phone extension
Requester contact info email addressrequester_contact_info_email_addresstext
Contact email address
Requester contact info alt telephonerequester_contact_info_alt_telephonetext
Alternate Contact phone number
Requester contact info alt phone extrequester_contact_info_alt_phone_exttext
Alternate Contact phone extension
Requester contact info display phone numberrequester_contact_info_display_phone_numbertrue/false
Indicates if the phone number of a UAP can be displayed to external clients.
Reason for returnreason_for_returntext
Returned value.
Delivery datedelivery_datetext
Original scheduled date of delivery. Required olny for FD intercept type.
Special instructionsspecial_instructionstextRequired
Special Instructions sent to the driver. Available only to AA intercept type
New delivery addressnew_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 numberreference_numbertextRequired
The reference number for which tracking information is requested.
Localelocaletext
Language and country code of the user, separated by an underscore. Default value is 'en_US'
From pick up datefrom_pick_up_datedate
The tracking information for the above reference number will be searched from this date
To pick up dateto_pick_up_datedate
The tracking information for the above reference number will be searched till this date
Dest countrydest_countrytext
The Destination Country associated with above reference number
Dest zipdest_ziptext
The Destination Zip associated with above reference number
Shipper numshipper_numtext
The Shipper Number (Account Number) associated with above reference number
Ref num typeref_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 numberinquiry_numbertextRequired
The tracking number for which tracking information is requested. Each inquiry number must be between 7 and 34 characters in length.
Localelocaletext
Language and country code of the user, separated by an underscore. Default value is 'en_US'
Offsetoffsettext
This is used to support pagination of package results. The offset is a 0-based index which defines the starting record to be returned.
Countcounttext
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 numberinquiry_numbertextRequired
The tracking number for which tracking information is requested. Each inquiry number must be between 7 and 34 characters in length.
Localelocaletext
Language and country code of the user, separated by an underscore. Default value is 'en_US'
Return signaturereturn_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 milestonesreturn_milestonestext
returnMilestones
Return podreturn_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

CitycitytextRequired
City.
Statestatetext
State.
Postal codepostal_codetextRequired
Postal code.
Country codecountry_codetextRequired
Returned value.One of: US (United States), PR (Puerto Rico).
Street linesstreet_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

Trackingnumbertrackingnumbertext
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
ShipmentidentificationnumbershipmentidentificationnumbertextRequired
The shipment's identification number Alpha-numeric. Must pass 1Z rules. Must be upper case. Length 18
Shipper numbershipper_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"
        }
      }
    }
  }
}

On this page