UPS Shipping (REST)¶

Overview¶

The UPS Shipping (REST) module integrates Odoo 18 with the UPS REST API for direct label generation, rate calculation, shipment tracking, and shipment cancellation. It replaces the legacy UPS XML/SOAP integration with the modern OAuth 2.0-based REST API.

Key capabilities:

Rate Estimation -- Get real-time shipping rates on sale orders with negotiated rate support.
Label Generation -- Generate shipping labels in PDF, ZPL, EPL, or SPL format directly from delivery orders.
Return Labels -- Automatically generate return labels alongside outbound shipments.
Shipment Cancellation -- Void shipments directly from Odoo.
Value-Added Services -- Saturday delivery, Collect on Delivery (COD), Bill My Account, declared value insurance, and duty payment options.


Module	`lh_ups`
Version	18.0.1.0.0
Category	Inventory / Delivery
License	LGPL-3
Author	Longhorn Web Solutions

Installation & Dependencies¶

Odoo Module Dependencies¶

Module	Purpose
`stock_delivery`	Delivery carrier and shipping integration framework
`mail`	Chatter for shipment notifications and label attachments

Python Dependencies¶

Package	Purpose
`requests`	HTTP client for UPS REST API calls
`Pillow` (PIL)	Image processing for GIF-to-PDF label conversion

Installation Steps¶

Copy the lh_ups folder into your Odoo custom addons directory.
Navigate to Settings > Apps > Update Apps List.
Search for UPS Shipping (REST) and click Install.

UPS REST API Configuration¶

Prerequisites¶

Before configuring the module, you need a UPS account and API credentials:

Create a UPS account at ups.com and note your Account Number.
Register as a developer at developer.ups.com using the same UPS account.
Create an application in the UPS Developer portal:
- Set the callback URL to your Odoo instance URL (e.g., https://yourcompany.odoo.com).
- Add the following API products: Authorization, Address Validation, Locator, Paperless Documents, Shipping, and Rating.
- Accept the terms and save.
Open your newly created app and copy the Client ID and Client Secret.

Creating a UPS Delivery Method¶

Navigate to Inventory > Configuration > Delivery Methods.
Click New and set Provider to UPS.
Fill in the UPS Configuration tab:

Field	Description
UPS Account Number	Your UPS shipper account number
UPS Client ID	OAuth 2.0 Client ID from the UPS Developer portal
UPS Client Secret	OAuth 2.0 Client Secret from the UPS Developer portal
UPS Service Type	The default shipping service (see table below)
UPS Package Type	The default package type for shipments
Package Weight Unit	Pounds (LBS) or Kilograms (KGS)
Package Size Unit	Inches (IN) or Centimeters (CM)
Label Format	PDF (GIF), ZPL, EPL, or SPL

Available Service Types¶

Code	Service
03	UPS Ground
11	UPS Standard
01	UPS Next Day Air
14	UPS Next Day Air Early
13	UPS Next Day Air Saver
02	UPS 2nd Day Air
59	UPS 2nd Day Air AM
12	UPS 3-Day Select
65	UPS Saver
07	UPS Worldwide Express
08	UPS Worldwide Expedited
54	UPS Worldwide Express Plus
96	UPS Worldwide Express Freight

API Environments¶

Environment	Base URL
Test	`https://wwwcie.ups.com`
Production	`https://onlinetools.ups.com`

Toggle between environments using the Test Mode checkbox on the delivery method. Use test mode during initial setup to validate your configuration without generating real shipments.

OAuth 2.0 Authentication¶

The module handles OAuth token management automatically:

On the first API call, the module authenticates with your Client ID and Client Secret.
An access token is obtained and stored on the delivery carrier record.
If a request returns a 401 (expired token), the module automatically refreshes the token and retries.

Label Generation¶

Generating Shipping Labels¶

Confirm a sale order with a UPS delivery method.
Open the associated delivery order (stock picking).
Click Validate to process the shipment and generate the label.

The module:

Validates required address fields on the shipper, warehouse, and recipient.
Builds the shipment payload with package details, weights, and dimensions.
Sends the request to the UPS Shipping API (/api/shipments/v1/ship).
Downloads and converts the label (GIF labels are auto-converted to PDF).
Attaches the label to the picking's chatter with tracking numbers.

Label Formats¶

Format	Description
GIF (PDF)	GIF images auto-converted to PDF for standard printers
ZPL	Zebra Programming Language for thermal label printers
EPL	Eltron Programming Language for thermal printers
SPL	Sato Printer Language for Sato thermal printers

Thermal Printer Labels

If you use ZPL, EPL, or SPL format, individual label files are attached per package. For GIF/PDF format, all package labels are merged into a single PDF attachment.

Multi-Package Shipments¶

When a delivery order contains multiple packages (result_package_id on move lines), the module generates a label for each package. Tracking numbers are concatenated with a + separator.

Commercial Invoices¶

For international shipments, the module automatically generates a commercial invoice when required. The invoice is attached as a separate PDF alongside the shipping labels. Invoice generation is triggered when the shipment crosses international borders and includes:

Product descriptions, quantities, and values
Harmonized System (HS) codes from product records
Country of origin
Terms of shipment (Incoterms)

Rate Estimation¶

Getting Rates on Sale Orders¶

When a UPS delivery method is assigned to a sale order, the module calculates real-time shipping rates:

Open a sale order and set the delivery method to UPS.
Click Get Rate or add the delivery line.
The module sends a rate request to the UPS Rating API (/api/rating/v1/Rate).
The returned rate is displayed, with automatic currency conversion if needed.

Negotiated Rates¶

The module requests negotiated rates by default. If your UPS account qualifies for negotiated (discounted) pricing, those rates are returned instead of published rates. The NegotiatedRatesIndicator flag is included in all rate and ship requests.

Weight Validation¶

Products must have a weight set for accurate rate calculation. The module raises an error if:

Any non-service, non-delivery product on the order has a zero weight.
Any move line on the picking has a zero weight and no package weight.

Shipment Tracking¶

Tracking Links¶

After label generation, tracking numbers are stored on the delivery order. Click the tracking link to open the UPS tracking page:

http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums={tracking_number}

Multi-Package Tracking¶

For shipments with multiple packages, tracking numbers are separated by +. Each package has its own tracking number viewable through the UPS tracking portal.

Return Labels¶

Automatic Return Labels¶

Enable Return Label on Delivery on the delivery method to automatically generate a return label alongside each outbound shipment.

When enabled:

The outbound label is generated first.
A return label is generated with reversed ship-from and ship-to addresses.
Both labels are attached to the picking's chatter.
If the return label fails, the outbound shipment is automatically voided to prevent orphaned shipments.

Portal Return Labels¶

Enable Get Return Label from Portal to allow customers to request return labels through the customer portal.

Value-Added Services¶

Bill My Account¶

Enable Bill My Account on the delivery method to allow customers to provide their own UPS account number for billing. When enabled:

Customers are prompted to enter their UPS account number on the sale order.
Shipping charges are billed to the customer's UPS account.
The delivery line amount shows as $0.00 on the sale order.
The UPS account number is stored as a company-dependent property on the customer's partner record.

Collect on Delivery (COD)¶

Enable Collect on Delivery to have UPS collect payment from the recipient upon delivery:

Option	Description
COD Funding Option	"Check, Cashier's Check or Money Order" or "Cashier's Check or Money Order" only

COD Availability

COD is not available for UPS Worldwide Express Freight (service code 96).

Saturday Delivery¶

Enable Saturday Delivery to allow weekend delivery for eligible services. This option is only available for services that support Saturday delivery (e.g., Next Day Air, 2nd Day Air).

Shipping Insurance¶

The module supports declared value (shipping insurance) through the standard Odoo shipping_insurance percentage field on the delivery carrier. The declared value is set per package based on the product costs.

Duty Payment¶

Configure who pays customs duties for international shipments:

Option	Description
Sender	Your company pays duties
Recipient	The customer pays duties upon delivery

Shipment Cancellation¶

Voiding a Shipment¶

Open the delivery order with an active UPS shipment.
Click Cancel Shipment.
The module calls the UPS Void API (/api/shipments/v1/void/cancel/{tracking_number}).
The tracking reference and carrier price are cleared from the picking.

Package Types¶

Configuring Package Types¶

The module adds ups_rest as a carrier type for Odoo package types (stock.package.type). Configure your UPS-compatible packages at Inventory > Configuration > Package Types:

Create or edit a package type.
Set Carrier to UPS.
Define dimensions (length, width, height) and weight constraints.

The default custom package code is 02 (Customer Supplied Package). Standard UPS package codes are also supported through the packaging type code field.

Address Requirements¶

UPS has strict address validation requirements. The module checks the following before any API call:

Shipper (Company) Address¶

Street address (street or street2)
City
Country
Phone (minimum 10 digits)
State (required for US, CA, IE)
ZIP code (required for all countries except HK)

Warehouse (Ship From) Address¶

Same requirements as the shipper address.

Recipient (Ship To) Address¶

Street address (street or street2, max 35 characters each)
City
Country
Phone (minimum 10 digits -- checked on partner or sale order partner)
State (required for US, CA, IE)
ZIP code (required for all countries except HK)

Address Line Length

UPS limits address lines to 35 characters. If either street line exceeds this limit, the module returns an error. Split long addresses across the two street fields to stay within limits.

Troubleshooting¶

Authentication Errors¶

Invalid Authentication Information

Symptom: "Invalid Authentication Information" error when generating labels.

Resolution:

Verify your Client ID and Client Secret match the values in the UPS Developer portal.
Ensure your UPS app has the required API products enabled (Authorization, Shipping, Rating).
Check that your UPS account is active and in good standing.
If using test mode, ensure you are pointing to the correct test environment.

Missing Weight Errors¶

Weight of product is missing

Symptom: "The estimated price cannot be computed because the weight of your product is missing."

Resolution:

Set a weight on all products in the order at Sales > Products > [Product] > Inventory tab > Weight.
For packaged shipments, ensure each package has a positive Shipping Weight.

Phone Number Errors¶

Phone must be at least 10 alphanumeric characters

Symptom: Phone validation error for shipper, warehouse, or recipient.

Resolution:

Ensure phone numbers contain at least 10 digits (non-numeric characters are stripped before validation).
Check the company partner, warehouse partner, and delivery address for valid phone numbers.

Rate Discrepancies¶

Rate does not match expected amount

Symptom: Rates in Odoo differ from rates shown on ups.com.

Resolution:

Confirm you are using the correct Service Type and Package Type.
Verify package dimensions and weights match what UPS would calculate.
Check if your account has negotiated rates -- these are used automatically when available.
Ensure the correct Weight Unit (LBS vs KGS) and Dimension Unit (IN vs CM) are configured.

XML Logging¶

Enable Log XML on the delivery method to log all UPS API requests and responses. This is invaluable for diagnosing issues with specific shipments. Review logs at Settings > Technical > Logging.