UPS Shipping with OAuth

Table of Contents ShowHide

Migrating to UPS OAuth 2.0 before June 4th, 2024

Beginning in June of 2024, you will no longer be able to transact with UPS APIs using an access key for authentication and are required to update your security model to OAuth 2.0.

UPS has implemented an OAuth 2.0 security model for all APIs to enhance the overall security for our customers to reduce fraud and provide enhanced API capabilities. As part of the process to keep customers secure, UPS will deprecate the existing Access Key-based authorization for our APIs. Beginning June 5, 2023, UPS will no longer distribute test keys for the old API, and all API transactions after June 3, 2024, will require clients to implement the OAuth security model.

If you are currently using the "UPS OnLine® Tools" integration with AbleCommerce, then follow the migration steps below to use the new UPS Shipping integration which supports the OAuth 2.0 security model, required by UPS.

What is OAuth?

OAuth 2.0 is a protocol used for authentication and authorization between two or more web applications. The OAuth 2.0 security model involves the use of access tokens, which are issued to a client application by an authorization server.

The access token is a string of characters that represents the authorization granted to a client application by a resource owner (typically, a user). This token is used to authenticate the client application and authorize access to specific resources on behalf of the resource owner and is passed as a bearer token in an API request.

Steps for Migration

The new UPS OAuth is a built-in feature, available in AbleCommerce 9.0.9 and later. If you are using AbleCommerce 9.0.x, and are currently using UPS Online® Tools as your shipping carrier, then follow these instructions for a seamless transition.

Login to your AbleCommerce Merchant Admin.
Using the menu, go to the Plugins page.
Find and install the new Plugin name "UPS Shipping with OAuth"
If needed, follow step-by-step instructions HERE
Register a new UPS developer account to obtain new API keys (Client ID and Client Secret).
If you need help, follow the instructions HERE
Use the new API OAuth security credentials, along with your UPS Account number, configure the new plugin.
If you need help, follow the configuration steps HERE

Complete all steps above before continuing.

Copy Over Configuration Settings

While stilled logged into the admin, open the configuration pages for both UPS Online Tools and UPS Shipping with OAuth with each in a separate browser window, side by side.
Match your configuration settings from UPS Online Tools to the new UPS Shipping with OAuth. Not all settings will change.

Configuration options are the same in both versions, but the default values of the newly installed plugin may be different from the existing one currently in use. Carefully check the configuration settings and update only the following to match UPS Online Tools:

Customer Type
Enable Printing of Labels
Optional Insurance
Enable Package Breakup
Maximum Weight (default 150)
Minimum Weight (default 0.10)
Enable Address Validation

DO NOT CHANGE: Rating URL, Test Server URL, or Tracking URL fields as these are now different than the old integration.

When finished, Save the settings for the new UPS Shipping with OAuth configuration.

Assign Shipping Methods

NOTE: If you have unprocessed orders, awaiting shipment, you should manually update the database so these orders will use the new gateway. An alternative is to make sure all orders are shipped before making the final migration of shipping methods. See Step 2 below for a database query to update the existing shipping methods.

Select and Assign the same Shipping Methods for the new OAuth integration so they are the same as the existing ones you are using in UPS Online® Tools.
Now check (edit) each of these active shipping methods in use for the existing UPS Online® Tools integration and make sure the corresponding ones in the new UPS OAuth integration have the same configuration as the corresponding one in use.

NOTE: If you have customized any of the existing shipping methods (e.g. pricing, rules, groups, zones, tax, etc.) it is possible to manually update the database so each points to the new UPS version:

Update ac_ShipMethods table, column ShipGatewayId, by identifying the original UPS gateway ID and changing it to the new gateway ID.
If you don't have any custom shipping methods, or you have finished carrying over the changes for each, then you can test before deactivating the old existing UPS Online® Tools.

To test, go to the storefront and add a shippable item to the cart.
Proceed through the checkout and stop on the Select Shipping Method page.
If you see two entries for each of UPS shipping methods, then it is working.

If you don't see two entries, then go back to the new UPS Shipping with OAuth configuration page and re-check all the settings by comparing to the original UPS Online Tools configurations.

After a successful test, use the Remove button from the configuration page for the old existing UPS Online® Tools integration being replaced and remove all the active shipping methods from the Configure > Shipping > Carriers page.

The migration is complete.

UPS Shipping Features and Requirements

With UPS API, customers can get real-time shipping rates to domestic U.S., Canadian, and international addresses. Your customers can also view UPS tracking information for their packages right from your store! You can enable UPS Shipping by entering your API OAuth credentials account information within AbleCommerce and immediately get real-time shipping rates.

