User Guide

UPS Developer Kit

© 2017 United Parcel Service of America, Inc. UPS, the UPS brandmark and the color brown are trademarks of United Parcel Service of America, Inc. All rights reserved. us_en
UPS Developer Kit User Guide

Table of contents
UPS Developer Kit User Guide

Before you start

Technical considerations and access requirements . . . . . . . 3

Implementation
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Access and administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Product overview
Shipping and rating business processes . . . . . . . . . . . . . . . . . . . . . . 21
Visibility business processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
International trade business processes. . . . . . . . . . . . . . . . . . . . . . . 35

UPS Developer Resource Center

Accessing resources and technical support. . . . . . . . . . . . . . . . . . 40
Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Technical support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Welcome to the UPS Developer Kit User Guide. This

guide provides information on how to access developer UPS Developer Kit page at ups.com
To access this page, go to:
kits and servers to test and transact with UPS. It also
https://www.ups.com/upsdeveloperkit?loc=en_US&WT.svl=SubNav
provides detailed information on technical support
for the APIs including hours of operation and response
times.
The UPS Developer Kit offers flexibility in integrating
UPS functionality directly into your business systems
and e-commerce websites. UPS offers 14 functionalities
via APIs that allow you to improve business process
efficiencies and enhance your customers’ Web
experience.

© 2017 United Parcel Service of America, Inc. All rights reserved.

Before you start
UPS Developer Kit

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical considerations
Prior to downloading any APIs, you should be familiar Access requirements
with: Review whether the particular API provides Test and
• Programming URL or socket connections Production Access with initial access key request, or if
• Creating a secure socket implementation that supports additional Production Access requests are required. You
Current Payment Card Industry (PCI) standards for will also need to review if your business models are
secure connections approved for use with each API.
• Encoding and decoding XML documents Notes:
• Designing and implementing a strategy into your • Custom code, that adapts your application’s business
existing software for handling errors logic and data to the API, must be developed in order
Check the available versions (XML, Web Services, to integrate API functionality into your e-commerce
or JSON). and/or business system applications. Programming
language that supports HTTP communication across
Internet socket and secure connections, such as Java,
Visual Basic or C++ can be used.
• To help you effectively integrate APIs, this user guide
provides instructions on how to download developer
kits at ups.com as well as request access to APIs. The
developer kit includes an introduction to all APIs as
well as a developer guide (with technical FAQs).

© 2017 United Parcel Service of America, Inc. All rights reserved.

Implementation
UPS Developer Kit

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started
To access the UPS Developer Kit on ups.com type in
Search the following text, “Developer Resources”.
Select the Developer Resource Center link. Once at the
Developer Resource Center scroll down to Step 3 and
select Access the UPS Developer Kit. You will land on
the application page that will allow you to download
developer kits and request access to UPS APIs.

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 1: S
 ign up for ups.com profile.
If already signed up, skip to Step 3.

Step 2: L og In
Enter username. Click Next. You will then be
prompted to enter password. You must be
logged in to download document files.

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 3: S
 elect an API
Under Developer APIs, you will find the
requirements for each of the APIs you require
and can access downloadable files as well as
availability for specific countries. You may also
consult the Product Overview section of this
guide starting on page 21.

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 4: D
 ownload the API documentation
1. Download zip file for the chosen API
2. When prompted, click on Save
3. Extract file on local computer
The downloaded file contains the Software Developer
Kit. Carefully review the entire Developer Guide for the
APIs you will integrate. The Software Developer Kit also
includes sample code and WSDLs.

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

UPS provides a testing environment that is accessible
with an Access Key for all APIs. This will allow you to
simulate request and response messaging to ensure
you have properly formatted your XML or Web Service
requests.
Most APIs provide immediate access to both test and
production environments. However, there may be
certain APIs that require a second request to activate
production access. Please reference the web page and
e-mail notification that display what APIs may require a
second production access request.
Step 5: R
 equest an access key
Once you have reviewed the Software Developer
Kit, you should request access to the UPS test
environment. You will be asked to:
1. Provide account information
2. Authenticate account information
3. Upon authentication, you will receive
confirmation that your request has
been received

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 5: R
 equest an access key (cont.)
