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 onboarding a merchant to ship with UPS; lists the API operations to use when shipping with UPS; and lists the supported services, parcel types, and labels when shipping with UPS.


Onboard a Merchant to Print UPS Labels

To print UPS labels through the Pitney Bowes Shipping APIs:


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 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 Control Log