The AbleCommerce integration with UPS includes Services and Rates, Tracking, Address Validation, Printable Shipping Labels, and the new secure OAuth requirements for API access . The AbleCommerce UPS integration includes features like selecting your rate based on customer type, including insurance, and package tracking. AbleCommerce uses your product's weight and dimensions to calculate the most accurate rates possible.

International shipping is available from many locations –

Argentina, Australia, Austria, Belgium, Brazil, Canada, Chile, Costa Rica, Denmark, Dominican Republic, Finland, France, Germany, Greece, Guatemala, Hong Kong, India, Ireland, Israel, Italy, Japan, Luxembourg, Malaysia, Mexico, The Netherlands, New Zealand, Norway, Panama, Peru, Philippines, Portugal, Puerto Rico, Singapore, South Africa, South Korea, Spain, Sweden, Switzerland, United Kingdom, United States, U.S. Virgin Islands, and Venezuela.

Detailed List of Features and Requirements:

Providing a shipping account number is required for AVS and Print Labels features.
UPS expects all product measurements to be in pounds and inches. Rates will still be calculated if you use a different unit of measurement, but there is additional overhead in converting the measurements. You will have the best performance if you use pounds and inches to begin with.
Shipping to international destinations is available.
Shipment tracking features are built-into AbleCommerce. Tracking services are provided by UPS.com.
Printing Labels with automated tracking number retrieval.
Address Verification Services optional.
Negotiated (discounted) business rates available as a configuration option.

Installing the UPS Plugin for AbleCommerce

Login to your AbleCommerce installation.
Using the menu, go to the Plugins page.
Use the Filter Plugins option and select the type "Shipping".

Note: UPS plugin will be available in the list as shown in the screenshot below.
Click the green Install button in the far right column.
When the confirmation popup appears, click the green Yes, install it button.
Upon completion, click the orange Configure button.

NOTE: Version shown may be different depending on the release of AbleCommerce you are using.

Register an App (O Auth) with UPS

In order to use UPS, you must have a shipping account with them. You will also need to create a developer account, assign your shipping account, and include Apps to obtain the OAuth Login credentials and services offered by UPS.

After installing, go to the Configure > Shipping > Carriers page from the admin menu.
Any installed shipping carriers will be available from this page. Click the blue plus (+) button or linked name to continue to the registration page.

Carefully read the on-screen instructions before continuing.
If you don't have an existing shipping account, register with UPS at https://www.ups.com/one-to-one/register
Once registered, you should receive an email containing the information needed to complete this registration.
Make sure your account is activated by UPS, and save your Account Number for the registration page.
To obtain the Client ID and Client Secret codes, click this link to Get Started (opens in new window)

If you have an existing developer account, login. If not, then Register for access to UPS's APIs.
Once logged in to the UPS developer portal https://developer.ups.com find the My Apps page.
Create a new App using these answer to the questions:

I need API credentials because I want to integrate UPS technology into my business.
Choose an account to associate with these credentials. Select your existing account number. If you don't have one, the form allows you to create a new one.
Enter the primary contact information in the form provided.
Enter an App Name in the field provided. (e.g. AbleCommerce)
Leave the Callback URL field blank.
Add the following 5 API Products:

Authorization (O Auth)
Address Validation - required for AVS
Rating - required to use UPS Labels
Shipping - required for live shipping rates
Tracking - required for tracking services

Once the App is created, the OAuth login credentials will be available.

From the My Apps page, you can see your new app and edit it to view the OAuth API credentials at any time.
From the section shown above, you will need to view/copy the Client ID and Client Secret keys to complete the AbleCommerce UPS Shipping registration.
You will also be able to view the API products that should be available to your new UPS App.

Return to the UPS Shipping Registration page, and enter the Client ID, Client Secret, and your UPS Account Number into the fields provided.
Click the Next button to continue, or CANCEL to quit and return to the previous menu.
After completing the App registration process, you will be on the Configure UPS page as shown in the next section.

Configure UPS Shipping

You must use a warehouse with an address supported from the UPS account.

From Configure > Shipping > Carriers page, click the EDIT icon for UPS. This will bring you to the Configuration page.

The UPS Client ID, Client Secret and Account Number previously entered are shown in the first three fields. These elements can only be used by the UPS App previously setup on the UPS developer's website.

Note: The UPS Account Number is necessary if you wish to offer negotiated (discounted) shipping rates, AVS, or the print labels feature.
Review and choose the appropriate Customer Type which should match your UPS account. This type of shipping determines which rates will be shown to your customers. An incorrect setting for Customer Type will result in less accurate rate estimates.

