Introduction

Globally certified UPS Ready and UPS Digital Connections provider. Supports 200+ origin countries, paperless commercial invoice, parcel, freight and virtually every special service. Further integrations include UPS Mail Innovations, UPS Access Point and Hazardous Materials.

From 3 June 2024 please use the new UPS REST integration.

Migration

From 3 June 2024 UPS decommissioned their XML API and customers are required to migrate to the new REST API. For common questions and issues please see our UPS Migration FAQ page.

Preferences

Service Types

Service Types	Value	Description
UPS Ground	UPS_GROUND	Delivery in one to five days
UPS Ground Freight Pricing	UPS_GROUND_FREIGHT_PRICING	An economical choice for multiple-package shipments weighing more than 150 pounds
UPS 3 Day Select®	UPS_THREE_DAY_SELECT	Day-definite option for less time-sensitive shipments
UPS Next Day Air®	UPS_NEXT_DAY_AIR	Ideal service for shipments that must arrive the next business day
UPS Next Day Air Saver	UPS_NEXT_DAY_AIR_SAVER	Next business day afternoon delivery
UPS Next Day Air Early AM	UPS_NEXT_DAY_AIR_EARLY_AM	Next business day overnight delivery available as early as 8:00 A.M. to most major cities in the U.S. or by 9:30 A.M. to most other cities
UPS 2nd Day Air	UPS_SECOND_DAY_AIR	Economical two-day delivery option for shipments that do not need overnight service
UPS 2nd Day Air AM	UPS_SECOND_DAY_AIR_AM	Delivery by 10:30 A.M. or 12:00 P.M. of the second business day to most commercial destinations in the U.S.
UPS Standard	UPS_STANDARD	Day-specific economical delivery option, door-to-door service.
UPS Worldwide Express	UPS_WORLDWIDE_EXPRESS	Send packages to 140 countries and territories with time-definite service and in-house customs clearance
UPS Worldwide Express Plus	UPS_WORLDWIDE_EXPRESS_PLUS	Send packages to more than 55 countries and territories with door-to-door service with in-house customs clearance
UPS Today Standard	UPS_TODAY_STANDARD	Ideal for shipments that must get there before the end of the day, with door-to-door service
UPS Today Dedicated Courier	UPS_TODAY_DEDICATED_COURIER	Dedicated courier offers door-to-door or board-to-board transport service, ideal for extremely urgent shipments
UPS Today Express	UPS_TODAY_EXPRESS	Ideal for shipments that must get there immediately
UPS Today Express Saver	UPS_TODAY_EXPRESS_SAVER	Ideal for shipments that must get there the same morning or afternoon
UPS Express	UPS_EXPRESS	Delivery to most business areas within the UK by 10:30 am the next day
UPS Express Plus	UPS_EXPRESS_PLUS	Ideal when your shipment must be there for the start of the business day
UPS Express Early AM	UPS_EXPRESS_EARLY_AM	Early business day delivery
UPS Expedited	UPS_EXPEDITED	Day-definite delivery and door-to-door service with in-house customs clearance included
UPS Worldwide Expedited	UPS_WORLDWIDE_EXPEDITED	Day-definite expedited delivery and door-to-door service with in-house customs clearance included
UPS Express Saver	UPS_SAVER	An economic alternative to the Express service available in Europe.
UPS Worldwide Saver	UPS_WORLDWIDE_SAVER	Next business day delivery to Canada, second business day delivery to Mexico, day-definite delivery by the end of the business day to other locations worldwide
UPS Economy	UPS_ECONOMY	Economical delivery, created especially for lightweight products
UPS Basic	UPS_BASIC	UPS_BASIC
UPS Express NA1	UPS_EXPRESS_NA1	Export to the United States, Canada, Mexico and many destinations in Central and South America
UPS Intercity Today	UPS_INTERCITY_TODAY
UPS First Class Mail	UPS_FIRST_CLASS_MAIL
UPS Priority Mail	UPS_PRIORITY_MAIL
UPS Expedited Mail Innovations	UPS_EXPEDITED_MAIL_INNOVATIONS
UPS Priority Mail Innovations	UPS_PRIORITY_MAIL_INNOVATIONS
UPS Economy Mail Innovations	UPS_ECONOMY_MAIL_INNOVATIONS
UPS Surepost Less Than 1LB	UPS_SUREPOST_LESS_THAN_1_LB
UPS Surepost 1LB or Greater	UPS_SUREPOST_1_LB_OR_GREATER
UPS Surepost BPM	UPS_SUREPOST_BPM
UPS Surepost Media	UPS_SUREPOST_MEDIA