Submit account information.

10

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 5: R
 equest an access key (cont.)
1. Provide account authentication
2. Once authentication is completed, you will be
brought back to the Request Access Key page
3. Click on the Request Access Key button
at the bottom
Note: Account Invoice Authentication (AIA) is required
for you to see your negotiated rates via the Shipping
and Rating APIs. Ensure you have a copy of one of
your most three recent invoices to AIA authenticate.

11

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Getting started (cont.)

Step 5: R
 equest an access key (cont.)
View confirmation that your request was
received and receive a confirmation e-mail.

12

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration

Requesting production access
Most APIs provide immediate access to both test and
production environments. However, there may be
certain APIs that require a second request to activate
production access. Please reference the web page and
e-mail notification that display what APIs may require
a second production access request.
Ensure that your implementation meets UPS
requirements for gaining production access.
• Go the UPS Developer Kit page and select Manage
Access Keys in the Access and Administration section.
• A dialog window will appear requesting that you
review requirements for approval. Click Continue if
ready to proceed.

XXXXXXXXXXXXXXXX

13

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

Requesting production access (cont.)
Choose one or more APIs and select Next to continue.

If you currently have production access for all APIs you

will get this screen.

14

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

Requesting production access (cont.)
• Receive online and e-mail confirmation of your request
for production access.

15

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

View/update access keys
To manage and update access keys, go to the UPS
Developer Kit page and select Manage Access Keys
in the Access and Administration section.

16

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

View/update access keys (cont.)
• Enter your Access Key in the View/Update Access
Key section.

• The next screen will display a list of APIs with the status
(Test or Production) for the key you entered.
Note: From that page, you can also request production
access or a new Access Key.

17

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

Edit account/contact information
To update primary and secondary contact information,
as well as account information, go the UPS Developer
Kit page and select Administration in the Access and
Administration section.

18

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Access and administration (cont.)

Edit account/contact information (cont.)
Contact information will be displayed. Select Edit
to make changes.
Note: It is very important for specific e-mail notifications
regarding changes to UPS certificates and other major
changes that the contact information is current. Also,
if you used an integrator it is important that the contact
information is changed to your company IT contact so
they receive the important notifications.

A new screen will appear for you to make changes.

Click Save Changes once finished.

19

© 2017 United Parcel Service of America, Inc. All rights reserved.

Product overview
UPS Developer Kit

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available countries: U.S. and Puerto Rico

business processes for all modes of transport
Available version(s): XML and JSON
Address Validation API Available mode(s): All modes
Access requirements: One request for Test & Production access
Whether integrated into a Web page or a non-Web order
system, the Address Validation API allows merchants to
compare city-state-ZIP combinations provided by buyers
with those maintained on UPS’s central computers API limitations
(servers). If the combination is not valid, UPS returns a list • Only validates U.S. and Puerto Rico addresses
of possible city-state-ZIP combinations to the merchant’s
• No latitude longitude coordinates provided in the
application. UPS provides up to ten alternate addresses.
API response
Approved business models • Only validates city-state-ZIP combination — not street
address
• Validation of addresses for shipments tendered to UPS
for delivery • Only validates one city, state, ZIP combination
per request
Unapproved business models/usages • UPS address database updated monthly with
• “Scrubbing” address databases information provided by the USPS
• Validation of addresses for any uses other than • NOT a CASS certified validation engine
UPS shipping • Does not replace requirement for CASS AV software

21

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available countries: U.S. and Puerto Rico

