UPS Initial Setup
This guide walks you step by step through the initial setup of the UPS Shipping Connector in Business Central. After completion, you can start creating UPS shipping labels right away.
Prerequisites
Before you begin, make sure you have the following:
- [x] UPS Business Account β An active account with UPS
- [x] UPS Developer Portal Account β Access at developer.ups.com
- [x] Client ID & Client Secret β Created in the UPS Developer Portal (OAuth 2.0 App)
- [x] Account Number β Your 6-character UPS Shipper Number
- [x] merchantCENTRAL Hub β The merchantCENTRAL Hub app must be installed
- [x] UPS Connector β The app "AD merchantCENTRAL Shipment UPS" must be installed
Sandbox vs. Production Access
UPS offers a sandbox environment for testing. Make sure to activate it first before working with real shipments! Sandbox credentials are created separately in the UPS Developer Portal.
Step 1: Set Up UPS Developer Portal
If you don't have access yet:
- Go to developer.ups.com
- Register with your UPS business account
- Create a new App:
- App Name: e.g.,
merchantCENTRAL BC - Callback URL: can be left empty (Client Credentials Flow)
- Products: Enable Shipping
- App Name: e.g.,
- After creation, you will receive:
- Client ID β e.g.,
A1B2C3D4E5F6G7H8I9J0 - Client Secret β e.g.,
K1L2M3N4O5P6...(only visible once!)
- Client ID β e.g.,
Save the Client Secret
The Client Secret is shown only once in the UPS Developer Portal. Copy it immediately and store it securely. If you lose it, you will need to create a new app.
Step 2: Open the Setup Page
There are three ways to open the UPS setup page:
Method 1 β Via Search:
- Press ++alt+q++ (or the search field in the top right)
- Enter UPS Shipment Setup
- Click on the search result
Method 2 β Via the merchantCENTRAL Dashboard:
- Open the merchantCENTRAL Dashboard
- Navigate to Shipping Providers
- Click on UPS
Method 3 β Via the Shipping Providers List:
- Open the Shipping Providers list
- Find the UPS entry
- Click on Open Setup in the action bar
Automatic Initial Creation
When opening the setup page for the first time, an empty record is automatically created. You don't need to create anything manually.
Step 3: Enter API Credentials
In the API Credentials section, enter your OAuth 2.0 credentials:
3.1 API Base URL
| Environment | URL |
|---|---|
| Production | https://onlinetools.ups.com |
| Sandbox | https://wwwcie.ups.com |
Recommendation: Start with Sandbox
Enable the Sandbox Mode field β the URL will automatically switch to the sandbox address.
3.2 OAuth 2.0 Credentials
| Field | What to Enter | Example |
|---|---|---|
| Client ID | OAuth 2.0 Client ID from the Developer Portal | A1B2C3D4E5F6G7H8I9J0 |
| Client Secret | OAuth 2.0 Client Secret (will be masked) | *** |
Credential Security
Client ID and Client Secret are stored encrypted in Business Central IsolatedStorage β not as plain text in the database. After entry, they are only displayed as ***.
3.3 Account Number
| Field | What to Enter | Example |
|---|---|---|
| Account Number | 6-character UPS Shipper Number | A12B34 |
Where Do I Find the Account Number?
You can find the UPS Account Number (Shipper Number):
- On your UPS invoices
- In the UPS business customer portal under Profile β Account Information
- In your UPS contract letter
Step 4: Test the Connection
Test the connection before proceeding:
- Click Test Connection in the action bar
- Business Central requests an OAuth Access Token from UPS
-
On success, a confirmation message appears:
β Connection successful. OAuth Token received.
-
The token is stored in the background (validity: ~4 hours)
Connection Failed?
Possible causes:
- Wrong Client ID or Client Secret β Check your credentials in the UPS Developer Portal
- Wrong URL β Sandbox credentials only work with the sandbox URL
- App not activated β Make sure your app has Active status in the Developer Portal
- Firewall β The BC server must be able to reach
onlinetools.ups.com(port 443)
β More help: Troubleshooting
Step 5: Enter Shipper Address
In the Shipper Address section, enter your shipper address:
| Field | Description | Example |
|---|---|---|
| Shipper Name | Company name | ALTENBRAND Datentechnik GmbH |
| Shipper Attention Name | Contact person (Attn.) | Max Mustermann |
| Shipper Street | Street (line 1) | Am Brunnenfeld 1 |
| Shipper Street 2 | Address supplement (line 2, optional) | Building B |
| Shipper Post Code | Postal code | 86511 |
| Shipper City | City | Schmiechen |
| Shipper Country Code | Country code (ISO-2) | DE |
| Shipper State/Province | State (required for USA/CA) | BY |
| Shipper Phone | Phone number | +49 8206 96200 |
| Shipper Email | Email address | versand@altenbrand.de |
Required Fields
Shipper Name, Shipper Street, Shipper Post Code, Shipper City, and Shipper Country Code are mandatory.
State/Province
For shipments within Germany, the State/Province field is optional. For shipments to the USA or Canada, it is required (e.g., CA for California, ON for Ontario).
Step 6: Set Default Settings
6.1 Default Service
| Service | Code | Transit Time | Coverage |
|---|---|---|---|
| UPS Standard | 11 |
2β5 business days | Europe |
| UPS Express | 07 |
Next business day | Worldwide |
| UPS Express Saver | 65 |
Next business day (more economical) | Europe |
| UPS Express Plus | 54 |
Earliest possible | Worldwide |
| UPS Expedited | 08 |
2β5 business days | Worldwide |
| UPS Access Point Economy | 70 |
2β5 business days | Access Points |
| UPS Worldwide Express Freight | 96 |
Next business day | Freight, worldwide |
Recommendation
For European B2B shipping, UPS Standard (11) is the most common choice. For time-critical shipments, choose UPS Express (07).
6.2 Package Types
| Type | Code | Description |
|---|---|---|
| Customer Supplied | 02 |
Your own packaging (default) |
| UPS Letter | 01 |
UPS envelope |
| Tube | 03 |
Shipping tube |
| PAK | 04 |
UPS PAK (plastic envelope) |
| Express Box | 21 |
UPS Express Box |
| 25KG Box | 24 |
UPS 25 kg box |
| 10KG Box | 25 |
UPS 10 kg box |
6.3 Label Format
| Format | Description | Usage |
|---|---|---|
| GIF | Standard image format | Office printers, web view |
| PNG | High-resolution image format | Office printers |
| ZPL | Zebra Programming Language | Zebra thermal printers |
| EPL | Eltron Programming Language | Eltron thermal printers |
| SPL | Star Programming Language | Star thermal printers |
6.4 Label Size
| Size | Description |
|---|---|
| 4x6 | 4 Γ 6 inches β standard thermal printer format |
| 4x8 | 4 Γ 8 inches β larger format with more space |
6.5 Default Weight
Enter a default weight in kilograms (e.g., 1 for 1 kg, max. 70 kg). This is used when no weight is specified on the package.
Step 7: International Settings (Optional)
In the International / Customs section, you can set defaults for international shipping:
| Field | Description | Example |
|---|---|---|
| Shipper Tax ID | EORI number or VAT ID for customs documents | DE123456789 |
| Default Reason for Export | Default reason for export | SALE |
β Details: International Shipments
Only for International Shipping
If you only ship within the EU, you can skip this step.
Setup Complete β
After these steps, your UPS Connector is ready to use. You can now:
- Create Labels β Create single or multiple shipping labels
- Create Return Labels β Generate return labels for customers
- Void Shipments β Void created labels at UPS
Checklist
- [ ] Client ID and Client Secret entered
- [ ] Account Number entered
- [ ] Test Connection successful
- [ ] Shipper address complete (Name, Street, Postal Code, City, Country)
- [ ] Default service selected (e.g., 11 for UPS Standard)
- [ ] Package type selected (e.g., 02 for Customer Supplied)
- [ ] Label format selected (GIF, PNG, ZPL, EPL, or SPL)
- [ ] Label size selected (4x6 or 4x8)
- [ ] Default weight entered
- [ ] Optional: Shipper Tax ID for international shipping