1. Home
  2. Docs
  3. Guides
  4. Ups_Migration_Faq
Log a Case

UPS Migration FAQ

Common questions and answers about the UPS XML to REST migration.

  1. Overview
  2. Migration steps for UPS Shipmate users
  3. Migration steps for Multi-Carrier users
  4. Shipping Preference
  5. Custom Address Source
  6. Shipping
  7. UPS Shipmate
  8. Commerce Cloud
  9. API Only

Overview

From 3 June 2024 UPS decommissioned their XML API and customers are required to migrate to the new REST API. For common questions and issues please see this guide.

We are continuously updating this guide with more questions and known issues.

NOTE: We filed for an extension of the deadline which was granted until 5 August. This is now further extended until 31 August.

Install the latest version of the package for sandbox or production.

What happens if I don't migrate?

UPS will begin to reduce functionality starting with Tracking.

Migration steps for UPS Shipmate users

Here you can find a detailed step by step guide of migrating from UPS Shipmate to UPS REST in Multi-Carrier.

1. Install the latest version of the app

The package version in your environment should be at least v1.127.5 but preferably higher. You can find the install link of the latest package under the Overview section of this page.

2. Install the latest version of the Migration Toolkit

Please use the Migration Toolkit v0.10 for sandbox or production. If you have any of the previous versions installed (v0.5 or 0.7) please uninstall them before installing v0.10.

3. Migrate your Shipmate Preferences

UPS Shipmate preferences can be migrated directly into the Multi-Carrier app.

IMPORTANT NOTES:
Once a preference is migrated it can NOT be reverted.

  1. Navigate to the 'Bringg Migration' object in Migration Toolkit
  2. Click on the'Migrate Single Carrier Preferences' button
  3. Select the preference(s) you want to migrate
  4. Click on the 'Migrate UPS Preferences' button
  5. Once completed you will see a 'Success' message and your preference will now be located under Shipping Preferences
  6. To finish the migration to UPS REST proceed with Step 1 and Step 3 of Migrate to Multi-Carrier.

4. Migrate Historic Data

It is possible to save historic data from the Shipmate app.

  1. Navigate to the 'Bringg Migration' object
  2. Click on the 'Create Job' button
  3. Click on 'Add'
  4. Select an option for the Single Carrier as well as the Multi-Carrier
  5. Click on 'Start Migration'

Migration steps for Multi-Carrier users

Here you can find a detailed step by step guide of migrating from UPS or UPS (API) to UPS REST.

1. Get your oAuth credentials

You need to use your 'ups.com' profile credentials to authenticate the accounts. Due to security limitations a set of credentials can only be used in one environment, so we recommend creating separate profiles for sandbox(es) and production.
Please also make sure that the account number is linked to the ups.com profile under existing payment methods.

IMPORTANT NOTES:
One set of credentials can only be used in one environment.
A preference can only be set up either on the test servers OR on the production ones. This is set based on the 'Demo Mode' toggle under Zenkraft Settings.

2. Install the latest version of the app

The package version in your environment should be at least v1.127.5 but preferably higher. You can find the install link of the latest package under the Overview section of this page.

3. Migrate your Shipping Preferences

IMPORTANT NOTES:
Once a preference is migrated it can NOT be reverted.
Before starting the authorization process make sure that all popup blockers are DISABLED.
Do NOT start migrating without the appropriate credentials.

There are three different scenarios to authorize the preferences:

  • You have one UPS account
  • You have multiple UPS accounts connected to a single ups.com profile
  • You have multiple UPS accounts connected to different ups.com profiles

  1. Navigate to the 'Migration' object in Multi-Carrier
  2. Select the preference(s) you want to authorize
  3. Click on the 'Authorize' button, this will redirect you to ups.com
  4. Enter your ups.com profile credentials in the popup window
  5. Once authorized you will receive a message saying that the process is complete
  6. Go back to the Migration tab
  7. Select the preference(s) you want to migrate
  8. Click on the 'Migrate' button

4. Migrate your Custom Address Sources

We run a check on all custom address sources and if UPS values are found within the CAS the inline status will set to 'Can Be Migrated'.

IMPORTANT NOTE:
Dynamically mapped values related to UPS will NOT be addressed/converted by the migration package.
Example: if Service Type is a mapped field rather than a static value you will need to manually convert the values in that field.

  1. Navigate to the 'Migration' object in Multi-Carrier
  2. Select the Custom Address Source record(s) you want to migrate
  3. Once migrated the inline status will change to 'Migrated'

Shipping Preference and Account

Is it possible to complete the migration first in Sandbox and then Production with the same shipping account? Or is there a limitation on migrating the same UPS account twice?

You can either set up a new Test preference or create a separate login that you'd sign in with in Sandbox.

Can I reauthenticate a Shipping Preference?

If you start receiving authorization errors or just want to reauthenticate the account you can do that by going to the shipping preference, edit, and reauthenticate the account by clicking on the "Login to ups.com" button.

Can I authenticate my accounts using my UPS CampusShip profile?

No, UPS CampusShip users will need to register for a regular ups.com profile.

Custom Address Source

I'm using the UPS (API) integration in the Multi-Carrier. Do I still need to migrate my Custom Address Source?

Yes, as the UPS (API) integration still uses the old XML API.

When migrating the Custom Address Source what changes should I expect to see?

After the migration Service type, Specific Carrier Fields, Payment type, Duties Payment Type, and Packaging type should all change.
Important note: Dynamically mapped values related to UPS won't be addressed/converted by the migration package. So, for instance, if Service Type is a mapped field rather than static value, you will need to convert all the values on that field.

Shipping

I am receiving an error message in the Shipment wizard stating "'9' is not valid under any given schemas"

Go to your relevant Custom Address Source, navigate to the Specific Carrier fields. Find the "UPS REST: Return Type" mapping and change it to "print_return_label".

When migrating the Custom Address Source what changes should I expect to see?

After the migration Service type, Specific Carrier Fields, Payment type, Duties Payment Type, and Packaging type should all change.
Important note: Dynamically mapped values related to UPS won't be addressed/converted by the migration package. So, for instance, if Service Type is a mapped field rather than static value, you will need to convert all the values on that field.

I am receiving an error message about "sender" not being an accepted value for billing

Go to your relevant Custom Address Source, navigate to the Specific Carrier fields. Find the "UPS REST: Duty Payment Type" mapping and change it to "shipper".

I am not able to override the 'sold to' information for international shipments

Unfortunately this feature is currently missing from the integration, we are working on adding it.

I am not able to find 'Shipping Notes'

Please make sure you are using v1.127.20 or higher.

'Validate Address' button is missing

Unfortunately this feature is currently missing from the integration, we are working on adding it.

Return shipment error: "Only one package is allowed for this movement"

Please note that Return Service can only process one package at a time.

How can I bill an account if I don't have the ability to authorize using the new UPS oAuth?

Third-party billing, also known as third-party logistics (3PL) billing, is a shipping arrangement where a party other than the shipper or consignee assumes financial responsibility for the shipment charges. In simpler terms, it involves the billing of shipping charges to a party other than the buyer or seller of the goods.
UPS (and many other shipping providers) recognize that their customer might utilize a third party to ship on their behalf, Zenkraft has built this functionality into our application!
You will first need to create a shipping preference using the new REST API (or migrate an existing preference). If you do not have your own UPS account already you will need to get one.
In order to let UPS know that you plan to bill another account you will need to use "third-party" billing. In the shipping wizard this setup will look like:

If you would like to automate the completion of these fields you can define them in the Custom Address Source.

UPS Shipmate

Can I continue using the UPS Shipmate app with the REST API?

No, you will need to migrate to the Multi-Carrier app to utilize the UPS REST API.

What are the steps to migrating to Multi-Carrier?

You can find the steps in our UPS Migration guide.

I am not able to see the 'Migrate Single Carrier Preferences' button

Please make sure you are using the Migration Package v1.7.

Can I keep historic shipment data?

Yes, you can migrate historic shipment data using the Migration Package.

Can I filter historic shipment data when migrating?

Yes, you can filter for example by created date to only save shipments created in the past few years.

Commerce Cloud

Do I need to change anything in my Zenkraft Cartridge configuration?

You can find the steps to updating the configuration in the cartridge in our SFCC Migration guide.

If I have both SFCC and Multi-Carrier, but one UPS.com login, what are the recommended steps to migrate?

You should first migrate everything within the Multi-Carrier then adjust SFCC as needed.

API Only

What are the steps to migrating the account on the API?

You can find the steps in our API Migration Guide.

How do I reauthenticate the account?

Fill in the missing details in the below code and run the request in Postman.

		curl --location --request PUT 'https://api.zenkraft.com/shippingaccount' \
		--header 'zkkey;' \
		--header 'Content-Type: application/json' 
		--data '{
				"shipping_account": {
					"carrier": "ups_rest",
					"country": "",
					"debug": true,
					"test": false,
					"auth": {
						"account_number": ""
					},
					"shipping_account": "",
					"parent_shipping_account": ""
				}
			}'

Does the authorization ever expire?

The authorization should never expire. If you start receiving authorization errors you can issue another PUT call on /shippingaccount