business processes (cont.) for all modes of transport
Available version(s): XML, Web Service and JSON
Address Validation Street Level API Available mode(s): All modes
Access requirements: One request for Test & Production access
Whether integrated into a Web page or a non-Web
order system, the Address Validation Street Level (AVSL)
API allows merchants to compare street-city-state-ZIP
API limitations
combinations provided by buyers with those maintained
on UPS’s central computers (servers). If the combination • Only validates U.S. and Puerto Rico addresses
is not valid, UPS returns a list of possible street-city-state- • Only classifies (commercial/residential) U.S. and
ZIP combinations to the merchant’s application. UPS Canadian addresses
returns up to ten alternate addresses. • Only validates one street, city, state, ZIP combination
Additionally, the AVSL API classifies addresses per request
commercial/residential for a number of countries • Only validates apartment or suite if an apartment
please check the developer guide for a current listing or suite is provided within the API Request or if the
(classification is UPS internal operations classification apartment or suite are in the UPS database
not based upon USPS information). • No latitude longitude coordinates provided in the
API response
Approved business models • UPS address database updated monthly with
• Validation of addresses for shipments tendered information provided by the USPS
to and delivered by UPS • NOT a CASS certified application
Unapproved business models/usages • Does not replace requirement for CASS AV software
• “Scrubbing” address databases
• Validation of addresses for any use other than UPS
shipping

22

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 31 countries for Small Package only

business processes (cont.) Available version(s): Web Service and JSON
Available mode(s): Package
Dangerous Goods API Access requirements: One request for Test & Production access
The Dangerous Goods API allows applications to validate
dangerous goods shipments prior to shipping. The
Dangerous Goods API verifies that dangerous goods – United States – Code of Federal Regulations, Title 49 (49CFR)
shipments meet regulation set requirements as well This API works in conjunction with the Rating and Shipping API
as ensuring they are valid for carriage within the UPS or other manifesting systems.
transportation network.
Approved business models
Dangerous Goods validation and shipping require a
UPS Contract so please check with your UPS Sales Validating UPS Fully Regulated Dangerous Goods shipments
Person for available Dangerous Goods services prior (validates origin/destination and chemical details)
to downloading the developer kit. Validating UPS Dry Ice, International Special Commodities –
Biological Substances Category B, and/or Lightly Regulated Lithium
Functionality includes: Batteries shipments (origin/destination validation only)
– Acceptance Audit Pre-check validates a Dangerous
• Use with manifesting systems that currently do not have hazmat
Goods shipment is acceptable to UPS. Validations
validation. Can be used in conjunction with Shipping and Rating
include origin/destination country and postal code,
APIs to process UPS Small Package shipments.
UPS service, regulation set, transportation mode,
and chemical record details (quantity, packing group, Unapproved business models/usages
packing instruction, etc.). • Validating shipments not intended for transport by UPS (Please note,
– Chemical Reference Data Lookup retrieves Dangerous the Dangerous Goods API is to be used for UPS shipments only.)
Goods chemical record details (i.e. allowable packing
groups, packing instructions, etc.) based upon UN API limitations
number or Proper Shipping Name. This functionality • Geographic validation updated monthly
complements the Acceptance Audit Pre-check. • Dangerous Goods chemical validation updated quarterly
Regulation sets supported include: Available Countries
– European Agreement Concerning the International • See available countries at ups.com Approved Countries List
Carriage of Dangerous Goods by Road (ADR) (https://www.ups.com/assets/resources/media/dangerous-
– International Air Transport Association (IATA) 23
goods-service-areas.pdf)
© 2017 United Parcel Service of America, Inc. All rights reserved.
UPS Developer Kit User Guide

Shipping and rating Available in 28 countries for Small Package only

business processes (cont.) Available version(s): XML and JSON
Available mode(s): Package
Locator API Access requirements: One request for Test &
Production access
The Locator API enables users to find local UPS service
locations using an address or phone number. The
Locator API provides UPS full-service and self-service
locations, hours of operation and pickup times. The Approved business models
Locator API can be customized to present information in • Use on merchant websites and non-Web, back-end
different configurations that include locations, additional systems
services, program types, type codes and if a location
Unapproved business models/usages
is a retail location. In addition, the Locator provides an
interactive map that displays up to ten UPS locations • Use by third-party logistics providers
and turn-by-turn driving directions (where available).
API limitations
Find locations such as: • Latitude longitude coordinates are not provided
• UPS Access Point ®
• Maps are not provided
• The UPS Store ®

• Mail Boxes Etc.®

