USPS (Legacy) - United States Postal Service Integration
USPS integration for domestic and international shipping from USA
The USPS (Legacy) module integrates with United States Postal Service to automatically calculate shipping rates based on weight and address, create shipping labels for orders, generate return labels for customers, and track shipments via USPS system.
This is the legacy version. USPS recommends installing the new "United States Postal Service (USPS) Shipping" module and removing this module as soon as possible.
Important Warning
This is the legacy version. USPS recommends installing the new "United States Postal Service (USPS) Shipping" module and removing this module as soon as possible.
Key Features
Key points
• Automatic shipping rate calculation based on weight and address
• Create shipping labels for orders
• Generate return labels for customers
• Track shipments via USPS system
• Cancel shipments when needed
• Support First Class (max 4 pounds), Priority (unlimited), Express (unlimited)
• Support domestic and international shipping
Requirements
Key points
• USPS Web Tools account (User ID)
• Company address must be in United States
• Company phone must be US number (10 digits)
• Valid ZIP code (format 12345 or 12345-6789)
USPS Service Types
USPS Services
| Service | Description | Weight Limit |
|---|---|---|
| First Class | Economy - Cost-effective | Max 4 pounds |
| Priority | Balanced - Standard | Unlimited |
| Express | Fast - Fastest | Unlimited |
EN/VI Terminology Reference
| Fields | Trường dữ liệu | Description |
|---|---|---|
| USPS User ID | ID người dùng USPS | USPS Web Tools account ID |
| Account Validated | Đã xác thực tài khoản | Account validated by USPS |
| USPS Service | Dịch vụ USPS | First Class, Priority, Express |
| Delivery Nature | Tính chất giao hàng | Domestic or International |
| Content Type | Loại nội dung | Merchandise, Documents, Gift, Sample, Return |
| Label Format | Định dạng nhãn | PDF or TIF |
| First Class | Hạng nhất | Economy service |
| Priority | Mức độ ưu tiên | Balanced service |
| Express | Tốc hành | Fastest service |
| Domestic | Nội địa | Within USA |
| International | Quốc tế | Outside USA |
| Flat Rate Box | Khung giá cho thùng hàng | Fixed rate box |
| Flat Rate Envelope | Khung giá cho đóng gói | Fixed rate envelope |
Configure USPS Shipping Method
Detailed configuration steps:
Steps
1. Go to Inventory → Configuration → Delivery → Shipping Methods
2. Click New
3. Fill information: Shipping Method (name), Provider (USPS Legacy), Company
4. USPS Configuration tab - Account info: USPS User ID, Account Validated (check if validated)
5. Configure service: USPS Service (First Class/Priority/Express), Delivery Nature (Domestic/International)
6. Content Type: Merchandise, Documents, Gift, Sample, Return (goods type)
7. Configure container (Domestic): Type of container (Regular/Rectangular/Non-rectangular), Type of USPS domestic regular container
8. Configure container (International): USPS Mail Type, Type of USPS International regular container
9. Custom dimensions: Package Width, Length, Height, Girth (if needed)
10. Options: Label Format (PDF/TIF), Machinable, Return Label on Delivery, Non delivery option
Calculate Shipping Rates
Rate calculation process from Sale Order:
Key points
• Requirements: Complete company address (street, city, state, ZIP, country US), complete customer address, all products have weight > 0, ZIP code in correct format
Steps
1. Create or open sales order
2. Fill completely: Customer with valid delivery address, products with configured weight
3. Click Add Shipping
4. Select USPS method
5. Click Get Rate to fetch price from USPS
6. System displays shipping fee (auto-converted from USD)
7. Click Add to add fee to order
Create Shipping Label
Label creation process:
Key points
• Label information: Barcode, sender/receiver address, tracking number, service type, weight
• Download label: Open picking → Chatter → Find message "Shipment created into USPS" → Click attachment file (PDF or TIF)
Steps
1. Go to Inventory → Operations → Transfers
2. Open picking to create label (status Ready or Done)
3. Ensure: Carrier = USPS, valid delivery address, weight updated
4. Click Send to Shipper (or Validate if not validated)
5. System calls USPS API and creates label
6. Label attached to picking chatter
7. Tracking Number updated automatically
Create Return Label
Two ways to create return labels:
Key points
• Automatic: Enable Return Label on Delivery in configuration, return label auto-created when creating shipping label
• Manual: Open delivered picking → Click Return → Create new return picking with Operation Type = Returns, reverse addresses
• Note: Only supports Domestic, cannot create return label for International
• Sender and receiver addresses reversed, return fee may differ from shipping fee
Track Shipment
Tracking number and USPS tracking:
Key points
• View tracking: Tracking Reference (carrier_tracking_ref) field on picking, number format 9400111899562941234567
• Track online: Click Tracking or visit https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=[TRACKING_NUMBER]
• Status updates: USPS does not auto-update to Odoo, need manual check or webhook/API integration
Cancel Shipment
Conditions and cancellation process:
Key points
• Conditions: USPS account must be validated (Account Validated = True), shipment not yet processed by USPS (usually within 24 hours), valid tracking number
• Process: Open picking to cancel → Click Cancel Shipment → System calls USPS API
• If successful: Tracking number removed, carrier price reset to 0, message "Shipment #[NUMBER] has been cancelled"
• If failed: Check account validated, contact USPS to cancel manually, create new label if need to resend
Common Error Handling
Errors and Solutions
| Error | Cause | Solution |
|---|---|---|
| Address of company missing or wrong | Company address incomplete | Settings → Companies → Update Info: Street, City, State, ZIP, Country (US), Phone (10 digits) |
| Please enter a valid ZIP code | ZIP wrong format | Use 12345 or 12345-6789, check on USPS.com |
| Recipient address cannot be found | Address does not exist | Verify with customer, use USPS validation tool |
| Weight is missing | Product has no weight | Inventory → Products → Fill Weight > 0 |
| Maximum weight 4 pounds | First Class limited to 4 pounds | Switch to Priority or Express, or split order |
| USPS Domestic for USA only | Using Domestic for international address | Change Delivery Nature to International |
| USPS International for outside USA | Using International for US address | Change Delivery Nature to Domestic |
| USPS Server Not Found | Cannot connect to API | Check internet, firewall, retry later |
| Service cannot deliver this package | Service not available | Choose different service (Express/Priority/First Class) |
Practical Tips
Key points
• Cost optimization: First Class for packages < 4 pounds (most economical), Priority balances price/speed (suitable for most), Express only when urgent (highest price)
• Data preparation: Always update product weight, validate customer address when entering, use standard company address
• Label management: Print label immediately after creation, store tracking number, pre-create return labels for easily returned products (clothing, shoes)
• Handle issues: Check XML log if errors occur (enable Log XML in carrier), contact USPS support for unclear API errors, consider switching to new USPS module
• Integration: Auto-create label when validating picking (needs customization), auto-send tracking email, integrate portal for customer self-print return labels