Packaging Types

Packaging Types	Value
UPS Your Packaging	UPS_YOUR_PACKAGING
Your Packaging	your_packaging
UPS Tube	UPS_TUBE
UPS Pak	UPS_PAK
UPS Pallet	UPS_PALLET
UPS 10kg Box	UPS_10KG_BOX
UPS 25kg Box	UPS_25KG_BOX
UPS Small Express Box	UPS_SMALL_EXPRESS_BOX
UPS Medium Express Box	UPS_MEDIUM_EXPRESS_BOX
UPS Large Express Box	UPS_LARGE_EXPRESS_BOX
UPS Express Box	UPS_EXPRESS_BOX
UPS Flats	UPS_FLATS
UPS Letter	UPS_LETTER
UPS Parcels	UPS_PARCELS
UPS BPM	UPS_BPM
UPS First Class	UPS_FIRST_CLASS
UPS Priority	UPS_PRIORITY
UPS Machinables	UPS_MACHINABLES
UPS Irregulars	UPS_IRREGULARS
UPS Parcel Post	UPS_PARCEL_POST
UPS BPM Parcel	UPS_BPM_PARCEL
UPS Media Mail	UPS_MEDIA_MAIL
UPS BPM Flat	UPS_BPM_FLAT
UPS Standard Flat	UPS_STANDARD_FLAT

Reference Types

It is possible to add up to two references to your shipping label. These can be either shipment level or package level references.
For shipment level references you can either set these manually in the Shipment Wizard under Billing and Reference Information, or you can default them from the Custom Address Source under Specific Carrier Settings using UPS: First Reference Type and UPS: Second Reference Type. While you can add the values you'd like to display to UPS: First Reference Value and UPS: Second Reference Value.

Reference Type	Value
AJ	Accounts Receivable Customer Account
AT	Appropriation Number
BM	Bill of Lading Number
9V	Collect on Delivery (COD) Number
ON	Dealer Order Number
DP	Department Number
3Q	Food and Drug Administration (FDA) Product Code
IK	Invoice Number
MK	Manifest Key Number
MJ	Model Number
PM	Part Number
PC	Production Code
PO	Purchase Order Number
RN	Reference Number
RQ	Purchase Request Number
RZ	Return Authorization Number
SA	Salesperson Number
SE	Serial Number
ST	Store Number
TN	Transaction Reference Number

Barcode Reference

If you are using the Shipment level references it is possible to turn the first reference into a barcode on the shipping label.

You can do this in the Shipment Wizard by ticking the Reference 1 Barcoded on Label option:

Or map it from the Custom Address Source:

Note: In order to barcode a reference number, its value must be no longer than 14 alphanumeric characters or 24 numeric characters and cannot contain spaces.

Here is an example of a label with the additional barcoded reference:

UPS Third Reference

From v1.106.1 it is possible to use a third, package level reference with your shipment. This won't actually appear on the label but will be submitted to UPS. Third references are especially useful for billing.

However, please bear in mind that if the first or second reference fields are empty, the third reference will automatically move onto their position and will be displayed on the label.

You can add the third reference in the Shipment Wizard in the Packages Section:

Or you can map this from the Custom Address Source:

Special Services

These are special services offered by the carrier which can be selected either during the Shipment creation, or can be defaulted in the Custom Address Source. In this section you can find the most commonly used services.

Shipment Delivery Confirmation/Package Delivery Confirmation

When this box is checked a confirmation signature will be required upon delivery. Shipment Delivery Confirmation is generally available for international shipments, while Package Delivery Confirmation is used for US domestic shipments.

The following static different values can be defaulted in the Custom Address Source either under the Packages section or under Carrier Specific Fields:

• SIGNATURE_REQUIRED: UPS will obtain the recipient's signature and provide you with a printed copy. You may also view the recipient's signature online.
• ADULT_SIGNATURE_REQUIRED: UPS will obtain the adult* recipient's signature and provide you with a printed copy. You may also view the adult recipient's signature online.
  *Adult recipients must have reached the legal age of adulthood in the receiving country. Higher age limits may apply where the legal age of adulthood is less than 21 years of age.

Package Delivery Confirmation under the Packages section:

Shipment Delivery Confirmation under Carrier Specific Fields:

Deliver Without Signature

When this box is checked UPS will deliver without obtaining a signature. The checkbox requires a TRUE value.

Direct Delivery Only

Direct Delivery Only ensures that a package is delivered to the residential or commercial address you provide. This service stops recipients from redirecting packages and prevents our drivers from rerouting deliveries when recipients are not at home, that includes UPS Access Points.

This option is not available for all countries and destinations. If the option is there you can select it in the shipping wizard:

Or add it in the custom address source:

Saturday Delivery

UPS offers the convenience of Saturday Delivery. The checkbox requires a TRUE value.

Dangerous Goods Signatory

The Dangerous Goods Signatory and the Haz Mat checkboxes need to be ticked and the necessary fields completed. As the signatory field is a text field, the values can be set as needed.
The Signatory needs to have dangerous goods training, so we advise to contact UPS for more information.

To default a certain hazardous material the UPS Hazmat fields need to be set under Packages. If there is only one hazardous material, then it is enough to only fill the UPS: Hazmat First and UPS: Hazmat First Quantity fields.

To find the Hazmat Object ID open the HazMat record object as shown below and copy the ID from the record URL.

Dry Ice

For dry ice delivery the below information needs to be provided. These can be defaulted in the Custom Address Source by using Child Objects under the Packaging section.

• Dry Ice checkbox
• Dry ice weight
• Regulation type: CFR for ground shipments - ATA for air shipments
• Medical use checkbox

Package Collect on Delivery (COD)

UPS will attempt to collect the amount shown on the C.O.D. tag or package label, and then send the payment to the sender. If UPS cannot collect the payment after three attempts, the package will be returned.

• Collect on delivery (COD): checkbox that requires a TRUE value
• Collect on delivery (COD) Amount: requires a static number value
• Collect on delivery (COD) Cashiers Check or Money Order Only: checkbox that requires a TRUE value

UPS Simple Rate

With UPS® Simple Rate, you pick from the five flat packaging rates and the four shipping speeds. Ship anywhere in the U.S. for a predictable rate.

UPS Proactive Response

UPS Proactive Response offers a sophisticated monitoring engine and dedicated logistics experts who continuously observe your critical shipments and take action when needed.
Note: Available from v1.115

International Shipping

In this section you'll find the required or recommended fields and settings for international shipments.

Mandatory fields for Customs items

• Description
• Quantity
• Quantity Unit
• Weight
• Unit price
• Country
• Unit of measure
• Harmonised Code

If there is Electronic Export Information (EEI), then include the schedule B number, schedule B unit and export type.

You can map the Quantity Unit and Unit fo Measure fields in the custom address source.

You need to add the following field mappings. We'll include the most common quantity units and unit of measures here.

• UPS: Quantity Units - Piece (PC), Each (EA), Quantity Not Required (X)
• UPS: Unit of Measurement - Bag (Bag), Box (Box), Each (Each), Piece (Piece), Other (Other)

Description of Goods

A short, general description of goods of what is being sent needs to be included in this field.

Package Contents

Package contents can either be Documents or Commodities. To automate the selection you need to add UPS: Package Contents under Specific Carrier Fields with one of the following API values:

• DOCUMENTS_ONLY
• NON_DOCUMENTS

EEI/AES filing

For international shipments from the US over $2500 in value an AES citation needs to be submitted. UPS does this on your behalf, no need to do anything when shipping with UPS.

EORI Numbers

Businesses and people wishing to trade must use the EORI number as an identification number in all customs procedures when exchanging information with Customs administrations. The EORI number should be entered in additional comments section of Invoice. If needed for a label the EORI number should be entered as the 1st or 2nd Package Level Reference.