• UPS Drop Boxes
• UPS Customer Centers
• UPS Express®
• Retail Chains
• UPS Authorized Shipping Outlet (ASO)
• UPS Authorized Service Providers

24

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 39 countries for Package and LTL Freight
business processes (cont.) (Gemini for Air Freight)
Available version(s): XML, Web Service and JSON
Pickup API Available mode(s): Package and LTL Freight
(Gemini for Air Freight)
The Pickup API enables users to schedule a UPS pickup
Access requirements: One request for Pickup API Small Package
from their home or office. Users may also schedule for Test & Production access, two
the pickup of a previously processed package, freight separate requests for Pickup API Ground
shipment or new shipment. Additionally, UPS’s Freight for Test & Production access
environmentally friendly pickup options are available
with the small package Pickup API.

Approved business models

•U
 se on merchant websites and non-Web, back-end
systems

Unapproved business models/usages

• Third-party hosting of pickup requests
• Use by third-party logistics providers

API limitations
• None

25

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 31 countries for Small Package

business processes (cont.) Available version(s): Web Service and JSON
Available mode(s): Package
Pre-Notification API Access requirements: One request for Test & Production access
The Pre-Notification API allows customer applications to
inform UPS operations of dangerous goods shipments
Approved business models
that have been processed and will enter the UPS
transportation network prior to an upload of manifest • Use with manifesting systems to notify UPS of processed
information at the end of the day. This will assist in Fully Regulated Dangerous Goods shipments
improved handling and fewer delays for dangerous
Unapproved business models/usages
goods shipments. The Pre-Notification API can be used
in conjunction with other APIs after a dangerous goods • None
shipment has been processed.
API limitations
Finally, the use of this API will be required for customers
• None
who have a dangerous goods contract and are shipping
cargo quantities of dangerous goods or are shipping
dangerous goods via road transport in Europe (European
Agreement Concerning the International Carriage of
Dangerous Goods by Road or ADR).
Functionality includes:
• Notify UPS of dangerous goods shipments once the
shipment is processed.
• Notify UPS of voided dangerous goods shipments.
In addition, custom code that adapts your application’s
business logic and data to the API must be developed
in order to integrate this API’s functionality into your
business systems.

26

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 103 countries for Small Package, 4 countries for LTL
business processes (cont.) Freight and 36 countries for Air Freight (Gemini APIs)
Available version(s): XML, Web Service and JSON (see notes)
Rating API Available mode(s): Package, LTL Freight (1), Air Freight (2)
Access requirements: Two separate requests for Test &
The Rating API provides rates (daily pickup, on-demand,
Production access for LTL Freight and
or retail) for available UPS small package and UPS® manual request for Air Freight via the
Freight LTL service levels to any destination served by Gemini APIs request form (see links at
UPS. The Rating API can be configured to present all rates UPS Developer Kit at ups.com)
available (“Shop” option) or rates for specific service
levels (“Rate” option). Published rates are provided by
Notes:
default; account-specific negotiated rates can be enabled
(1) Web Service only for LTL Freight
by Account Invoice Authentication in the Account
(2) Air Freight through Gemini APIs XML only
Summary or Account Maintenance pages at ups.com.
Please see page 11 of this guide for further details. The
Rating API provides delivery date and time for all services
except Ground (the Time-in-Transit API must be used for
this information).

Approved business models API limitations

• Use on merchant websites and non-Web, back-end • Rating for Air Freight requires use of the Gemini APIs.
systems Please see the UPS Developer Kit home page as well as
the Announcements and API Updates section for a link
Unapproved business models/usages to the Gemini APIs request form and developer guide.
• Display of UPS rates side by side with competitor rates Please read the request form thoroughly for gaining
access to this API.
Rating API supports hazmat rating.

