UPS

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

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

This guide provides developers with the details necessary to build the UPS shipping capabilities from your own UPS account into your ShipStation API workflows.

If you are using or plan to use the UPS services included with ShipStation API, rather than connecting your own UPS account, see our UPS from ShipStation guide.

Requirements

Connect Account

You can connect a UPS account using the POST method to the /v1/connections/carriers/ endpoint, or via the ShipStation API Dashboard.

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

Connect via Endpoint

carrier_name: ups

POST /v1/connections/carriers/:carrier_name

Sample request:

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.

Reconnecting a UPS Account

In some cases, you may need to reconnect a UPS account to ShipStation API. Reconnection can take place in the ShipStation API dashboard or via API. Using the Reconnect method will allow you to keep the same carrier_id and connection contract.

The following scenarios will require you to reconnect your UPS account to ShipStation API:

Example Reconnect Call

PUT /v1/connections/carriers/:carrier_name/: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"
}

Modify Carrier Settings

ShipStation API takes advantage of some of UPS's advanced functionality but does not enable it by default. If you need to modify the properties of your UPS account connection or enable some of the carrier's advanced functionality not enabled by default, you can update these settings in your ShipStation API account dashboard or via API using the PUT method with the /v1/connections/carriers/ endpoint.

Additional Properties

Sample update request:

PUT /v1/connections/carriers/:carrier_name/:carrier_id/settings

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
11
PUT /v1/connections/carriers/ups/se-108252/settings HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "nickname": "my very cool UPS account",
  "pickup_type": "daily_pickup",
  "is_primary_account": "true",
  "use_negotiated_rates": "true"
}

A successful request will receive an HTTP status 204 response.

Rates

UPS supports sending estimated rates (including your contracted negotiated rates) to ShipStation API.

Service Details

Available UPS services are provided below. Please note that carriers may update their available services at any time. To ensure you are always using valid services, you can use the list carrier services endpoint at any time.

For most services, the max weight is 150 lbs and the max combined length and girth (2Wx2H) is 165" (419cm).

Domestic Services

Ground Saver Services

On April 2nd, 2025, UPS replaced SurePost services with UPS Ground Saver®. This domestic service is available to US-based accounts and has a delivery time of Ground+1 day. While the name of the service has been updated, the Service Codes you use in your requests remain the same.

International Services

Mail Innovations Services

US-based accounts that have Mail Innovations service enabled, also have access to these services:

To configure your account for shipping with Mail Innovations services, you will need to modify your UPS carrier settings and update the following UPS-specific properties:

Shipping from Great Britain to Northern Ireland

As of 1st May 2025, UPS will support all movement types (B2B, B2C, C2C, and C2B) for shipping from Great Britain (GB) to Northern Ireland (NI), as related to the Windsor Framework.

Let UPS know in advance if your goods are considered 'at risk' of moving through Northern Ireland to be sold in the EU. To learn when goods can be considered as ‘not at risk’, see the page UK Government Guidance page Moving goods you bring into Northern Ireland as 'not at risk’ of moving to the EU.

Shippers must send an email to ​[email protected]​ for UPS to add instructions to their UPS UK shipping account number, along with UKIMS approval number & XI Duty Deferment number, when applicable. They must also enter their B2B NI customer’s XI EORI number with the shipping data in the ​Destination Tax ID​​ field, if they know it.

NI Importers, and if required, some GB shippers, will need to be authorised under the new ​UK Internal Market Scheme (UKIMS)​​ to avoid EU duties. Merchants may want to consider signing up for the ​UK Government's [Trader Support Service​​}(https://www.gov.uk/guidance/trader-support-service).

Windsor Framework Parameters​

Data Expectations

NOTE: Clear goods descriptions, values, and commodity codes are required for all movement types.

*Please specify each item in the shipment with its commodity code, weight, and a concise description, eg. "Ladies woven 100% cotton blouse”, “Men’s leather shoes” or "iPhone" instead of a general one.

• Incorrect: Nuts
• Correct: 26 hexagonal aluminum bicycle nuts
• Incorrect: T-Shirts
• Correct: 15 men's T-Shirts, Size L, 100% Cotton

B2B parcels with UKIMS authorisation:

B2B parcels without UKIMS authorisation:

B2B/B2C/C2B parcels

TIP: You may find it helpful to see the Products Object section of our International Shipping page.

Additional Considerations for Validation

Return Services

UPS supports returns for all domestic services except for SuerPost and Mail Innovations®.

Although UPS Mail Innovations® does offer a return service option, we do not currently support it in ShipStation API. 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.

Packages

UPS has 10 predefined package types for use with MI services:

Adding Shipment Insurance

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

A few notes about adding insurance to UPS shipments:

Label Support

Label Reference Fields

UPS supports adding custom label messages. UPS labels include two reference fields, each with a 35-character max length. If the text in a reference field exceeds 35 characters, the text will be truncated on the label.

Multi-Package Labels

UPS supports ulti-package shipping for most service classes. The maximum number of labels for a multi-package shipment is 20.

UPS returns individual labels per package for multi-package shipments (one main label file and then individual files in the response).

Label Branding

UPS supports label branding.

Voiding Labels

You can void a UPS label using ShipStation API up to 24 hours after label creation. If you need to void a label after the 24-hour period has passed, you may still be able to do so using your UPS account portal.

Paperless Labels

For UPS, ShipStation API only supports creating paperless labels for the UPS Mail Innovations Returns service: mail_innovations_return. For all other UPS services, the paperless label feature is not available at this time.

Customs Declarations

Most UPS accounts are configured to submit customs forms electronically via the UPS EDI system. Check with your UPS account representative if you are unsure if your account is EDI enabled.

If your account is not EDI enabled or you are shipping to a country that does not support electronic submission, you will need to include three copies of the printed commercial invoice (downloadable from the form_downloads object) in your international shipments. These can be in the box itself or in the plastic sleeve outside the box.

When the declared value of a shipment is $1k or higher, UPS will automatically return a high-value report to ShipStation API titled “UPS Control Log” which you can download from the form_downloads object. You must print two copies and retain one that is signed by the UPS employee who accepts the package. The signed report will serve as part of your documentation should the high-value shipment become lost or damaged.

Delivery Confirmation

UPS supports the following delivery confirmation options (options other than online may incur an additional fee from UPS).

See our Delivery Confirmation page for more details about using the confirmation property.

Shipping Alcohol

To ship alcohol with your UPS account, you must be authorized by UPS to do so and have it included in your UPS contract.

Additionally, you must:

Review UPS’s How To Ship Special-Care or Regulated Items page for details.

Advanced Options

UPS supports certain advanced options, which you can add to the shipment object when creating a shipment or label.

To ensure you always have the most up-to-date information about a carrier's advanced options, use the list carrier options call.

Manifests

UPS does not support creating printable manifests. All shipment data is submitted electronically to UPS at the time of label creation, so UPS will have the shipment data in their system.

Scheduling Pickups

UPS supports scheduling pickups using ShipStation API. Set the pickup_type property for your account settings to the option indicated by your UPS account representative.

UPS pickup times can vary depending on service and pickup location. Please contact your UPS account representative to get information specific to your account.

Service Points (PUDO)

UPS does not support shipping to service points.

Tracking

ShipStation API's integration with UPS supports receiving tracking updates. Review our ​Track a Package guides​​ for details on tracking with the ShipStation API.

Disconnecting Your UPS Account

See the Disconnect section in our Delete a Carrier page for the process of deleting or disconnecting a carrier from ShipStation API.