United Parcel Service (UPS)¶

Overview¶

The PB Shipping 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.

This page describes how to register a merchant’s existing UPS account with the Shipping APIs; lists the API operations to use when shipping with UPS; and lists the supported services, special services, parcel types, and label options.

Onboard a Merchant to Print UPS Labels¶

To print UPS labels through the Pitney Bowes Shipping 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://www.ups.com/pitneybowes.
The merchant must register the UPS account for use with the PB Shipping APIs, as described in Carrier Account Registration.

API Operations for Shipping with UPS¶

The PB Shipping APIs integrate with UPS through the following operations:

Operation	Method	Endpoint
Register an Existing Carrier Account	POST	/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier}
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}
Get Tracking Information	GET	/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier=UPS
Accounts APIs	——	See the Accounts APIs table on the Merchant Accounts page.

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`
Verbal Confirmation of Delivery	`VERBAL`	Example: "inputParameters": [ { "name": "VERBAL_CONF_PHONE", "value": "5054597878" } ] The `value` field must be set to a 10 digit phone number.

UPS Surcharges¶

The following surcharges can apply to UPS shipments.

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

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¶

Please read the following before printing a UPS label:

Label size values use an upper-case X, as shown in the table below. A lower-case x will result in an error.
The URL to retrieve a label is available for 24 hours after the label is created.
The DOC_4X6 label size can be used only for domestic shipments with a declared value below $1,000.00. Declaring the value is optional. To declare a value, use the INS special service.
Shipments with the DOC_8X11 label size return the label and any related forms as a link to a PDF. If a label contains multiple forms, the PDF contains all the forms.
Shipments with a declared value of $1,000.00 or more require the DOC_8X11 label size. The shipments generate a UPS Control Log in addition to the label. Both the control log and label are 8X11. The control log includes a section the merchant hands to UPS and a section the merchant keeps.
With the exception of shipments using UPS Express Envelope (LTR), shipments to Puerto Rico and international destinations require the DOC_8X11 label size. The shipments generate a commercial invoice in addition to the label. The invoice includes three copies. Both the commercial invoice and the label are 8X11.

The following table describes the options for each label size.

Label Options¶
Label Size (size)	File Format (fileFormat)	Content Type (contentType)	Destination
DOC_4X6	PDF	URL	U.S. [1]
DOC_8X11	PDF	URL	U.S. Puerto Rico, International

[1]	Declared value must be less than $1,000.

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.