27

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 103 countries for Small Package, 4 countries for LTL
business processes (cont.) Freight and 36 countries for Air Freight (Gemini APIs)
Available version(s): XML and Web Services (see notes)
Shipping API Available mode(s): Package, LTL Freight (1), Air Freight (2)
Access requirements: Two separate requests for Test &
The Shipping API supports the integration of UPS’s Production access for LTL Freight and
shipping functionality across enterprise systems and manual request for Air Freight via the
websites. Integration allows for use of data from the Gemini APIs request form (see links
shipper’s applications without requiring key-entry at UPS Developer Kit at ups.com)
by the user while supporting internal processes with
convenient and controlled access to shipping. The
Shipping API also supports the entire small package Notes:
UPS Returns® portfolio, including international returns. (1) Web Service and JSON for LTL Freight
UPS residential/commercial address classification (2) Air Freight through Gemini APIs XML only
and city, state and ZIP validation are also provided.
Integration of the UPS Shipping API requires significant
programming time and expertise.

How the Shipping API works

The process consists of two phases: the Ship Confirm
phase followed by the Ship Accept phase. An XML
request/response pair is exchanged between the client
and server in each phase. Please note that cancelling
or voiding a shipment requires its own procedure and
message types.

Approved business models

• Use on merchant (UPS Ready® Provider) websites and
non-Web, back-end systems
• When integrated on a website with controls for access Shipping API supports hazmat shipping.
• Use by third-party application vendors strictly
controlled through the UPS Ready program
28

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating

business processes (cont.)
Shipping API (cont.)

Unapproved business models/usages

• Display of UPS rates side by side with competitor rates
• No side-by-side comparisons with competitors on
external or Web-based implementations
• No hosting of Shipping API on any website

API limitations
• Not supported: World Ease® functions, Batch Processing
and UPS Hundredweight Service® aggregation

Shipping API supports hazmat shipping.

29

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Shipping and rating Available in 103 countries for Small Package only
business processes (cont.) Available version(s): XML, Web Service and JSON
Available mode(s): Package
Time-in-Transit API Access requirements: One request for Test & Production access
for UPS approved business models
The Time-in-Transit API lets users compare the speed
of delivery of different services so they can select
the service most appropriate for a shipment. This API
provides access to all available UPS shipping services
for anywhere UPS delivers around the world. The
information includes the scheduled delivery date and
time as well as the number of days in transit. Provides
date and time of delivery for ground packages which
take into account UPS holidays and weekends.

Approved business models

•U
 se on merchant websites and non-Web, back-end
systems

Unapproved business models/usages

• Use by third-party information logistics providers who
are not a party to the transaction
• For creating Time-in-Transit tables from UPS proprietary
information

API limitations
• None

30

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Visibility business processes Available in 31 countries for Small Package only

Available version(s): XML and JSON
Quantum View® API Available mode(s): Package
Quantum View® Data provides comprehensive tracking Access requirements: One request for Test & Production access
information that can be seamlessly integrated into
in-house applications, from spreadsheets and simple
databases to ERP systems.
Subscriptions
Shipment status updates can be automatically This feature gives you a way to indicate which types
downloaded to internal system, as frequently as every of Quantum View events you wish to retrieve. You can
hour if needed, in a number of common data file set up subscriptions for outbound shipments, inbound
formats (CSV, XML, TXT or EDI ANSI or EDI EDIFACT). shipments and shipments using alternate billing. These
• Outbound subscriptions can include manifest, origin, delivery and
• Inbound exception activity. Quantum View subscriptions are
created by you through ups.com. Managing the type of
• Third-party – Current information on shipments billed
information you receive and the type of subscription is
to a UPS account via Freight Collect, third-party or
all completed at ups.com. To activate your subscription
Consignee Billing.
you must contact your sales representative.
Understanding XML Quantum View services Bookmarks
Quantum View information is presented as “events”. For users with high volume of activity and to ease the
With this API, your application can automatically retrieve burden on network resources, the Quantum View API
Quantum View events and integrate the information may limit the amount of information returned for
into your systems’ processes. any single request. This limit is approximately 150KB
for multiple combined files or 500KB for a single file.
For files exceeding the limit, UPS returns part of the
information and appends a special bookmark element
to the response. To retrieve the additional information,
re-issue the original request with the bookmark element
added.

31

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Visibility business processes (cont.)

Quantum View API (cont.)

Information format
When your application requests Quantum View events,
the API returns only events that have not been viewed
before. File name and date/time requests are the only
exceptions to this rule.

