How to configure UPS (UPSPARCELREST) in techSHIP [Guide]

UPS REST uses OAuth authorization to connect the account owner's UPS profile to techSHIP.

The UPS integration supports:

• Void, including void requests for closed orders

• Rate Shopping

• Time in Transit, when returned with rates

• Tracking History

• Third-Party Billing

• Collect on Delivery (COD)

• Flexible Address Validation

• Returns and Return Labels

• Label References

• Signature Required

• Dangerous Goods

• WorldEase manifest processing

Information to be Provided

Have the following account information available before configuring UPS:

Confirm that the account is enabled for the intended services, shipping locations, and billing arrangements. For Dangerous Goods, confirm eligibility for the intended material, transportation mode, and service with UPS before processing shipments.

Specifications and Constraints

Operational Details

UPS supports domestic and international small parcel shipping. Available services depend on the account, origin, destination, and package type.

Commercial Invoice: techSHIP submits international trade-document information and stores invoice documents returned by UPS. Supply the required commodity, customs, and export data; a shipping label does not replace the commercial invoice.

CUSMA certificates: For eligible international shipments between the United States and Canada, the integration can upload PDF certificates attached to matching client-item SKUs. Client items must be enabled, trade documents must be included, and the shipment must not use Mail Innovations or SurePost. This upload uses the supplied certificates; it does not create a certificate for an item without one.

Dangerous Goods documents: The integration stores DG documents returned by UPS. Document availability depends on the shipment and carrier response. Confirm the required declarations, package markings, and pickup paperwork for the shipment; do not assume the shipping label or DG declaration supplies every required document.

• Mail Innovations packaging: Use a separate Client Account when the required Package type is incompatible with the standard UPS services used by another account.

• Dangerous Goods rating: ECO mode and rate estimates are unavailable for DG shipments. Select the appropriate shipping service directly.

• Returns: Return labels can be requested with outbound shipments, and separate return shipments are supported. Configure the applicable return service, address, and billing information.

• WorldEase: Manifest processing closes the applicable WorldEase master shipments. This is separate from DG declaration printing.

EU Product Identifiers

For qualifying consumer shipments imported into the European Union from outside the EU, techSHIP validates required product identifiers when processing on or after November 1, 2026, at 00:00 UTC. The check applies when international trade-document processing applies.

Use the manufacturer's actual identifier. Copying the merchant SKU is appropriate only when it is also the manufacturer-assigned identifier. Values sent to UPS are trimmed and limited to 100 characters.

Supply these values through the Integrated system or supported order-management rules. They belong to the corresponding commodity lines, not to general order references.

Configuring a Baseline Account

A Baseline Account serves as the fundamental connection point between techSHIP and the carrier's system. It acts as a template that holds the credentials and fundamental properties required to process shipments.

The techSHIP AI Assistant is available from the Carrier page for supported Carrier configuration tasks. For detailed conceptual information and advanced configuration, refer to 📄 techSHIP AI Assistant: Overview & Availability [Information].

Adding a Carrier

Before adding an account, you must ensure the Carrier entity is available for your location.

1. Click My Carriers from the left menu under the Carriers category.

2. Click Add Carrier.

   

3. Select the desired Carrier.

You may encounter additional messages depending on the carrier status or your plan:

• Subscription Required (⭐): If the carrier has a star icon, you will see a message stating "To use this carrier, a subscription upgrade is required." Press Contact to Upgrade to proceed.

  

• Carrier Suspended: If the carrier has not been used for an extended period, you will see a message stating “This carrier is currently on hold...” Click Request Assistance to reactivate it.

  

• Setup Fee Waived: If a carrier from the same carrier group is already installed in your location, you can add this carrier without incurring additional fees.

  

4. If needed, update the carrier Name.

5. Click Add Carrier.

   

If the purchase confirmation appears, complete the following steps:

• Review the purchase notice and any applicable charge information.

• Optionally enter a PO Number.

• Select I am authorized to complete this purchase on behalf of my organization.

• Click Purchase to confirm the Carrier addition.

Once the Carrier is added, you will be automatically redirected to the Carrier page to continue setting it up.

6. Enter the Code of the Carrier as it appears in your host system.

The Code of the Carrier must match exactly the value defined in the host system. Any discrepancy (including casing or extra spaces) may prevent the carrier from working correctly.

7. Click Save.

   

If your facility utilizes the centralized Pickup Schedule, we highly recommend adding this new carrier to your calendar now. While not required to process labels, this ensures accurate induction metrics for your Insights dashboards. To learn more, see 📄 Understanding the Centralized Pickup Schedule & Expected Induction Logic [Information].

Adding a Baseline Account