Commercial Invoice

To be able to generate a commercial invoice first you need to set up a commercial invoice template then either add it within the wizard or map it from the Custom Address Source.

When you create a template make sure to fill the following details:

• Description - internal use only
• Terms of Sale - this is a static value, for different terms please create separate templates
• Invoice date - this can be overwritten from the CAS
  

Other configuration options for the commercial invoice include:

• Ship to Tax ID
• From Tax ID
• Freight Charges
• Comments
• Declaration Statement

Commercial Invoice Terms of Sale

The following terms are supported via the UPS API:

• CFR: Cost and Freight
• CIF: Cost Insurance and Freight
• CIP: Carriage and Insurance Paid
• CPT: Carriage Paid To
• DAF: Delivered at Frontier
• DDP: Delivery Duty Paid
• DDU: Delivery Duty Unpaid
• DEQ: Delivered Ex Quay
• DES: Delivered Ex Ship
• EXW: Ex Works
• FAS: Free Alongside Ship

Commercial Invoice Sold To Fields

It is possible to override the default information in the Sold To section of the commercial invoice.

Paperless invoice

By default, if paperless invoicing is supported, the invoice will be electronically transmitted to UPS.
UPS accounts need to be enabled to use paperless invoice. Please discuss this with your UPS account manager before implementing the solution. Returns: paperless is not available for international returns. Exception to this if you have a special (paid) agreement with UPS to set up paperless upload document service. This usually takes 3-4 weeks.

Upload Documents

UPS allows uploading documents such as your own documents to attach to the UPS shipment. Documents can include things such as commercial invoice or certificates of origin . Zenkraft offer this functionality via an invocable method called "Upload ETD".

NOTE: Please check with UPS beforehand if your account is authorized to use this functionality.

Once your shipment has been created, you can then utilize the invocable method via a process builder to upload your documents.

The documents need to be stored on your original object, so for example if you are shipping from an Order object, you need to store the files that you would like to upload on the Order object under the Notes and Attachments or the Files related list.

Below is an example of the process builder that you can set up. In this example the process runs after the shipment is created and we are getting the necessary IDs via field reference.

• Salesforce Object Id - specify the salesforce ID of the object that holds the files to be uploaded
• Attachment Or File - specify File or Attachment, depending on how you store your documents
• SoQL Condition - specify the criteria to choose the files to upload. You might have a situation where you store other files but only want to upload the PDF documents. An example value you could use is : FileType= 'PDF'
• Tracking Number - please specify the tracking number of the shipment the document is connected to
• Custom Address Source Id - please specify the custom address source Salesforce id that was used to create this shipment
• Preference ID - please specify the shipping preference Salesforce ID that was used for this shipment
• Save documents to shipment record (optional) - you can copy or move the uploaded documents to be stored on the shipment

Error Handling

From v1.113 onwards it is possible to map and error handler field in the custom address source to display any error message provided by the carrier in the API response.

Returns

It is possible to create a Custom Address Source specifically for returns. (If you need help setting up a Custom Address Source please use this guide.) In the Custom Address Source the Shipment Type should be set to Return.

Under Specific Carrier Fields you can set the UPS: Return Type and UPS: Return Description fields. If you plan to automatically email the return labels then use the Print Return Label return type.

Return Type	Value
Electronic Return Label	8
Print Return Label	9
Print and Mail Return Label	2
Return Service 1 Attempt	3
Return Service 3 Attempts	5

UPS codes on the shipping label

There are many different services codes that can appear on the return label, like KEY, KEY-RS, etc, as well as service description, like RETURN SERVICE - PAYMENT GUARANTEED.
These are automatically added by UPS based on certain criteria, eg. destination, service type. For accurate information on these codes we recommend reaching out to your UPS account manager.

For more information on the various return services please visit the UPS Return Services page.

QR code returns

QR code returns are available with our UPS (Zenkraft API) integration.

Email Notifications

UPS provides notification emails for every tracking step. In the Shipping Preference you can decide when you want your customers or yourself to receive these notification, if at all.

Open your UPS shipping preference and scroll down to the Email Notifications section.

• Email Message Default - you can type here the message you'd like your customers to see
• Send Email Notification to Shipper - if this checkbox is checked, you, or the person whose email address is added to the sender details, will be notified at the checkpoints selected below
• Send Email Notification to Recipient - if this checkbox is checked the person whose email address is added to the recipient details, will be notified at the checkpoints selected below
• Email Notify on Exception - the people selected above will receive a notification when the shipment is in Exception stage
• Email Notify on Delivery - the people selected above will receive a notification when the shipment is in Delivered stage

Sending your own notifications

You may want to send out your own email notifications or email the label to multiple parties. You can add additional notification recipients under Specific Carrier Fields in the Custom Address Source.

UPS Mail Innovations

UPS Mail Innovations works with the U.S. Postal Service, providing the pick-up, processing and interim transportation of mail.

Enable Mail Innovations and/or SurePost on your Preference

Go to your UPS sipping preference and enable "Include Mail Innovations Packaging Types" and "Include Sure Post Service Types".

Package and Service Matrix for Mail Innovations

NOTE: UPS SurePost does not support reference information.

Hazardous Materials

You can ship your Hazardous Materials (Haz Mat) with the Multi Carrier app by selecting your Haz Mat items via the Wizard screen. You have to make sure that your UPS account supports the Dangerous Goods/Hazardous Materials service otherwise you won't be able to create shipments. If you are unsure, please contact your UPS account manager.

For more information on setting up HazMat fields please check the Special Services section of this document.

Here is a guide for creating a Haz Mat shipment.

1. Create your Haz Mat item

Go To the DG/HazMat object.

Click New HazMat Details

Fill out all the details as you would normally for your Hazardous Materials shipments.

Click Save.

Next you must create the HazMat Commodity

Fill in the required sections:

Once you have your Commodity and Detail, you need to go back into your Detail objet and link the Commodity to it:

You have now added the necessary hazmat details and these will be available on the Wizard screen which we show in the next step below.

2. Add the Haz Mat item to the Wizard

Next go to the Shipping Wizard, fill in the recipient and package details and you will then see a new Special Service appear where you will be able to choose Haz Mat.

Select this checkbox and you will see the below fields, you can have up to 3 Haz Mat items in each package:

Using the magnifying glass you can choose the Haz Mat item(s) you created in the first part of this guide.

For each package you need to also specify the Emergency Contact, Phone, Q Value, Transportation Mode and whether the package is Over Packed or All Packaged in one.

If you are unsure of any details to put here, please contact your UPS Account manager so they can help you determine what you need to specify for your particular shipment.

Click Create Label, and you will have create a Haz Mat shipment.

You should see a shipping label that has dangerous goods terminology:

Label Formats

The available label formats can be usually grouped into two types: thermal and non-thermal labels.

Description	Values
EPL	Thermal 4x6 - EPL2 Thermal 4x8 - EPL2
ZPL	Thermal 4x6 - ZPL Thermal 4x8 - ZPL
PDF	Only if "Convert GIF to PDF" is enabled in the shipping preference
GIF

Label Acronyms

There are many acronyms that might appear on a UPS label depending on the services selected for a shipment.

• EDI - Paperless shipment where no paper invoice is required
• EDI-CC - Paperless International (World Ease) Global Consolidated Clearance
• EDI-DOC - Document shipment, paperless or non-paperless
• EDI-IDIDS - Paperless or Non-Paperless customer uploaded invoice and/or additional documents for shipment
• EDI-PULL - Paperless shipment where no paper invoice is required and the shipper intends UPS to pull other clearance related documents from the pouch and process at the origin
• INV - Non-document shipment where paper invoice is required and all information, including invoice line detail, is keyed. Pull the customs copy of the Commercial Invoice.
• INV-CC - Non-document GCC (World Ease) shipment that contains invoice line detail from the shipping system
• KEY - Non-document shipment where the paper invoice is required and the shipper did not capture invoice line detail or critical information is missing

Error Messages

In this section you can find the most common error messages, what they mean and how to solve them.

An Error Occured while parsing the response from UPS License Agreement

This error means that the application is unable to connect to the UPS system. Check if all UPS remote site settings are set to active under Setup > Remote Site Settings.
Once this is activated restart the preference creation process.