Approved business models

• Use
 on merchant websites and non-Web, back-end
systems

Unapproved business models/usages

• Use by third-party logistics providers

API limitations
• Updates are batch and limited to every 30 minutes
with updates
• Files must be appended to existing data, in that only
what has changed is included in the hourly file updates
• Only Manifest, Exception and Delivery scans are
provided within the files. No intermediate scans
(in transit scans)

32

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Visibility business processes (cont.) Available in 103 countries for all transport modes
Available version(s): XML, Web Service and JSON
Tracking API Available mode(s): All modes
The Tracking API provides transparency in allowing Access requirements: One request for Test &
customers to track their shipments from an e-commerce Production access
site using a reference or order number. Customers
can find specific details about their shipment’s status,
including the time and location of each scan as the
API limitations
package moves toward its final destination. Additionally,
tracking information can blend seamlessly with the look • Limit of 64KB per response regardless of the size
of your site. of a shipment
• Shipments with 50 packages may only return the first
Approved business models 15 packages dependent upon how much tracking
•U
 se on merchant websites and non-Web, back-end information is available on the packages
systems • Transactional not batch and no batch upload
of tracking numbers
Unapproved business models/usages • The API only tracks a single tracking or reference
• Use by third-party information logistics providers who number with each tracking request
are not a party to the transaction • Package scans and weight information is available
• Use by “robots” that track every outbound package for six months
until a specified event • Reference number tracking is available for four months
• Delivery scan information is available for 18 months

33

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Visibility business processes (cont.) Available in 45 countries for Small Package only
Available version(s): XML, Web Service and JSON
UPS Signature Tracking® API Available mode(s): Package only
The UPS Signature Tracking API provides the same Access requirements: One request for Test & Production access
information as the Tracking API plus: for UPS approved business models
• Receiver’s name and address
• C.O.D. collected amount
Approved business models
• Proof of Delivery (POD) signature image
• Use on merchant websites and non-Web, back-end
Merchants can integrate a POD letter image into their systems
systems to automatically e-mail, mail or fax a POD letter
to buyers proactively or in response to non-payment Unapproved business models/usages
or requests for POD. Since the POD letter includes the • Use by third-party information logistics providers who
receiver’s signature (when collected), this solution are not a party to the transaction
can meet the demands of buyers not satisfied with • Use by “robots” that track every outbound package until
the “clarified” (typed by UPS driver service provider) a specified event
signature information provided by the standard
Tracking API. API limitations
Note: Processing requests requires that the account • Same as Tracking API
number is included. Tracking numbers generated by other • Additional limitation of storage of signatures for
accounts will not work unless those accounts are added 18 months
to the My UPS ID Account Summary for the My UPS ID
used in the XML Request.

34

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

International trade business Available in 68 countries for Small Package

processes Available version(s): Web Service and JSON
Available mode(s): Small Package
Paperless Document API Access requirements: Single request for Test & Production
access for UPS approved business models
Paperless Document API provides you the ability to
upload your document images in conjunction with
your shipments. This eliminates the need to attach
paper shipping documents to the package and the Understanding Paperless Document API processing
associated issues of processing delays. This API is used • The Paperless Document API Web Service consists
in conjunction with other manifesting systems as well of three operations:
as the Shipping API. This capability essentially eliminates 1. Upload documents to Forms History (See API
the hassle of lost or damaged paperwork and allows for Limitations on page 34).
seamless and automated linking of shipments and the
2. Delete uploaded documents (one document ID
document images required for processing.
per delete request).
Note: You must have a valid six-digit account number 3. Push uploaded documents to Image Repository.
and be enabled by your UPS Account Manager for
your account within the UPS back-end systems to use Note: You will need to build input screens that collect
the Upload My Forms at ups.com or the Paperless information needed by the application to initiate
Document API. If the shipper number is not enabled upload, delete and push requests for document
within back-end systems for the Upload Forms, the images created.
Paperless Document API will throw a hard error.

35

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

