UPS Carrier Guide

United Parcel Service, Inc. (UPS) is the world's largest domestic and international package delivery company and a fully integrated partner with ShipEngine.

In addition to domestic and international services, ShipEngine accounts in the United States can also leverage UPS Mail Innovations® consolidation services via ShipEngine, if available to your UPS account.

This guide provides developers with the details necessary to connect and use a UPS account with ShipEngine.

Connect Your Account

ShipEngine API allows you to connect your UPS accounts programmatically without logging in to the ShipEngine API dashboard. This is useful if you have wrapped a custom UI around the ShipEngine API toolset and want to add or disconnect existing carrier accounts without exposing your end users to the API dashboard.

These APIs can be used in parallel with the ShipEngine Partner APIs to programmatically create new ShipEngine users, and then connect existing UPS accounts all via the API without logging into a dashboard. Together these APIs empower you to completely white-label the ShipEngine experience for your end users.

Continue below for instructions on how to programmatically connect UPS using the ShipEngine API.

For instructions on connecting UPS via the ShipEngine dashboard, go to our UPS help article.

UPS Account Information Model

Example POST Call

POST /v1/connections/carriers/UPS

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
11
POST /v1/connections/carriers/ups HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"nickname": "My UPS account",
"account_number": "123456789",
"account_postal_code": "10001",
"account_country_code": "US"
}

Example Response

You will receive a 302 response with a Location header. You must redirect your user to the URL from this header, which will land on a UPS sign-in screen.

1
"Location": "https://authbridge.auctane.com/authflow/ups/shipengine/initiate?callbackUrl=https..."

We advise redirecting your user to this location URL in a pop-up window. When the user has signed in, they will land on a page that will direct them to close the window. At this point, your application should make a List Carrier call to retrieve the new list of connected carrier accounts.

If your UPS account was connected prior to June 3, 2024 you will need to reconnect it so that it can establish a connection with UPS' oauth API. Reconnection can take place in the ShipEngine dashboard, or via API. The contract for reconnection is identical to the contract for connection. Using Reconnect will allow you to keep the same carrier_id.

Example Reconnect Call

PUT /v1/connections/carriers/UPS/::carrier_id

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
11
PUT /v1/connections/carriers/ups/se-12345 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"nickname": "My UPS account",
"account_number": "123456789",
"account_postal_code": "10001",
"account_country_code": "US"
}

Additional UPS Account Settings

ShipEngine takes advantage of some of UPS's advanced functionality but does not enable it by default. These settings can be updated in the Dashboard or via the API.

UPS Service Details

The following domestic and international shipping services are available from UPS. For most services, the max weight is 150 lbs and the max combined length and girth (2Wx2H) is 165" (419cm).

Domestic Services

International Services

Package Types

Additionally, for U.S.-based accounts that use UPS SurePost® and UPS Mail Innovations®, UPS has 10 predefined package types for use with these services:

Return Services

Return services are not supported for this carrier.

Although UPS Mail Innovations® does offer a return service option, we do not currently support it in ShipEngine.

If you attempt to create a return label using UPS Mail Innovations®, you will see an "Object reference not set to an instance of an object" error message.

Adding Shipment Insurance

UPS supports adding insurance to your shipments. Review the Parcel Insurance page for details on adding shipment insurance with ShipEngine.

A few notes about adding insurance to UPS shipments:

Advanced Options

UPS supports the following advanced options:

To ensure you always have the most up-to-date information, use the List Carrier Advanced Options call.