Invalid or missing product origin country code for product number 1

Please check that both the shipper and recipient countries are filled in correctly.

Request can not be authorized due to invoice not found in the UPS billing system.

This error usually occurs if the invoice used to set up the preference is too old.

Account can not be added to your profile due to exceeding the maximum number allowed

1. Call UPS Customer Service: 1-866-742-5877
2. Provide them with your USER ID (8000xxxxx) (not the 6 alphanumeric account #)
3. Ask them to add a new account (this account appears in the PAYMENT METHODS section of your account when logging into the UPS portal)
4. Create new Shipmate Preference with new account number

Unable to correctly obtain all available service types. Please add sender/recipient address information, select packaging type, and try again

This error usually occurs when there is an issue with the UPS API server.

The Shippers shipper number cannot be used for the shipment

This error usually occurs because there is a problem with your UPS account number. Please contact UPS and ask them if there is a block on the account.

There is a non-technical issue with your request, in order to resolve you will need to contact UPS customer service at 1-888-851-4901.

This error usually occurs when you try to create a new Shipping Preference. This is because some account numbers require extra validation. Please call this number, validate the account, then you will be able to create the preference.

The Commercial Invoice Discount value cannot be larger than the total value of all commodities. Please update the Commercial Invoice Record.

This error usually occurs if the discount value on the commercial invoice template is larger than the total value of all the products. Go to your commercial invoice template under Shipping Forms and update the discount value accordingly.

The country associated with Shipper's ShipperNumber must be the same as the shipment Shipper's country

This error usually occurs if the sender and recipient country or countries are different from the registered country of the shipping account. For example you are trying to ship from UK to IT using a US account. This is not possible with UPS, they require to use an account registered in either the shipper or the recipient country.

Common Questions

In this section you can find our most commonly asked questions regarding this carrier. If you have a question not listed here please contact us.

Can I show/hide negotiated rates?

If you have negotiated rates enabled with UPS then they will show automatically. However, it is possible to hide them.

Go to your UPS preference and lick edit. Scroll down and check Hide Negotiated Rates. Save your changes.

I am not getting a commercial invoice for Northern Ireland when shipping from the EU

Due to the current geopolitical situation (Brexit), although Northern Ireland is technically part of the UK, it is still considered to be in the EU. As EU-EU shipments are considered domestic, therefore no CI is generated for Northern Ireland.

Can I use my UPS Express Envelope with UPS Ground?

UPS Express Envelopes can be used only with UPS Next Day Air, UPS 2nd Day Air, and UPS Worldwide Express.

I am getting a Postcode related error message for my UPS Ireland account

You do not need to enter your postcode when adding a UPS Ireland account. You only need to use your street address, city, and country.

Can I use UPS Worldwide Economy?

Worldwide Economy is a low-cost international service for low weight eCommerce shipments. The service offers merchants s a low cost means of accessing international markets with lower value goods, increasing the opportunities for top line sales growth by opening up new countries for sales or by allowing merchants to expand the breadth of product which they offer to international customers. UPS Economy offers two shipping options, Economy DDP (delivery duties paid) and DDU (delivery duties unpaid). Not available in all countries.
Please contact your UPS account manager to enable this service for you account. Once it is enabled you will be able to use it within our application.

Is UPS Hundredweigth service available in Multi-Carrier?

If you have a Hundredweight contract then the discount will be automatically applied if:
-Total shipment billable weight of 100 pounds or more for UPS Next Day Air, UPS Next Day Air Saver, UPS 2nd Day Air A.M. or UPS 2nd Day Air shipment
-200 pounds or more for each UPS 3 Day Select or UPS Ground shipment

How many packages can I ship with UPS?

UPS has a limit of maximum 50 packages per shipment.

Can I create shipments using local alphabet?

Non-Roman characters set such as Arabic, Chinese, Cyrillic, Greek, Hebrew, Japanese, Korean, Tamil and Thai are NOT supported to return in the response.

Why am I getting duplicate checkpoints?

Please check the user's time zone. Differences between the org wide and the user time zones can cause duplicated tracking checkpoints.