Skip to content

Creating Labels

With the UPS Connector, you can create single labels, bulk labels, and return labels, as well as void shipments and recover labels. This guide explains all variants step by step.

Creating a Single Label

Step 1: Start Label Creation

Via the merchantCENTRAL Dashboard:

  1. Open the merchantCENTRAL Dashboard
  2. Click on Shipment Labels β†’ Create New Label

Via the Shipment Label List:

  1. Open the Shipment Label List (search: Shipment Labels)
  2. Click New in the action bar

Via a Sales Order:

  1. Open the posted Sales Order or the Sales Shipment
  2. Use the Create Shipping Label action

Step 2: Select Shipping Provider

In the Create Label dialog:

  • Shipment Provider: UPS
  • Service: pre-filled from the UPS Setup (e.g., 11 for UPS Standard)

Change Service per Label

You can change the UPS service individually per shipment. For example, normally UPS Standard for regular shipments, but UPS Express for urgent packages.

Step 3: Fill In Recipient Details

Field Description Required
Recipient Name Recipient name βœ… Yes
Recipient Attention Name Contact person (Attn.) ❌ No
Recipient Street Recipient street βœ… Yes
Recipient Street 2 Address supplement ❌ No
Recipient Post Code Postal code βœ… Yes
Recipient City City βœ… Yes
Recipient Country Code Country code (ISO-2, e.g., DE, US) βœ… Yes
Recipient State/Province State (required for USA/CA) ⚠️ Conditional
Recipient Email Email (for QVN Ship Notification) ❌ No
Recipient Phone Phone ❌ No

Automatic Population

When you create a label from a sales order, the recipient details are automatically populated from the delivery address.

USA & Canada: State Is Required

For shipments to the USA or Canada, the State/Province field must be filled in (e.g., CA, NY, ON). UPS will reject shipments without this field.

Step 4: Enter Shipment Details

Field Description Default
Weight (kg) Weight in kilograms From UPS Setup
Package Type Package type From UPS Setup
Package Content Content description β€”
Reference No. 1 Your reference number (e.g., order number) β€”
Reference No. 2 Second reference number β€”

Step 5: Create the Label

Click Create. Business Central performs the following steps:

  1. Validation β€” Checks all required fields, weight ≀ 70 kg, country codes = 2 characters
  2. OAuth Token β€” If no valid token is available, a new one is requested
  3. JSON Request β€” Shipment sent as JSON to the UPS Shipping API (POST /api/shipments/v2409/ship)
  4. Parse Response β€” ShipmentIdentificationNumber, tracking numbers, label graphic
  5. Storage β€” Label and tracking numbers are saved in Business Central

After successful creation, you will see:

  • The Shipment Identification Number (UPS shipment number)
  • A Tracking Number per package
  • Tracking URL: https://www.ups.com/track?tracknum={Number}
  • The label is ready for download/print

Creating Bulk Labels

For processing multiple shipments at once:

Procedure

  1. Open the Shipment Label List
  2. Select multiple open labels (++ctrl+click++ or ++shift+click++)
  3. Click Create Bulk Labels in the action bar
  4. Confirm the creation

Sequential Processing

Unlike DPD (one SOAP call for all), UPS labels are created sequentially β€” one shipment at a time. This is due to the UPS API, which does not offer a multi-shipment endpoint. The bulk function still automates the process significantly.

Error Handling for Bulk

  • If an error occurs, the affected shipment is flagged and the process continues for the remaining shipments
  • After bulk creation, check the error messages in the label list

Multi-Parcel Shipments

For shipments with multiple packages:

Adding Packages

  1. Open the label
  2. In the Packages section, you will see the package list
  3. Add a line for each package:
Field Description
Package Type Package type (individually per package)
Weight (kg) Weight in kilograms (max. 70 kg)
Length / Width / Height (cm) Dimensions in centimeters
Package Content Content description
Reference No. 1 Reference for this package

Dimensional Weight

UPS calculates the transport weight as the maximum of actual weight and dimensional weight (L Γ— W Γ— H / 5000). Enter the dimensions so UPS can calculate the correct weight and avoid surcharges.

After Creation

Each package receives its own tracking number. In the package list, you will see:

  • Tracking Number β€” individual UPS tracking number per package
  • All packages are linked via the shared Shipment Identification Number

β†’ Details: Packages

Voiding a Shipment

Created UPS shipments can be voided as long as they have not yet been picked up:

Procedure

  1. Open the shipment label you want to void
  2. Click Void Shipment in the action bar
  3. Confirm the void

What Happens During a Void?

  • Business Central sends a Void Request to UPS (DELETE /api/shipments/v2409/void/cancel/{id})
  • UPS confirms the void with StatusCode 1
  • The label is marked as voided in Business Central
  • The tracking number becomes invalid

Time Window

A void is only possible before UPS has physically picked up the package. After pickup, the shipment can no longer be voided.

Label Recovery

If a label has been lost or could not be printed:

Procedure

  1. Open the affected shipment label
  2. Click Recover Label in the action bar
  3. Business Central requests the label again via the Label Recovery API

Tracking Number Required

For label recovery, the tracking number must be known. It is automatically saved when the label is created.

Validation Before Creation

Before a label is created, Business Central automatically checks:

Check Error Message
Account Number present? Account Number must have a value
Shipper address complete? Shipper Name/Street/PostCode/City must have a value
Credentials present? Client ID and Client Secret are required
Recipient name present? Recipient name is required
Recipient street present? Recipient street is required
Recipient postal code present? Recipient post code is required
Recipient city present? Recipient city is required
Country code = 2 characters? Country code must be 2 characters
Weight ≀ 70 kg? Weight must not exceed 70 kg
Customs items for non-EU? Customs items are required for non-EU shipments

Weight Format

UPS uses kilograms (KGS) as the weight unit:

Input in BC Sent to UPS
0.5 kg 0.5 KGS
1 kg 1.0 KGS
5 kg 5.0 KGS
31.5 kg 31.5 KGS
70 kg (maximum) 70.0 KGS

Weight Conversion

If weights in your system are stored in grams, the connector automatically converts them (Γ· 1000).

Frequently Asked Questions

Can I modify a label after it has been created?

No. Void the label and create a new one.

Are shipping notifications sent to the recipient?

Yes! If a recipient email address is provided, the connector automatically activates UPS Quantum View Notification (QVN) β€” the recipient receives an email with tracking information.

What is the default package type?

Customer Supplied Package (02) β€” your own packaging. Use the UPS-branded packaging types (Letter, Tube, PAK, Express Box) only if you are actually using UPS-provided packaging materials.

How many packages can a shipment have?

There is no fixed limit. Each package receives its own tracking number.

Can I reuse the same label after voiding?

No. After voiding, the tracking number is invalid. Create a new label.