International trade business Step 3: Go to Paperless Document API and provide
processes (cont.) the Document ID from Step 1 along with the
Shipment Identification number and Tracking
Number(s) from Step 2. Complete a Push To
Paperless Document API (cont.) Image Repository Request, which will push the
There are two options when you use the Paperless documents to Forms Repository which will
Document API with the Shipping API or other return a Forms Group ID back to you.
manifesting systems.
Approved business models
Option 1: • Use with shipments that require documentation within
Step 1: Go to Paperless Document API and complete internal business processes or other back-end systems.
an Upload Request. Upload your documents This is not for hosting on the Web.
to Forms History and receive a Document ID.
Unapproved business models/usages
Step 2: Go to Shipping API and submit a request to
create a domestic or international shipment • Use by third-party logistics providers
with the Document ID from Step 1. Shipping
API will internally push the documents to a API limitations
Forms Repository and return Forms Group ID • The API is capable of handling multiple files and
in response back. multiple documents in each file.
– Maximum allowable size for each file is 1MB with a
Option 2: total maximum allowable size limit for all files of 5MB.
Step 1: Go to Paperless Document API and complete – Maximum of 13 files are allowed per request with no
an Upload Request. Upload your documents more than 13 documents in each file or in total per
to Forms History and receive a Document ID. shipment
Step 2: Go to Shipping API and submit a request to create • There are two steps to each document image.
a domestic or international shipment. You will Step 1: Upload the image.
receive a Shipment Identification number and
Step 2: Submit the image either through the Shipping
Tracking Number(s).
API or the Paperless Document API.

36

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

International trade business Available in 34 countries for Small Package

processes (cont.) Available version(s): Web Service and JSON
Available mode(s): Package
UPS TradeAbility® API Access requirements: Single request for Test & Production
access for UPS approved business models
UPS TradeAbility suite of information-based services
enables the effective management of the movement of
goods across international borders. The UPS TradeAbility •D
 enied Party Screener API
APIs can help improve regulatory compliance, reduce From one source, determines who is on the U.S.
operating expenses, and streamline global supply chains government watch lists, ensuring current and accurate
and international trade processes. compliance with government regulations. Allows
• Landed Cost API single transactions and the selection of different match
Estimates the cost of international shipments: settings to allow broader searches and checks a single
including duties, customs fees and taxes. Preferential source for named parties and destination countries,
duty rates may be included in Landed Cost estimates plus it provides specific reasons for denial and list
by default. For these rates to be applied when shipping, sources.
shipper must submit proper documentation along with • Import Compliance API
the shipment. Allows transactions containing up to 99 Helps reduce border delays by maximizing compliance
products per shipment from one origin country to with country-specific trade relations, procedures and
one destination country. To provide the most accurate restrictions before importing. Import Compliance
estimate of landed cost, the service may refine its transaction details will be stored and can be accessed
estimate through a series of interactive queries and for 90 days. Allows transactions containing up to 99
responses using the QueryRequest element. User products per shipment from one origin country to one
re-issues the request and includes answers using destination country.
EstimateRequest elements. Once UPS has received all •E
 xport License Detector API
the information needed, a landed cost estimate will be Accesses the latest U.S. export license requirements
provided. based on destination country or commodity
information such as Export Classification Number, to
help reduce the risk of fines and sanctions.

37

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

International trade business

processes (cont.)
UPS TradeAbility APIs (cont.)

Approved business models

• Approved for End Users and UPS Ready® Providers

Unapproved business models/usages

• No hosting of UPS TradeAbility APIs by unapproved
third parties

API limitations
• No Harmonized Code lookup functionality

38

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer
Resource Center
UPS Developer Kit

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Accessing resources
and technical support
You can access the Developer Resource Center
by following these steps:
Step 1: Type in search engine or on ups.com search
UPS Developer Resource Center.
Step 2: Select the UPS Developer Resource Center
or Developer Resource Center link.

40

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Resources
Follow key three steps (and associated links) as well as
links to access technical support and the UPS Developer
Kit Community through the UPS Developer Resource
Center.
Step 1: Integration/Planning
Learn About Integrating UPS Developer Kit APIs
Plan Your Integration
Read the Instructions for Developers
View a List of Available APIs
Step 2: Getting Started/Instructions
Learn how to access UPS Developer Kit and servers to test
and transact with UPS.
View the UPS Developer Kit User Guide
View the Quick Reference Guide
View the Developer Kit FAQs
Step 3: Developers: Download APIs
Obtain and manage your API credentials and download
developer kits.
Access the UPS Developer Kit
Access Gemini Downloads and Tool Kit

41

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical support
There are four channels for obtaining support for the
UPS Developer Kit APIs, all of which may be accessed
through the UPS Developer Resource Center. Instructions
on getting access to the UPS Developer Resource Center
can be found on page 40.

UPS Developer Kit support

1. U
 PS Developer Kit Community
This is a community forum for developers to answer
one another’s questions and share information,
therefore response time may vary. There is also a
“System Status Page” that allows registered customers
to subscribe to e-mail notifications when changes are
posted to this web page.
2. E
 -mail technical support (preferred channel)
This is the support channel for technical support and
questions regarding API integration. It is accessed by
logging in and attaching your XML Request/Response
files and any other pertinent information about your
integration. UPS E-mail Technical Support can only
support the XML Request/Response pair. Technical
support cannot advise customers and developers
on how to integrate the XML into their internal or
purchased software.

42

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical support (cont.)

UPS Developer Kit support (cont.)
3. G
 eneral questions phone support
(limited to ups.com navigation support)
Phone support is the least comprehensive support
mechanism for developers. This channel of support
addresses questions about the user interface at
ups.com and how to gain access to the APIs and
navigate the Access Key request process. It does not
provide technical support for XML Request/Response
issues and questions. Those types of questions must
go through UPS E-mail Technical Support.
4. U
 PS Developer Kit FAQs
This is a self-service support PDF document that
can be opened or downloaded. It contains over 240
frequently asked questions about every mode and
service supported by the UPS Developer Kit APIs.
It’s also available in an online version at the UPS
Developer Kit Community.

43

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical support (cont.)

Getting e-mail technical support
Step 1: From the Developer Resource Center page select
the E-mail UPS link in right hand column.

Step 2: Complete name, e-mail address fields, Support

Category must be Technical Support, Support
Topic must be Developer Resources, click Next.

44

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical support (cont.)

Getting e-mail technical support (cont.)
Step 3: Scroll down the page and complete the
remainder of the form, including:
– Your Telephone
– Stage of Development
– Developer Resource which is the API you are
integrating
• Attach your XML Request/Response Pair file. (You must
be logged in to attach files)
• Include any pertinent description of the issues in the
What is your question or comment? field
• Select Send E-mail button

45

© 2017 United Parcel Service of America, Inc. All rights reserved.

UPS Developer Kit User Guide

Technical support (cont.)

Technical support hours and response times Note: If you are sent an e-mail from first-level E-mail Tech
Support stating your case log # has been escalated, the
First-level e-mail technical support 24 hour planned response clock starts from the time you
• Hours of operation are 8:00 a.m. to 8:00 p.m. EST receive the e-mail from first-level E-mail Tech Support
Monday through Friday (provided the Escalation Support desk is open). If not,
• E-mail response time is planned to be within four then the clock will begin when the Escalation Support
business hours of the initial request desk opens. This means if your case log is escalated
• Business hours are defined as hours of operation at 8:30 p.m. on Friday, you may not receive an e-mail
of the Tech Support desks when service technicians response from the Escalation Support desk until Monday
are working (UPS holidays excluded) at 8:00 p.m. at the latest (Saturdays, Sundays and
holidays are excluded). Response times are from the time
Note: If you submit an e-mail request after business the case log was escalated plus 24 hours which does not
hours, the four hour response time frame will not begin include weekends or UPS holidays.
until the following morning at 8:00 a.m. EST Monday
through Friday.

Escalation support
• Hours of operation are 8:00 a.m. to 8:00 p.m. EST
Monday through Friday
• Response time is planned to be within 24 hours during
normal hours of operation
• Closed weekends and on UPS holidays

46

© 2017 United Parcel Service of America, Inc. All rights reserved.