From the Carrier page, click Add Account to create a new Baseline Account.

You will be redirected to the Baseline Account page to complete the setup.

Entering incorrect values will prevent the system from generating shipping labels.

General Tab

In the General tab, define the administrative properties:

• Name: Enter a descriptive name for the account.

Enter a descriptive name based on unique properties. E.g.:

• Carrier Name - Account Number (CarrierX - 123456789)

• Carrier Name - Consolidator Name (CarrierY - MyConsolidator)

• Carrier Name

• Usage: Select the most suitable option:

  • Test: Used for sandbox or onboarding purposes.

  • Production: Used for live shipping.

Keep the Status field set to its default Active value. An account must be Active to remain fully editable. For detailed conceptual information on account statuses, refer to 📄 How to Inactivate and Activate a Carrier Baseline Account [Step-by-Step Guide].

Registration Tab

Save the Baseline Account before registering it. On the Registration tab, use the registration action and choose:

• Register this account now: Complete authorization with the account owner’s UPS login.

• Send a registration link to the customer: Generate a link for the account owner to complete authorization. Link validity can be set from 1 to 7 days.

The account owner signs in to UPS and approves the connection. Successful registration populates Registration id. An existing registration ID can be reused across accounts or portals within the same organization.

Only one registration link is active for an account at a time. Generating a replacement or choosing Register this account now replaces the previous active link.

Carrier Tab

Connection and Pickup Settings

• Registration id: Identifies the account's authorization. It is populated through registration; an existing ID can be entered when reusing a registration.

• Pickup mode: Select the pickup or drop-off arrangement used by the account.

• Contact name, Pickup open time, Pickup close time, and Pickup ready hours: Configure the warehouse pickup contact and schedule when applicable.

• Weekends mode: Configure the days excluded from pickup scheduling.

• Fetch zone info from ups: Enable when zone information is needed. This can require an additional rate request after label creation.

Mail Innovations

Configure MI customer number and MI customer Guid with the rating credentials supplied by UPS. MI rate timeout controls the timeout used for that rating operation.

Ship From Address

Complete the Ship from address group with the warehouse induction address, Sender name, and Phone. Client-specific address overrides are configured in the Client Account.

Labels Tab

Formats: ZPL thermal output and image-based PDF output are supported. PDF and PNG preferences request an image from UPS for conversion; selecting PNG does not mean that UPS returns a native PNG shipping label.

Stock sizes: The integration requests 4 × 6-inch or 4 × 8-inch labels according to the Baseline Account's label-stock setting. Select the output and stock appropriate for the printing workflow.

Finalizing the Setup

Once you have entered the required information, click Save.

After you save the Baseline Account, check whether the Registration tab or a registration status badge is available.

If neither is available, the Carrier does not use this Registration workflow in techSHIP. If registration is still pending, open the Registration tab and press Registration, then complete 📄 How to Register a Carrier Baseline Account [Step-by-Step Guide] before creating shipments.

From the Carrier page, you can now see the Baseline Account listed with the administrative status Active. The Active status is separate from the account's registration status.

The Baseline Account configuration is now saved. You can continue with Configuring a Client Account below to assign the Baseline Account to a specific Client.

Configuring a Client Account

Adding an Account

Before adding a Client Account, ensure that the Client has been created. For instructions creating a Client, see: 📄 10 - How to create a Client profile [Step-by-Step guide].

1. Click Clients from the left menu under the Clients section.

2. Click the Edit icon for the desired Client.

   

3. Click Add Accounts.

   

4. Optionally, use the Search box to search by Baseline Account Name or Carrier.

5. Select the Baseline Accounts that will serve as the foundation for your new Client Accounts.

6. Click Add Accounts.

   

   A toast notification will confirm the accounts were successfully assigned. Click the Refresh icon if recently added accounts are not displayed.

   

7. Click Edit on each newly created account.

   

8. Configure the available options in each tab (except Carrier).

   

For complete instructions on configuring this settings, see 📄 How to configure the Billing Account General Options tab [Step-by-Step guide].

Carrier Tab

Service and Address Validation

• Service code: Select the service used for orders without an applicable imported service, or select ECO for eligible rate-shopping shipments.

• Override WMS Service Code: Enable when the configured Service code must replace the service received from the Integrated system.

• Default commodity description: Supply the fallback commodity description.

• Package type: Select packaging compatible with the intended service.

• Address validation: Select the validation behavior. Street-level validation is available for supported US and Puerto Rico addresses.

• Handle unclassified as residential: Configure how an address without a residential/commercial classification is treated.

Accounts and Billing

• Shipper account #: Enter the shipping account number.

• Bill receiver account # or Bill third party account #: Configure the applicable alternative payer, with Bill postal and Bill country as required for the selected billing arrangement.

• Use as default third party bill postal and country: Use the configured billing postal code and country as defaults for third-party billing.

• Duty payment terms: Select the duty payer. Complete Duty account #, Duty account postal, and Duty country code where applicable.

• Bypass UPS 120901 negotiated rates unavailable error: Enable only when the account should accept an otherwise successful shipment response containing alert 120901. With this option disabled, that alert blocks processing. Enabling it does not establish that negotiated rates are available or correct.

Export and Customs

Keep Skip trade documents disabled when international trade-document submission is required.

Configure Reason for export, Shipper tax number, Currency code for export, and Terms of sale for the client. Additional comments, Declaration statement, and Commercial invoice copies provide the corresponding invoice settings.

Returns

Use Print return labels to request return labels with outbound shipments. In the Returns group, configure the return Service code, return address, and applicable Return bill shipper account #, Return bill receiver account #, or Return bill third party account #. Complete Return bill postal and Return bill country when required.

Address Overrides

In Ship from (induction) address, configure the sender identity and Ship from phone. Use Override sender address when the client ships from an address different from the Baseline Account.

Use Reformat ship-to phone when recipient phone formatting is needed. If Substitute missing ship-to phone is enabled, supply the replacement in Ship-to phone substitution.

WorldEase

For accounts using WorldEase, configure Enable WorldEase, DocBox label service, destination, charge, and port information in the World Ease group using the account's agreed setup with UPS.

DG/Hazmat Tab

This tab is available when the location has DGIS or client-item Dangerous Goods functionality enabled.

• Enable Dangerous Goods: Enable for shipments using DG data prepared from client items or DGIS. This setting selects the prepared-data workflow; it does not populate missing item details.

• Map Regulation from Carrier/Service and Regulation: Use the service mapping or configure the applicable regulation explicitly.

• Map Transportation Mode from Carrier/Service and Transportation Mode: Use the service mapping or configure the applicable transportation mode. Check that it matches the actual service, particularly for air shipments.

• Map Form Type from Carrier/Service and Form Type: Configure the form selection used by the DG workflow.

• DG Declaration Type: Select an available declaration template when the configured workflow uses one.

• Emergency Contact Name, Emergency Contact Phone, and Emergency Contract Number: Supply the applicable emergency-contact details.

• Signatory Place (default): Supply the default signing location used by the DG workflow.

• Default Package UN Code and Default Package Type: Supply the applicable DG packaging defaults.

Preparing Client Items for Dangerous Goods

For each affected SKU, open the client item and select the Dangerous goods tab:

1. Select Enable Dangerous Goods for the item.

2. Complete Container Type with the applicable packaging value. UPS uses this item-level value as the HazMat packaging type.

3. Complete the item's DG details using the values confirmed by your DG specialist, including the UN identifier, hazard class, and packing group when applicable.

4. Ensure the order's SKU matches the configured client item and synchronize the DG item data to the shipment before processing.

Also select Enable Dangerous Goods in the Client Account's DG/Hazmat tab and mark the order as Dangerous Goods. Enabling DG at the Client Account does not automatically mark the order as a DG shipment.

The Hazardous materials (deprecated, use client items instead) group on the Carrier tab is not the setup path for new item-based DG configurations. Turning off Enable Dangerous Goods switches away from prepared item/DGIS data to stored account-level HazMat values; it does not automatically repair missing data.

Specifying Rate Shopping Service Codes

Configure the services to include or exclude when rate shopping. In the Carrier tab:

• Rateshop SurePost: Include eligible SurePost rates.

• Rateshop Mail Innovations: Include eligible Mail Innovations rates after configuring its Baseline Account rating credentials.

• Skip generic UPS rateshop: Exclude standard UPS rates when using the applicable SurePost or Mail Innovations configuration.

For detailed instructions on how to configure this, see: Include or exclude Service Codes when Rate Shopping [Step-by-Step Guide].

Label References

Configure references in the Client Account's General tab, in the Labels group. Reference 1 through Reference 4 and their corresponding type fields are available; empty client values can inherit the corresponding Baseline Account values.

Standard UPS shipments submit up to two nonempty references. Mail Innovations can submit up to four. Allow reference truncation applies the carrier's reference-length restriction.

For a distinct third reference, verify the transmitted value before relying on it: the current mapping can reuse Reference 2 for the third slot. The four available fields do not guarantee four independent values.

For a comprehensive guide on how to use label references, see: Using order References in your labels [Step-by-Step guide].

Finalizing the Setup

Once you have entered the required information, click Save.

With the account configured and requirements verified, you can now proceed to process orders as described below.

Configuring an Order

The steps described in this section are not required for carrier setup, and they are offered as an optional review if further order-level configuration is required.

Follow the UI Navigation steps in 📄 05 - How to edit an order’s information - [Step-by-Step guide], using the carrier-specific values provided in this guide.

Carrier Tab

Review the applicable settings when editing the order:

• Service code and Ship date: Select the shipping service and date.

• COD amount and COD Funds Code: Configure collection when applicable to the shipment.

• Print return labels: Use the account default or override return-label generation for the order.

• Skip address validation and Residential: Set the applicable validation and address classification.

• Commodity description: Enter the shipment description.

• Dangerous Goods: Mark shipments requiring DG processing. Complete the item/DGIS preparation as well as the Client Account setup.

• Signature required: Request the applicable signature service.

In Commercial invoice, review PO Number, Invoice number, Shipper type, Receiver type, Reason for export, Terms of sale, Consignee tax number, Shipper tax number, Additional comments, and Declaration statement as applicable.

Shipper type and Receiver type use the order value first, then the Client Account value, then the integration default: Business for the shipper and Direct consumer for the receiver. Select the actual party classification. For qualifying EU imports, ensure every commodity line has the required product identifiers described above.

Click Save to apply the order-level changes. After the Order is updated, continue with the standard shipping workflow.

Dangerous Goods Documents

After processing, use Print → DG Declaration to print the DG document available for the order. UPS documents returned with the shipment are retained with the first package. This action does not guarantee that UPS returned a document, or that the available declaration is the specific certification required for pickup.

Troubleshooting

• Authorization token is missing: Review the Baseline Account's Registration tab and complete authorization with the account owner. Verify Registration id before attempting shipment processing.

• Registration link no longer works: Check whether it expired, was revoked, or was replaced. Generate a current link from the Baseline Account's Registration tab.

• UPS rejects shipment creation: Check Shipper account #, service, origin, destination, and account authorization. Successful rating alone does not confirm permission to create a shipping label.

• Missing EU product identifiers: For applicable consumer imports, populate the affected item-line SKU and manufacturer product identifier. Confirm the actual Receiver type; do not reclassify a consumer shipment simply to bypass validation.

• Dangerous Goods details are absent: Check Enable Dangerous Goods, SKU matching, item DG flags and details, and completion of the item/DGIS synchronization. Marking the order as Dangerous Goods alone does not create the required commodity data.

• Invalid DG regulation or transportation mode: Review Regulation, Transportation Mode, their mapping options, and the selected service in the Client Account. Confirm that the supplied values match the intended shipment.

• UPS reports missing HazMat packaging type: For error 126071 PackageServiceOption/HazMat/PackagingType is required, open the affected client item, select Dangerous goods, and complete Container Type with the appropriate value. Verify that the order SKU matches that item and synchronize the updated DG data before processing again.

• UPS rejects item DG details: Verify the formatting of the UN identification number and hazard class in the client item's DG data. Enter the applicable codes rather than descriptive labels; for example, a confirmed Class 9 item uses 9, rather than CLASS 9. Confirm the complete UN identifier and whether a packing group applies with your DG specialist. Do not remove a packing group solely to make an order process; successful processing does not establish regulatory compliance.

• DG rate estimate fails: ECO mode and rate estimates are unavailable for DG shipments. Select the applicable service directly instead of using ECO.

• DG declaration is missing: Check whether the shipment response contains a DG document and whether the configured declaration workflow produced one. Provide Support with the order and response details if no document is available; label creation alone does not establish that all DG paperwork was returned.

• Alert 120901 blocks processing: Review Bypass UPS 120901 negotiated rates unavailable error and the returned charges. Before retrying a failed order that already received a tracking number, verify cancellation of the prior shipment. Historical shipments without a stored cancellation identifier may require cancellation directly with UPS.

• Label exists but charge or zone is missing: If Fetch zone info from ups is enabled, inspect the subsequent rate/charge error. A failed zone lookup can leave the order processed with its label and an unresolved charge; verify the existing shipment before creating another one.

• Mail Innovations rates are unavailable: Verify MI customer number, MI customer Guid, Rateshop Mail Innovations, and a compatible Package type.

• CUSMA certificate is not submitted: Verify the matching client-item SKU and attached PDF, the US–Canada international lane, and that Skip trade documents is disabled. The upload does not apply to Mail Innovations or SurePost.

• Return-label processing fails: Review Print return labels, the return Service code, return address, and return billing fields in the Client Account's Carrier tab.

• References differ from the configured values: Check General → Labels, inherited values, the service-specific reference count, and the third-slot limitation described under Label References.