United Parcel Service (UPS)

Overview

The Global Ecommerce 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.


Onboard a Merchant to Print UPS Labels

To print UPS labels through the APIs:


API Operations for Shipping with UPS

The APIs integrate with UPS through the following operations:

Operation


Method

Resource Path


Add Carrier Account

POST

/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier=UPS

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=UPS&cancelInitiator=SHIPPER

Get Tracking Information

GET

/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber

Merchant Accounts APIs

——

See API Operations for Merchant Accounts.


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


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

Label Considerations

  • Label size values use an uppercase X. Do not use a lowercase x.

  • Labels retrieved through URLs are available for 24 hours after creation.

  • In addition to the label, the API might return one or both of the following documents, depending on the shipment’s value and destination:

    • UPS Control Log: An 8X11 document returned for shipments with a declared value of $1,000.00 or more. The control log includes a section the merchant hands to UPS and a section the merchant keeps. Declaring the value is optional. To declare a value, use the INS special service.

    • Commercial Invoice: An 8X11 document returned for shipments to Puerto Rico and to international destinations. The commercial invoice includes three copies. The commercial invoice is not returned for shipments that use UPS Express Envelope (LTR).

  • For shipments with a declared value above $1,000.00, only the PDF file format is available. Declaring the value is optional.

  • For the PDF file format, if the shipment contains multiple forms, the PDF contains all the forms.

  • For the GIF file format with the URL content type, shipments to Puerto Rico and to international destinations return two objects in the documents array. The first is the label. The second is the customs paperwork, which prints as a PDF.

Label Options

Note

Please read the Label Considerations above before printing a label.

Label Size
(size)


File Format
(fileFormat)

Content Type
(contentType)

Puerto Rico & International Destinations

Declared value can exceed $1,000


DOC_4X6

PDF


GIF
GIF
ZPL2

URL


URL
BASE64
BASE64

No


Yes 1
No
No

Yes


No
No
No

DOC_8X11

PDF

URL

Yes

Yes

1

Two objects are returned in the documents array. The first is the label (GIF), and the second is the customs paperwork (PDF).


Samples

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


Sample UPS Invoice

Shipments that require customs paperwork generate a UPS invoice.

Sample UPS invoice


UPS Surcharges

The following surcharges can apply to UPS shipments. Surcharges are returned in the rates.surcharges array.

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

Trademark Notice

Use of the following trademarks by Pitney Bowes has been granted by permission of the owners:

UPS, the UPS Shield trademark, the UPS Ready mark, the UPS Developer Kit mark, and the Color Brown are trademarks of United Parcel Service of America, Inc. All Rights Reserved.