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:
- 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 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}?carrier={carrier}&cancelInitiator=SHIPPER |
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 |
Collect on Delivery (C.O.D.) - Check | COD_CHECK |
Example: "inputParameters": [ {
"name": "CURRENCY",
"value": "USD"
},{
"name": "INPUT_VALUE",
"value": "10.00"
} ]
Supported values for |
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 |
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 Canadian domestic services except STD.
|
UPS Express Pak | PACK | All U.S. domestic services except 3DA & GRD.
All Canadian domestic services except STD.
|
UPS Express Tube | TUBE | All U.S. domestic services except 3DA & GRD.
All Canadian domestic services except STD.
|
UPS Express Box Small | SMALL_EXP_BOX | All U.S. domestic services except 3DA & GRD.
All Canadian domestic services except STD.
|
UPS Express Box Medium | MED_EXP_BOX | All U.S. domestic services except 3DA & GRD.
All Canadian domestic services except STD.
|
UPS Express Box Large | LG_EXP_BOX | All U.S. domestic services except 3DA & GRD.
All Canadian domestic services except STD.
|
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 theINS
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 theDOC_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 Size (size) |
File Format (fileFormat) |
Content Type (contentType) |
Destination |
---|---|---|---|
DOC_4X6 | URL | U.S. [1] | |
DOC_8X11 | URL | U.S.
Puerto Rico, International |
[1] | Declared value must be less than $1,000. |
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.
