United Parcel Service (UPS)

Note

This feature is available in the Sandbox environment.

On this page

Overview

The PB Complete 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 Label

Sample UPS Control Log

Sample UPS Control Log