Note: If you want to use negotiated rates, you must contact UPS and make sure your account qualifies.
Enable Address Validation is an optional service that can be used when a customer enters an address during checkout. If a better address can be suggested to the customer, they will see an alternate address and be allowed to use the suggested one, or keep the address as entered. Check the box to enable this feature.

- Requires that you have an UPS Account entered on the configuration page.
- You should not activate more than one Address Validation Service within AbleCommerce.
If you have an established an account with UPS, you can use the printing label feature to generate tracking numbers and labels. Check the box next to Enable Printing of Labels.
The Optional Insurance option can include shipping insurance with the shipping amounts. When enabled, all real-time rates will reflect the additional cost (if any) for insurance. If you want the estimated rate to include insurance, check the box for it. When this option is checked, AbleCommerce sends the value of the shipment to the service rate provider. Most shipping services already provide insurance up to a certain amount. The default setting is 'No', or unchecked.
The Enable Package Breakup option is checked by default. This allows a shipment to be split into multiple parts if the total order weight exceeds the maximum amount. This will not change the number of shipments in the order, only the calculation to determine the most accurate shipping costs.
The Maximum Weight is this carriers limit for a package. The default value is 150 lbs.
The Minimum Weight is the amount used when the order weight does not meet the minimum. The default value is 0.10 lb.
The URL settings come pre-configured when you create the shipping account through AbleCommerce. These URL's can change so the fields are available for modification. It is not advisable to modify the URL's here unless specifically instructed to do so.

Rating URL: The URL to which requests are posted in Live mode.

Test Server URL: The URL to which requests are posted in Test Mode.

Tracking URL: The URL to which requests are sent for package tracking. {0} is substituted with the tracking number at the time of request.
The Mode settings are used to enable/disable rates from the test server. Debugging can also be enabled which can help with any communication problems.

Test Mode: When Test Mode is enabled, rate requests are sent to test server using the Test Mode URL.

Debug Mode: When debug mode is enabled, all messages sent to and received from UPS are logged. This should only be enabled at the direction of qualified support personnel.

Default Log File Location: ..\App_Data\Logs\[gatewayname].log
After making any changes, click the SAVE button. To complete the shipping carrier setup, see Adding or Removing Shipping Methods in the next section.
Or, you can click the SAVE AND CLOSE button to return to the Shipping Carriers page.

Adding or Removing Shipping Methods

Configuring Shipping Services for UPS

You must select the services you want to be available to your customers. Each service (shipping method) is configured separately once it's added.

In the bottom section of the page, you will see the Shipping Method menu. This is a list of all services offered by the provider. You should review the entire list of shipping services offered and decide which ones you want to make available as shipping options in your store.
You can use the buttons from the Action column to individually Add or Edit the shipping method.
Check the box next to one or more shipping methods, or check the box at the top of the first column to quickly select all methods.
This will activate the Update button, which will drop-down to provide 2 options: either Add or Remove the selected methods.

The update will take place immediately after selection.
In this example, we will add and configure the "UPS Ground" service. Check the box next to all others you want to offer as a shipping service.
Using the Update button, select the option Add selected methods.
The selected shipping services now appear at the top of the list and each will be linked for configuration.
To remove an individual shipping method, use the Remove button in the Action column, or you can select multiple methods by checking the box in the first column and activating the Update button which will give you the option to select Remove selected methods. The update will take place immediately after selection.

Configure a Shipping Method

Each shipping method will use its own configuration settings. To configure a shipping service, click the EDIT button to view the Configure page.
The above example shows the default configuration values for all shipping services that are added.
Change the Shipping Method Name if needed. This is the name that will be displayed to the customer and the merchant on all invoices and receipts.

Note: Most third-party carriers do not want the names of their shipping methods changed.
If these shipping charges are taxable, then select a Shipping Tax Code. Make sure you understand the tax laws according to your local tax authority.
Taxes on shipping charges are combined with any other taxes calculated for the shipment.
Use the Handling Fee field to include a charge for handling or processing. The handling fee can be a fixed amount, percent of the shipping charge, or a percentage of the shipment total. After entering the amount, select one of these three options available.
There is a display option to either show the Handing Fee included in the shipping cost, which will hide the amount in the shipping cost. Or to show the handling fee separately, where it will be displayed as a separate line item on the invoice. If you show the handling fee separately, you may then select a Handling Tax Code if you are required to collect tax on this type of charge.
The Minimum Purchase field is the designated minimum value of a shipment before this shipping method will be available. Until this limit is met, the shipping method will not display.
A minimum purchase value applies to the total of each shipment, not the total of the order.
The Maximum Purchase field is the designated maximum value of a shipment before this shipping method will be available. If this limit is exceeded, the shipping method will not display.
A maximum purchase value applies to the total of each shipment, not the total of the order.
When finished making changes, be sure to Save.

