UPS Setup
The following instructions apply to setting up integration credentials for the UPS REST API integration. The UPS REST API integration is native in Znode versions 9.9 and later.
Step A: Access the UPS REST API Developer Portal
The UPS REST API Developer Portal can be found at https://developer.ups.com/.
Login with an existing UPS REST API Developer Portal account or follow the instructions at https://developer.ups.com/get-started (under Step 4 - Developer Access) to set up a developer account.
If your organization already has a UPS Developer Portal account, please consult your internal team to determine whether a new account should be created. New applications can be added to existing developer accounts if desired.
Step B: Create a Developer Portal App
After you log in, follow Step 5 - Obtain Your OAuth Credentials instructions of the “Getting Started with UPS APIs” instructions to set up an “App” and to obtain integration credentials.
When prompted for the Use Case, please make the following selection.
Identify the account number to be associated with the application being created, review and accept the terms, then select “Next”.
Heed the following warning prior to completing the “Who should we contact?” screen. There is additional guidance noted in the “Getting Started” documentation.
Complete the requested information on the “Who should we contact?” screen then select “Next”. You will be directed to the “Add App” screen to configure the application that will be using the APIs.
Under the “Apps Details” header,
Enter a value for the “App Name”. This value names the software that is connecting to the UPS APIs under the selected account number.
IMPORTANT: If you currently have two UPS account numbers in use - one for non-LTL UPS shipments and one for LTL UPS shipments - you will need to create two UPS apps. Znode recommends selecting an App Name value that allows easy identification between LTL and non-LTL.
Leave the “Callback URL” blank.
If the “Billing Account Number” is not selected, select the account number to be billed for shipments under the forthcoming assigned API credentials.
IMPORTANT: If you currently have two UPS account numbers - LTL and non-LTL - you will need to create two UPS apps. One of the apps should have the LTL account number, and the other app should have the non-LTL account number.
Under the “Add Products” header, the Authorization product should automatically be selected. If it is not selected, please select it.
Select the “Address Validation” product.
If you will be using UPS (TForce) Freight LTL services, select the “TForce Rating” product.
If you will be using UPS non-LTL services, please select both the “Rating” and “Time In Transit” products.
As your product selections are made, a list of “Products Included In This App” is generated on the left side of the screen.
Validate this list contains the needed products and select “Save”.
An “App” should be created upon completion of these steps. The API keys should now be assigned and the (API) products approved for use. If the API Products have a status of “Pending”, it should take only a few minutes for the approval process to complete.
Step C: Test vs Production Credentials
UPS credentials generated during the app creation may be used in the test (aka CIE - Customer Integration Environment) and production environments. There are no credential values specific to each environment; just one set of credentials. Configuration of the URL address of where estimate requests are sent is the mechanism of control for which environment is being used.
Step D: Configure Znode UPS Shipping
The following instructions apply to configuring either the test or production environments.
If requests should be sent to UPS’s test (i.e. CIE - Customer Integration Environment) environment, configure Znode for testing purposes.
If requests should be sent to UPS’s production environment, configure Znode for production purposes.
Step D.1: UPS Integration Credentials (UPS Developer Portal)
The credential values to be input into the Znode admin must be obtained from the UPS Developer Portal.
UPS Account Number. The value under the “Billing Account number” heading is associated with the Client ID-Client Secret pair in the Developer Portal.
Client ID. The value associated with the “Client ID” heading for the UPS app in the Developer Portal.
Client Secret. The value associated with the “Client Secret” heading for the UPS app in the Developer Portal.
If you have a separate account number for LTL shipping requests, a second UPS app should be created.
Step D.2: Configure UPS Environment in Znode
The URL is the UPS “address” where Znode will send requests for shipping estimates.
The UPS environment URLs are configured in the web.config file along with the indicator that determines test versus production environment usage. The below values should already be configured for you, however, please verify the values in accordance with the instructions herein.
web.config file Snippet
The “UPSRestGatewayBaseURL” value should match the UPS Test URL value.
The “UPSRestProductionBaseURL” value should match the UPS Production URL value.
The “IsUPSRestGatewayTest” value identifies whether Znode should be sending requests to the UPS test or production environment. A value of “true” will direct requests to the UPStest environment. A value of “false” will direct requests to the UPS production environment.
Step D.3: Configure UPS Credentials in Znode
This configuration is needed for each store that uses UPS shipping.
In the Znode Admin, browse to the “Stores & Reps” > “Stores” > “Shipping Origin” screen and scroll to the “UPS” section.
The following configuration fields apply to the non-LTL shipping account.
UPS Client ID. The value associated with the “Client ID” heading for the non-LTL “Billing Account number” value.
UPS Client Secret. The value associated with the “Client Secret” heading for the non-LTL “Billing Account number” value.
UPS Account Number. The value under the “Billing Account number” heading is associated with the UPS Client ID - Client Secret pair used for non-LTL requests.
The following configuration fields apply to the LTL shipping account. If you do not use UPS LTL shipping, these fields can be left blank. If your LTL account number is the same as your non-LTL account number, please repeat the same information into the LTL shipping fields as entered in the non-LTL shipping fields.
UPS LTL Account Number. The value under the “Billing Account number” heading is associated with the UPS Client ID - Client Secret pair used for LTL requests.
UPS LTL Client ID. The value associated with the “Client ID” heading for the LTL “Billing Account number” value.
UPS LTL Client Secret. The value associated with the “Client Secret” heading for the LTL “Billing Account number” value.
Shipment Drop-Off Type. Formerly labeled “Select UPS Drop-Off Type”. No changes have been made to this functionality.
Packaging Type. Formerly labeled “Select UPS Packaging Type”. No changes have been made to this functionality.
UPS Integration FAQs
Do I need new business account numbers?
No! The existing business account numbers you have with your shipping vendors should remain the same. The technical logins and credentials created as part of these documented instructions should be tied to your existing business account numbers.
What are key configurations that need modification when converting from test to production environments?
Converting the native Znode installation from test to production shipping vendor environments, the following are key configuration activities that need to be completed.
If you use UPS, update the web.config file “IsUPSRestGatewayTest” value to “false” to indicate UPS requests should be sent to the production UPS environment. (Refer to Step D.2: Configure UPS Environment in Znode)
That’s it! UPS does not have separate credentials for test versus production environments, so the setup completed in Step D.3: Configure UPS Credentials in Znode can remain the same.
See the UPS “Step 7 - Move to Production” documentation.
How do I associate multiple account numbers with my Developer Portal UPS App?
UPS does not allow you to associate more than one “Billing Account number” to a UPS App.
Znode recommends creating at least one UPS App specific to Znode’s connection to UPS. The UPS App should be associated with your existing UPS business account number.
You will need to create additional UPS Apps for Znode if you have separate business account numbers for LTL and non-LTL shipping. Znode natively supports two UPS Apps - one tied to non-LTL and one tied to LTL.
If you do not already have a separate LTL business account number, you do not need to have one created. You may continue using a single business account number (and subsequently a single UPS App) for both LTL and non-LTL.
What is another name for UPS’s test environment?
UPS refers to its test environment as the “Customer Integration Environment” or “CIE” environment.