Troubleshooting & FAQ
Here you will find solutions for common problems with the UPS Connector as well as general questions.
Connection Problems
"OAuth2 token request failed" / Authentication Errors
| Possible Cause | Solution |
|---|---|
| Client ID or Client Secret incorrect | Check your credentials in the UPS Developer Portal |
| Sandbox/production URL swapped | Make sure Sandbox Mode is set correctly |
| Token expired and not automatically renewed | Click Test Connection in the setup |
| UPS account deactivated or locked | Contact UPS support |
OAuth 2.0 Token Expiry
The UPS Connector automatically obtains a new token when the old one has expired (~4 hours validity). If errors still occur, check the Client Credentials.
"Test Connection" Fails
Step-by-step diagnostics:
- Check Client ID: Is the Client ID correctly copied from the UPS Developer Portal?
- Check Client Secret: Was the secret entered correctly? (Displayed as
***) - Check Account Number: Is the 6-character UPS customer number correct?
- Check Sandbox Mode: Sandbox only for tests, production for real shipments
- Internet connection: Can the BC server reach the UPS URLs?
- Sandbox:
https://wwwcie.ups.com - Production:
https://onlinetools.ups.com
- Sandbox:
- Firewall/Proxy: Are the UPS URLs allowed in the firewall?
Label Creation
"Missing weight for package" / Weight Errors
| Cause | Solution |
|---|---|
| Weight not specified | Enter the weight in the package (required field) |
| Weight = 0 | Specify at least 0.1 kg (100 g) |
Weight Format
UPS expects the weight in kilograms with the unit KGS. The connector translates the input automatically.
"Missing dimensions" / Dimension Errors
Package dimensions (length, width, height) are optional for UPS. However, if you specify dimensions, all three values (L×W×H) must be filled in.
"Invalid service for destination" / Wrong Service
Not all UPS services are available for all destination countries:
| Service | Area of Use |
|---|---|
| 11 - Standard | Europe only |
| 65 - Express Saver | Europe only |
| 07 - Express | Worldwide |
| 54 - Express Plus | Worldwide (selected destinations) |
| 08 - Expedited | Worldwide |
| 70 - Access Point | Only with Access Point network |
| 96 - Express Freight | Worldwide |
Solution: Select a service that is available for the destination country. For international shipments outside Europe, Express (07) or Expedited (08) are recommended.
"Label creation failed" / General API Error
- Check the recipient address for completeness (name, street, postal code, city, country)
- Check whether the shipper address in the setup is correct
- Check the UPS Account Number
- Verify the weight (min. 0.1 kg)
- Review the BC error message — the UPS API usually provides a specific error text
International Shipments
"Missing customs items for international shipment"
| Cause | Solution |
|---|---|
| No customs items created | Create at least one Customs Item position |
| Destination country is non-EU | Customs data is required for non-EU countries |
See: International Shipments for a complete guide.
"Invalid HS Code" / Invalid Customs Tariff Number
- HS codes must have at least 6 digits (e.g.,
844332) - For the EU, 8–10 digits are recommended (e.g.,
84433291) - Check the code at zolltarifnummern.de
Customs Declaration Missing for Shipments to the United Kingdom
Since Brexit, GB is a non-EU country. The connector checks this automatically — make sure that all Customs Items and customs data (Invoice No., Date, Incoterm) are filled in.
Cancellation & Void
"Void failed — shipment already in transit"
Shipments can only be cancelled before UPS has picked up the package. Once the package has been scanned, cancellation is no longer possible.
Alternative: Contact UPS customer service directly for a package recall.
"Shipment not found for void"
- Check whether the tracking number is correct
- Shipments in the sandbox cannot be voided with the production endpoint (and vice versa)
- Very old shipments (>90 days) may no longer be voidable via the API
Sandbox vs. Production
How Do I Switch from Sandbox to Production?
- Open the UPS Setup page
- Disable the Sandbox Mode toggle
- The URLs are automatically switched:
- Sandbox:
https://wwwcie.ups.com - Production:
https://onlinetools.ups.com
- Sandbox:
- Click Test Connection to verify the connection
Credentials Note
The Client ID and Client Secret are typically the same for sandbox and production. However, the UPS Account Number must be your real customer account.
Sandbox Labels Don't Work for Shipping
This is normal — sandbox labels have no valid tracking numbers and are not processed by UPS. They are only for testing the API integration.
Label Format Issues
Label Is Not Displayed Correctly
| Format | Description | Usage |
|---|---|---|
| GIF | Image file | Standard for PC printers |
| PNG | Image file (higher quality) | Recommended for PC printers |
| ZPL | Zebra Programming Language | Zebra thermal printers only |
| EPL | Eltron Programming Language | Older thermal printers |
| SPL | Sato Printer Language | Sato thermal printers |
Solution: Select the format in the setup that matches your printer. For regular PC printers, use PNG or GIF.
Label Is Too Small / Too Large
Check the Label Size in the setup:
| Size | Usage |
|---|---|
| 4×6 inches | Standard for shipping label printers |
| 4×8 inches | Larger format for more information |
Performance & Job Queue
Label Creation Takes Too Long
- Check the internet connection of the BC server
- UPS API response times can vary depending on load
- For bulk shipments: Create labels sequentially (one after another) to avoid rate limits
Job Queue Entries with Errors
- Open Job Queue Entries in Business Central
- Filter for UPS-related entries
- Check the error message in the error log
- Set the status to Ready to re-execute the entry
General FAQ
What type of UPS contract do I need?
You need a UPS business customer contract with API access. Contact your UPS representative or register at developer.ups.com.
Can I use multiple UPS accounts?
Currently, the connector supports one UPS account per Business Central company. The Account Number is stored centrally in the setup.
Are tracking numbers automatically reported back?
Yes, the tracking number is automatically saved in the Shipment Label after label creation and reported back to the merchantCENTRAL Hub.
Does the connector support multi-parcel shipments?
Yes! You can create multiple packages per shipment. Each package receives its own tracking number. All packages of a shipment are grouped under a common shipment number.
How much does using the UPS API cost?
The UPS API itself is free of charge. You only pay the regular UPS shipping costs according to your contract.
Can I change the label format after the fact?
The format (GIF/PNG/ZPL/EPL/SPL) is set when the label is created. To get a different format, you must cancel the label and create a new one.
What is the difference between UPS Express and DHL Express?
Both are international express shipping services. The merchantCENTRAL Hub is shipping provider-independent — you can set up UPS or DHL (or both) as Shipment Providers as needed.
Support
If you cannot resolve a problem:
- Check Activity Log: Open the merchantCENTRAL Activity Log and filter by
UPS - UPS error message: The API usually returns a specific English error message — search for it in the UPS Developer Documentation
- Contact your administrator: For setup changes or credential issues
- UPS Support: For account-related questions or service availability