Additional Settings

There are three optional configurations which can be used to filter shipping methods that are shown to the customer.

These additional settings allow you to display available shipping methods according to the shipping groups (used for custom shipping conditions and locations where products are shipped from), the zones (regions the products are shipped to), and/or any groups that a customer is assigned to. By default, every new method added will use all available destinations, special shipping conditions, and user groups. To make shipping methods explicit to any of these criteria, follow the steps given below.

Shipping with Ship Groups

Ship Groups are typically used for products that have special shipping requirements, such as perishables, oversized, or overweight. You can also define the shipping origin.

To setup Ship Groups, go to Configure > Shipping > Ship Groups using the menu.

If this shipping service needs to be applied to a specific warehouse(s), then you will need to setup Ship Groups first. The warehouse determines the origin of shipping, and ship groups allows you to choose specific warehouses and define which shipping methods and products will be available to them.
A warehouse determines the shipping origin.
If this shipping method will be allowed from all locations and types, then keep the default All Ship Groups option selected.

Shipping with Zones

Zones allow you to configure specific places for use with many features, including shipping methods.

To setup Zones, go to Configure > Regions > Zones using the menu.

If the shipping service applies to a specific Zone(s), select it from the Selected Zones list.
A zone determines the shipping destination.
If the shipping service applies to all ship to locations, then keep the default All Zones option selected.

Shipping with User Groups

When you apply a shipping service to a user group, then it will only appear for the users who are logged in as members of that group.

To setup User Groups, go to People > Users > User Groups for regular customers. To setup User Groups for administrators only, go to People > Admins > Admin Groups.

If the shipping service applies to a specific User Group or Admin Group, select it from the Selected Groups list.
If the shipping service applies to everyone, admin and customers alike, then keep the default All Groups option selected.
When finished configuring this shipping method, press the Save button to continue.

Configuring Additional Services for UPS

At the bottom of the Configure Shipping Carrier page, there will be a list of service names for the selected carrier.
When finished configuring a shipping method service, you may want to Save and then select another service type to configure.
After you have completed all configurations, press the Save and Close button to return to the list of all methods. This will include all shipping methods for all carriers any custom methods you have created.
This will bring you back to the Shipping Methods page which displays all configured shipping service types available for the store.
The Type column displays the shipping service and any custom methods in place.
Additional columns are shown for Ship Groups, Zones, and User Groups. Each of these features are documented separately.
From this page, you can add, sort, remove and configure all shipping methods.
To add a new shipping carrier, go to the Plugins page using the menu. You may have as many services and combinations of shipping carriers as needed.

Troubleshooting Techniques

Use this quick guide if the shipping methods are not appearing during the checkout process.

Confirm your product(s) are shippable and have a weight. Some carriers require dimensions as well. This information is found within the Shipping and Tax section of the Edit Product page.
Confirm you warehouse (the shipping origin) has a valid address for the carrier. Go to Configure > Shipping > Warehouses to check address information. On the same page, you will be able to find all the products assigned to this warehouse.
Confirm you are shipping to a valid address for the method. For example, some shipping methods will only appear if they are within a particular country or state. Another example, ground transportation is not available to Hawaii from the mainland United States.
If the carrier requires an account number or key, confirm the information is correct from the applicable service carrier's configuration page. This information is found under the Configure > Shipping > Carriers page.
Check the available shipping services you have configured and make certain they have the correct ship groups or zones defined for the package and address delivery. This step applies if you have configured special shipping situations using Ship Groups and/or Zones.
From the configuration page of the carrier, there is a checkbox to enable Debug Mode. Only use this feature if all steps above have been confirmed. Once debug is enabled, test a shipment calculation through the checkout process. This will log an entry.
Then you will need to access the debug log file which is located on the server in the following location ...\website\App_Data\logs\*carrier name*.log
Open the file and carefully review the data that was SENT and RECEIVED. In the received response, there should be a message or error indicating the reason the shipping method did not calculate on the shipment received. If needed, provide this information to technical support.
When finished troubleshooting, make sure to turn OFF debug mode.

Successful Shipping Rates

When the shipping carrier is setup correctly, the user should see the selected shipping methods and rates on the /Checkout/ShipMethod page: