United Parcel Service (UPS)¶

On this page

Overview
Onboard a Merchant to use UPS
Shipping Operations
Services
Special Services
Parcel Types
Label Sizes and Formats
Surcharges
Sample UPS Label
Sample UPS Control Log

Overview¶

The PB Shipping APIs provide integration to UPS® shipping services. 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 for use with the PB Shipping APIs, lists the supported API operations, and lists supported services, parcel types, and label sizes.

Onboard a Merchant to use UPS¶

To register your merchant 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.
You must register the merchant’s UPS account for use with the PB Shipping APIs, as described in the Register Existing Carrier Accounts tutorial.

Shipping Operations¶

The following shipping operations can be used with UPS.

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	DELETE	/v1/shipments/{shipmentId}
Get Tracking Information	GET	/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier=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

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 specialServices array. The following example shows a special services array with the ADULT_SIG and INS special services.

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

Some special services take input parameters, as shown in the Input Parameters column in the table below.

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`
Delivery Area Surcharge	`DELIVERY_AREA`	Response only
Direct Delivery Only	`DIRECT`
Dry Ice	`DRY_ICE`	Example: "inputParameters": [ { "name":"WEIGHT_UOM", "value":"OZS" },{ "name":"WEIGHT", "value":"10.00" } ]
Extended Area Pickup Surcharge	`EXT_AREA_PU`	Response only
Extended Area Surcharge	`EXTENDED_AREA`	Response only
Fuel Surcharge	`FUEL`	Response only
Hold for Pickup	`HOLD`
Declared Value	`INS`	Example: "inputParameters": [ { "name":"INPUT_VALUE", "value":"20.00" } ]
Large Package Surcharge	`LARGE_PACKAGE`	Response only
Peak Season Surcharge	`PEAK_SURCHARGE`	Response only
Peak Season Surcharge - Additional Handling	`PEAK_ADD_HDL`	Response only
Peak Season Surcharge - Large Package	`PEAK_LG_PKG`	Response only
UPS Premium Care™	`PREMIUM_CARE`
UPS Print Return Label	`PRL`	Example: "inputParameters": [ { "name":"RETURN_PKG_DESCRIPTION", "value":"books" } ]
Residential Surcharge	`RESIDENTIAL`	Response only
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.

Parcel Types¶

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.

Label Sizes and Formats¶

Please read the following before Creating a UPS Shipment:

Set the label size in the documents.size field in the Create UPS Shipment request.
The label size values listed in the table below use an upper-case X. Using a lower-case x will result in an error.
The Create UPS Shipment request returns the label and any related forms as a link to a PDF. If a label contains multiple forms, the PDF contains all the forms.
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 a shipment’s value is optional. A shipment’s declared value is set using the INS special service.
Shipments with a declared value of $1,000.00 or more generate a UPS Control Log and require that you use the DOC_8X11 label size. Both the control log and shipment 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 generate a commercial invoice and require the DOC_8X11 label size. Both the commercial invoice and the shipment label are 8X11. The invoice includes three copies.

Label Sizes¶

Label Size

File Format

Content Type

Destination

DOC_4X6

PDF

URL

U.S. 48, Alaska, Hawaii

Declared value must be less than $1,000.

DOC_8X11

PDF

URL

U.S. 48, Alaska, Hawaii,
Puerto Rico,
International

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
UPS Premium Care™	PREMIUM_CARE

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.