United Parcel Service (UPS)¶

On this page

Overview
Onboard a Merchant to Print UPS Labels
API Operations for Shipping with UPS
UPS Services
UPS Special Services
UPS Parcels
UPS Labels
Samples
UPS Surcharges

Overview¶

The Global Ecommerce APIs integrate with UPS^® shipping services through the API operations listed on this page. Shipments can originate from the U.S. and Canada. To print UPS labels, a merchant must have an existing UPS account.

Onboard a Merchant to Print UPS Labels¶

To print UPS labels through the APIs:

The merchant must be enrolled with your developer account. For more information, see Merchant Enrollment Models.
The merchant must have an existing account with UPS. If a merchant does not have an existing UPS account, the merchant can register for an account at https://wwwapps.ups.com/doapp/signup?loc=en_US.
The merchant must register the UPS account for use with the APIs, as described in Add Commercial Carrier Accounts.

API Operations for Shipping with UPS¶

The APIs integrate with UPS through the following operations:

Operation	Method	Resource Path
Add Carrier Account	POST	/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier=UPS
Rate a Parcel	POST	/v1/rates
Create a UPS Label	POST	/v1/shipments
Reprint a Label	GET	/v1/shipments/{shipmentId}?carrier=UPS
Retry a Label	GET	/v1/shipments?originalTransactionId={transaction_id}&carrier=UPS
Void a Label Note: This operation is available only in Production and not available in Sandbox.	DELETE	/v1/shipments/{shipmentId}?carrier=UPS&cancelInitiator=SHIPPER
Get Tracking Information	GET	/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber
Merchant Accounts APIs	——	See API Operations for Merchant Accounts.

UPS Services¶

The following are the supported services for UPS.

U.S. Domestic Services¶

Service	ID	Shipment Origin
UPS Next Day Air® Early	NDA_AM	U.S. 48, Alaska, Hawaii
UPS Next Day Air®	NDA	U.S. 48, Alaska, Hawaii, Puerto Rico
UPS Next Day Air Saver®	NDA_SVR	U.S. 48, Alaska, Hawaii
UPS 2nd Day Air® A.M.	2DA_AM	U.S. 48, Alaska, Hawaii
UPS 2nd Day Air®	2DA	U.S. 48, Alaska, Hawaii, Puerto Rico
UPS 3 Day Select®	3DA	U.S. 48
UPS® Ground	GRD	U.S. 48, Alaska, Hawaii, Puerto Rico
UPS® Ground - Intra AK	GRD	Alaska
UPS® Ground - Intra Oahu	GRD	Hawaii

U.S. International Services¶

Service	ID	Shipment Origin
UPS Worldwide Express Plus®	XPP	U.S. 48, Alaska, Hawaii
UPS Worldwide Express®	EXP	U.S. 48, Alaska, Hawaii
UPS Worldwide Saver®	EXS	U.S. 48, Alaska, Hawaii
UPS Worldwide Expedited®	XPD	U.S. 48, Alaska, Hawaii
UPS® Standard (to Canada/Mexico)	STD	U.S. 48

Canadian Domestic Services¶

Service	ID
UPS Express® Early	NDA_AM
UPS Express®	NDA
UPS Express Saver®	NDA_SVR
UPS Expedited®	2DA
UPS Standard®	STD

Canadian Services to the U.S. and Mexico¶

Service	ID
UPS Express® Early (to US Only)	XPP_USA
UPS Express®	EXP_USA
UPS Express Saver®	EXS_USA
UPS Expedited®	XPD_USA
UPS 3 Day Select® (to US Only)	3DA_USA
UPS Standard® (to US Only)	STD_USA

Canadian International Services¶

Service	ID
UPS Worldwide Express Plus®	XPP
UPS Worldwide Express®	EXP
UPS Worldwide Saver®	EXS
UPS Worldwide Expedited®	XPD

UPS Special Services¶

This section lists the available special services for a UPS shipment. For descriptions of special services see your UPS documentation. Shippers are responsible for understanding the special services they use and for adhering to requirements.

Set special services in the rates.specialServices array. Each object in the array takes a specialServiceId and, if required, inputParameters. The following example shows two special services, the second of which takes input parameters:

"specialServices": [
    {
        "specialServiceId": "ADULT_SIG"
    },
    {
        "specialServiceId": "INS",
        "inputParameters": [ {
            "name": "INPUT_VALUE",
            "value": "1000.00"
        } ]
    }
]

Special Service	ID	Example Input Parameters
Additional Handling	`ADD_HDL`
Adult Signature Required	`ADULT_SIG`
UPS carbon neutral	`CARBON`
Collect on Delivery (C.O.D.) - Cashier’s Check or Money Order	`COD_CASHIER`	Example: "inputParameters": [ { "name": "CURRENCY", "value": "USD" },{ "name": "INPUT_VALUE", "value": "10.00" } ] Supported values for `CURRENCY` name-value pair: `USD` and `CAD`
Collect on Delivery (C.O.D.) - Check	`COD_CHECK`	Example: "inputParameters": [ { "name": "CURRENCY", "value": "USD" },{ "name": "INPUT_VALUE", "value": "10.00" } ] Supported values for `CURRENCY`: `USD` and `CAD`
UPS Delivery Confirmation	`DEL_CON`
Direct Delivery Only	`DIRECT`
Dry Ice	`DRY_ICE`	Example: "inputParameters": [ { "name": "WEIGHT_UOM", "value": "OZS" },{ "name": "WEIGHT", "value": "10.00" } ]
Hold for Pickup	`HOLD`
Declared Value	`INS`	Example: "inputParameters": [ { "name": "INPUT_VALUE", "value": "20.00" } ]
UPS Print Return Label	`PRL`	Example: "inputParameters": [ { "name": "RETURN_PKG_DESCRIPTION", "value": "books" } ]
Saturday Delivery	`SAT_DELIVERY`
Shipper Release	`SHP_RELEASE`
Signature Required	`SIG`

UPS Parcels¶

The following are the supported UPS parcel types.

Parcel Type	ID	Services Supporting the Parcel Type
UPS Express Envelope	LTR	All U.S. domestic services except 3DA & GRD. All U.S. intl services except XPD & STD. All Canadian domestic services except STD. All Canadian intl services except XPD_USA, 3DA_USA, STD_USA, XPD.
UPS Express Pak	PACK	All U.S. domestic services except 3DA & GRD. All U.S. intl services except STD. All Canadian domestic services except STD. All Canadian intl services except 3DA_USA, STD_USA.
UPS Express Tube	TUBE	All U.S. domestic services except 3DA & GRD. All U.S. intl services except STD. All Canadian domestic services except STD. All Canadian intl services except 3DA_USA, STD_USA.
UPS Express Box Small	SMALL_EXP_BOX	All U.S. domestic services except 3DA & GRD. All U.S. intl services except STD. All Canadian domestic services except STD. All Canadian intl services except XPD_USA, 3DA_USA, STD_USA, XPD.
UPS Express Box Medium	MED_EXP_BOX	All U.S. domestic services except 3DA & GRD. All U.S. intl services except STD. All Canadian domestic services except STD. All Canadian intl services except XPD_USA, 3DA_USA, STD_USA, XPD.
UPS Express Box Large	LG_EXP_BOX	All U.S. domestic services except 3DA & GRD. All U.S. intl services except STD. All Canadian domestic services except STD. All Canadian intl services except XPD_USA, 3DA_USA, STD_USA, XPD.
Customer Package	PKG	All services.
UPS 25 KG Box®	25KG	U.S. international services XPP, EXP, EXS.
UPS 10 KG Box®	10KG	U.S. international services XPP, EXP, EXS.

UPS Labels¶

Label Considerations¶

Label size values use an uppercase X. Do not use a lowercase x.
Labels retrieved through URLs are available for 24 hours after creation.
In addition to the label, the API might return one or both of the following documents, depending on the shipment’s value and destination:
- UPS Control Log: An 8X11 document returned for shipments with a declared value of $1,000.00 or more. The control log includes a section the merchant hands to UPS and a section the merchant keeps. Declaring the value is optional. To declare a value, use the INS special service.
- Commercial Invoice: An 8X11 document returned for shipments to Puerto Rico and to international destinations. The commercial invoice includes three copies. The commercial invoice is not returned for shipments that use UPS Express Envelope (LTR).
For shipments with a declared value above $1,000.00, only the PDF file format is available. Declaring the value is optional.
For the PDF file format, if the shipment contains multiple forms, the PDF contains all the forms.
For the GIF file format with the URL content type, shipments to Puerto Rico and to international destinations return two objects in the documents array. The first is the label. The second is the customs paperwork, which prints as a PDF.

Label Options¶

Note

Please read the Label Considerations above before printing a label.

Label Size
(size)

File Format
(fileFormat)

Content Type
(contentType)

Puerto Rico & International Destinations

Declared value can exceed $1,000

DOC_4X6

PDF

GIF

ZPL2

URL

BASE64

No

Yes 1

No

Yes

No

DOC_8X11

PDF

URL

Yes

1: Two objects are returned in the documents array. The first is the label (GIF), and the second is the customs paperwork (PDF).

Samples¶

In this section

Sample UPS Label
Sample UPS Control Log
Sample UPS Invoice

Sample UPS Label¶

Sample UPS Control Log¶

Shipments with a declared value of $1,000.00 or more generate a UPS Control Log. The control log contains a section to hand to UPS and a section the merchant keeps. Declared value is set using the INS special service.

Sample UPS Invoice¶

Shipments that require customs paperwork generate a UPS invoice.

UPS Surcharges¶

The following surcharges can apply to UPS shipments. Surcharges are returned in the rates.surcharges array.

Surcharge or Fee	API CODE
Delivery Area Surcharge	DELIVERY_AREA
Extended Area Pickup Surcharge	EXT_AREA_PU
Extended Area Surcharge	EXTENDED_AREA
Fuel Surcharge	FUEL
Large Package Surcharge	LARGE_PACKAGE
Peak Season Surcharge	PEAK_SURCHARGE
Peak Season Surcharge - Additional Handling	PEAK_ADD_HDL
Peak Season Surcharge - Large Package	PEAK_LG_PKG
Residential Surcharge	RESIDENTIAL

Trademark Notice¶

Use of the following trademarks by Pitney Bowes has been granted by permission of the owners: