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
In order to create a Preference for UPS REST in the Multi-carrier application please obtain the credentials below directly from the carrier. Typically this information is obtainable from your carrier account manager or your internal logistics team.
IMPORTANT: One ups.com profile can only be used once. So if you have multiple environments, ie
sandbox and production, it is recommended to use separate ups.com credentials. Otherwise once you go
live in production with the same credentials used in a sandbox that sandbox will break.
CampusShip credentials can NOT be used for oAuth. Please create a new ups.com profile.
How to Test
If you don't have your live credentials available during implementation phase, Zenkraft can provide test credentials. Click on the Use Test Account toggle and select the Test Account Country from the dropdown.
How to reauthenticate the account
If you start receiving authorization errors or just want to reauthenticate the account you can do that by going to the shipping preference, edit, and reauthenticate the account by clicking on the "Login to ups.com" button.
Service Types
| Service Types | Value | Description | |
|---|---|---|---|
| UPS Ground | ups_ground | - | Copy |
| UPS Next Day Air | ups_next_day_air | - | Copy |
| UPS Second Day Air | ups_second_day_air | - | Copy |
| UPS Express | ups_express | - | Copy |
| UPS Expedited | ups_expedited | - | Copy |
| UPS Standard | ups_standard | - | Copy |
| UPS Three-Day Select | ups_three_day_select | - | Copy |
| UPS Next Day Air Saver | ups_next_day_air_saver | - | Copy |
| UPS Next Day Air Early | ups_next_day_air_early | - | Copy |
| UPS Worldwide Economy DDU | ups_worldwide_economy_ddu | - | Copy |
| UPS Express Plus | ups_express_plus | - | Copy |
| UPS Second Day Air AM | ups_second_day_air_am | - | Copy |
| UPS Saver | ups_saver | - | Copy |
| UPS First Class Mail | ups_first_class_mail | - | Copy |
| UPS Priority Mail | ups_priority_mail | - | Copy |
| UPS Expedited MaiI Innovations | ups_expedited_mail_innovations | - | Copy |
| UPS Priority Mail Innovations | ups_priority_mail_innovations | - | Copy |
| UPS Economy Mail Innovations | ups_economy_mail_innovations | - | Copy |
| UPS MaiI Innovations (MI) Returns | ups_mail_innovations_returns | - | Copy |
| UPS Access Point Economy | ups_access_point_economy | - | Copy |
| UPS Worldwide Express Freight Midday | ups_worldwide_express_freight_midday | - | Copy |
| UPS Worldwide Economy DDP | ups_worldwide_economy_ddp | - | Copy |
| UPS Express 12:00 | ups_express_12_00 | - | Copy |
| UPS Heavy Goods | ups_heavy_goods | - | Copy |
| UPS Today Standard | ups_today_standard | - | Copy |
| UPS Today Dedicated Courier | ups_today_dedicated_courier | - | Copy |
| UPS Today Intercity | ups_today_intercity | - | Copy |
| UPS Today Express | ups_today_express | - | Copy |
| UPS Today Express Saver | ups_today_express_saver | - | Copy |
| UPS Worldwide Express Freight | ups_worldwide_express_freight | - | Copy |
| UPS Worldwide Express Freight | ups_worldwide_express_freight | - | Copy |
| UPS SurePost Less than 1LB | ups_surepost_lt_1lb | - | Copy |
| UPS SurePost | ups_surepost | - | Copy |
| UPS Print and Mail (PNM) | ups_print_and_mail_pnm | - | Copy |
| UPS Standard Flats | standard_flats | - | Copy |
| UPS Parcel Select Lightweight Irregular | parcel_select_lightweight_irreg | - | Copy |
| UPS Worldwide Express Plus | ups_worldwide_express_plus | - | Copy |
| UPS Worldwide Express | ups_worldwide_express | - | Copy |
| UPS Worldwide Saver | ups_worldwide_saver | - | Copy |
| UPS Economy Mail Innovations | ups_economic_mail_innovations | - | Copy |
| UPS Economy | ups_economy | - | Copy |
| UPS Basic | ups_basic | - | Copy |
| UPS Express NA1 | ups_express_na1 | - | Copy |
| UPS Next Day Air Early | ups_next_day_air_early_am | - | Copy |
| UPS Worldwide Expedited | ups_worldwide_expedited | - | Copy |
Packaging Types
| Packaging Types | Value | |
|---|---|---|
| Your Packaging | your_packaging | Copy |
| UPS Letter | letter | Copy |
| Tube | tube | Copy |
| PAK | pak | Copy |
| UPS Express Box | express_box | Copy |
| UPS 25KG Box | 25kg_box | Copy |
| UPS 10KG Box | 10kg_box | Copy |
| Pallet | pallet | Copy |
| Small Express Box | small_express_box | Copy |
| Medium Express Box | medium_express_box | Copy |
| Large Express Box | large_express_box | Copy |
| Flats | flats | Copy |
| Parcels | parcels | Copy |
| BPM | bpm | Copy |
| First Class | first_class | Copy |
| Priority | priority | Copy |
| Machinables | machinables | Copy |
| Irregulars | irregulars | Copy |
| Parcel Post | parcel_post | Copy |
| BPM Parcel | bpm_parcel | Copy |
| Media Mail | media_mail | Copy |
| BPM Flat | bpm_flat | Copy |
| Standard Flat | standard_flat | Copy |
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.
| Reference Types | Value | |
|---|---|---|
| Reference 1 | reference_1 | Copy |
| Reference 2 | reference_2 | Copy |
| Reference 3 | reference_3 | Copy |
| Accounts Receivable Customer Account | accounts_receivable_customer_account | Copy |
| Appropriation Number | appropriation_number | Copy |
| Bill of Lading Number | bill_of_lading_number | Copy |
| Collect on Delivery (COD) Number | collect_on_delivery_cod_number | Copy |
| Dealer Order Number | dealer_order_number | Copy |
| Department Number | department_number | Copy |
| Food and Drug Administration (FDA) Product Code | food_and_drug_administration_fda_product_code | Copy |
| Invoice Number | invoice_number | Copy |
| Manifest Key Number | manifest_key_number | Copy |
| Model Number | model_number | Copy |
| Part Number | part_number | Copy |
| Production Code | production_code | Copy |
| Purchase Order Number | purchase_order_number | Copy |
| Purchase Request Number | purchase_request_number | Copy |
| Return Authorization Number | return_authorization_number | Copy |
| Salesperson Number | salesperson_number | Copy |
| Serial Number | serial_number | Copy |
| Store Number | store_number | Copy |
| Transaction Reference Number | transaction_reference_number | Copy |
| Return Label | barcode | Copy |
Add barcoded reference
It is possible to barcode a reference on the shipping label. Once you selected the appropriate reference
mappings then you add UPS REST: Barcode Indicator under the specific carrier fields and set the
reference type as indicated in the above table.
NOTE: If you want to barcode the first package level reference the static value should be first_reference.
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.
NOTE: from v1.128.10 it is possible to configure the list of available special services in the wizard.
Saturday Delivery
UPS offers the convenience of Saturday Delivery. The checkbox requires a TRUE
value.
List Rates and Negotiated Rates
By default the carrier returns the negotiated rates, unless otherwise specified. The other options are List Rates (account specific non-discounted rates) or Retail Rates (otherwise known as published rates - this is the most expensive option).
Bill Recipient or Third-Party
You can bill the shipment charges to the recipient or a third party account.
For recipient you need to add the Billing Account and Billing Account Postal Code, for
third-party billing you also need the Billing Account Country.
The acceptable values for billing are: shipper, recipient, third_party.
International Shipping
In this section you'll find the required or recommended fields and settings for international shipments.
Mandatory fields for Customs items
- Description - character limit: 105
- Quantity
- Value
- Commodity Code
- Manufacture Country Code
- Weight
Duty Payment
Duty payment can be set to the following options:
- Sender - shipper
- Recipient - recipient
- Third-party - third_party
If recipient or third_party is selected then the below fields can be or need to be filled in:
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 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 flow 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.
File naming
UPS REST requires specific tags for the different document types. Please ensure the tags are included in the file name using the following format: [tag]filename. For example [t02]invoice.pdf for a commercial invoice.
Here are the possible options:
- t01 - Authorization form
- t02 - Commercial Invoice
- t03 - Certificate of Origin
- t04 - Export Accompanying Document
- t05 - Export License
- t06 - Import Permit
- t07 - One Time NAFTA
- t08 - Other Document
- t09 - Power of Attorney
- t10 - Packing List
- t11 - SED Document
- t12 - Shipper's Letter of Instruction
- t13 - Declaration
Flow setup
Below is an example of the flow 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 REST: Return Service Code. If you plan to automatically email the return labels then use the Print Return Label return type.
| Return Type | Value |
| Electronic Return Label | electronic_return_label |
| Print Return Label | print_return_label |
| Print and Mail Return Label | print_and_mail |
| Return Service Attempt | return_service_attempt |
QR code returns
It is possible to include a QR code on the shipping labels by using the Include QR special service.
To be able to use QR codes you will need the following credentials from UPS:
- Domain
- QR User ID
- QR Password
You can enter these credentials when creating the preference. If you need to update an existing preference please create a case and include the credentials and the Shipping ID (the number in the Account Number filed on the Preference).
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.
Your credentials were incorrect
This error might appear out of the blue. Unfortunately there is a known issue with corrupted refresh tokens, so for now the quickest solution is to reauthenticate the account as described in the Preferences section of this guide.
Missing or invalid shipper number
This error usually means that the UPS account number used for shipping is not associated to the ups.com
profile credentials used for authentication.
1. Log into ups.com
2. Click on your profile and select Accounts and Payment. (If the account is listed then please
reach out to UPS to verify any possible issues.)
3. Under Add Payment Method select Add Existing Account and click Add
4. Follow the instructions on the screen to add your account.
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 use three address lines when shipping?
From v1.131.18 it is possible to use three address lines if needed.
Can I authenticate my accounts using my UPS CampusShip profile?
No, UPS CampusShip users will need to register for a regular ups.com profile.
