1. Home
Log a Case

UPS Implementation Guide

Introduction

Globally certified UPS Ready and UPS CTP 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.

Preferences

To setup a UPS preference you need to know your account number and the shipping/billing addresses linked to that account.
In case a US address is used as the billing address, please make sure to only include the first 5 digits of the ZIP code.
Please make sure to match the casing on the invoice as UPS addresses are case sensitive.

Unless it's a brand new account, you will need to also enter the details you can find on your latest invoice (ideally within the last 2 weeks). UPS sends you a new invoice every Saturday so please use that to make sure you don't hit any errors.

Your invoice should look similar to the below

You will need to enter the details into the preference section you see here:

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
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
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:

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

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

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:

Saturday Delivery

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

Deliver Without Signature

When this box is checked UPS will deliver without obtaining a signature. 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

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.

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

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".

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:

  • 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 objects.
  • 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 that needs to uploaded 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 Preference Salesforce ID that was used for this shipment.

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

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

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 ContactPhoneQ ValueTransportation 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:

Where can I find the codes for UPS Dangerous Goods/Hazardous Materials?

Refer to the UPS HazMat table.

Label Formats

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

Description Values
EPL
  • 4X6
  • 4X8
ZPL
  • 4X6
  • 4X8
SPL
  • 4X6
  • 4X8
PDF
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.

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.

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.

Is it important to use the correct weight in the wizard?

UPS automatically corrects the weight (if it is higher compared to what the customer provided) based on the operational scanning for Real Weight & Dim Weight. No extra fee for an individual correction, but in the US there is a bundled fee if the number of corrections for a single customer exceed a certain limit.

I'm shipping to individuals. Do I need to add a Company in the Shipment Wizard?

For UPS 'Company' is a required field. If you're shipping to individuals then this field can be used as "attention to" (e.g. recipient name).

Can I cancel a shipment with multiple packages?

Yes. All you need to do is cancel the master tracking number which is related to the first package, and it will cancel the whole shipment and all related packages.

I accidentally entered the incorrect address. Does UPS validate the address when creating the shipment?

UPS has an Address validation functionality, however this is only available for US and Puerto Rico addresses. If you accidentally create a shipment with the wrong country or ZIP code then you need to delete that shipment and recreate it, or contact UPS to update the address.

What is Simple Rate?

UPS Simple Rate offers U.S. domestic nationwide (Domestic shipments between all 50 states including Alaska and Hawaii) flat rate shipping up to 50 lbs. Rates are based on package size and delivery speed. Supported with the following services: UPS Ground, UPS 3 Day Select, UPS 2ndDay Air and UPS Next Day Air Saver.

Does Zenkraft support UPS Smart Pickups?

Yes, but the pickup still needs to be scheduled in our app. Smart Pickup is an account setting that enables the account to have same-day pickup if the Pickup API request falls within the allowed notify time. The benefit of Smart Pickup is that the client gets charged a weekly fee rather than per pickup like they would if it was on-call.

Can I automate carrier pickups?

It is possible to set up automated carrier pickups from any custom or standard object. You can find more information and detailed steps in our Automated Pickups guide.

Can I adjust the delivery address (UPS Package Intercept)?

Customers wanting to change the delivery address need to go through UPS customer support as there is no way to do that via the UPS APIs.

Can DAT be used for IncoTerms with International Shipments?

DAT was changed to DPU- Delivery at Place Unloaded or DAP – Delivery At Place. DAT can be used only for UPS Freight.

Does UPS send SMS messages?

UPS will automatically send out a Pre-Alert SMS notification on the day before the planned delivery. This SMS will be sent to the phone number that is provided in the consignee details.
While this does not depend on the UPS service such as Standard, there are some business rules in place that affect this service:

  • Consignee can receive max 2 SMS/day
  • For 1 day time in transit (TiT) shipments, the SMS will be sent after the manifest is transmitted to UPS
  • For more than 1 day TiT shipments, the SMS will be sent when the estimated delivery date is confirmed & calculated, this happens when the package is effectively picked up and enters the UPS origin center
  • If the manifest information we receive contains both email and SMS, then first an email is sent to the consignee. Only if the email is not opened will an SMS be sent out
  • In case the consignee opens email, they will not get any SMS!
  • Based on the SMS/email the consignee can redirect a shipment to a UPS Access Point
  • Redirects can be requested up to when a package is out for delivery

Why do my labels shows 'Address Line 2' above 'Address Line 1'?

Address formatting does not print the same for Ground as it does for Mail Innovations. The UPS label format displays as follows. The only time we use "USPS" format on the address label is when we interact with the USPS (such as SurePost or Mail Innovations).

Ground Mail Innovations
CONTACT
PHONE
COMPANY (OR NAME)
ADDRESS 3
ADDRESS 2
ADDRESS 1
CITY, STATE, ZIP
CONTACT NAME
COMPANY NAME
STREET ADDRESS
ADDRESS LINE 2
CITY, STATE, ZIP
COUNTRY

Can I automatically include our invoice number or PO number in the shipment record?

To have your invoice number automatically appear in the Billing and References Information section of the Shipment Wizard, and later on the Shipment record, you'll need to map the following fields on the Custom Address Source.

  • UPS: First Reference Type - with a static value of IK for Invoice Number and PO for PO number
  • UPS: First Reference Value - with the field containing the invoice number mapped

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.

Back to Top