Register an Application with UPS
Effective June 3, 2024, UPS requires a new method of authentication to communicate with their API which replaces the previous access key based method. All versions of starting with 2.10.0 support this new method of authentication.
To utilize this new authentication mechanism, you are required to use the UPS website to create an “application” which will then provide you with a pair of credentials known as a “Client ID” and a “Client Secret”. These two values are mixed case alphanumeric strings 48-64 characters long. You will need to save the Client ID and Client Secret, and use them with the WRKUPSAUTH Command to allow UPSTI to authenticate and access the UPS API.
Below are the steps required to create an application and retrieve the required “Client ID” and “Client Secret” credentials.
-
Go to the UPS Developer portal and log in using your UPS.com credentials.
-
After logging in, a circle with the first letter of your username should be visible towards the top right of the page. Click it, and select “Apps” from the dropdown menu that appears.
-
If you have already created one or more applications previously, you should be taken to a page which lists all applications. You should click the “Add Apps” link on the bottom left.
NOTE: If you have not previously created an application, UPS.com may skip taking you to an empty list and will instead take you directly to the “Add Apps” page.
-
On the Add Apps page, UPS will ask you to select the reason you need API credentials. Select I want to integrate UPS technology into my business from the dropdown.
NOTE: If you select any other answer for this question, UPS will attempt to configure your application in a way that UPSTI is not compatible with.
UPS will also ask you to choose a UPS shipper account to associate with the credentials.
Once you’ve filled out the form, click Next.
-
UPS will then ask you to provide contact information for a Primary Contact. You will need to provide values for the First Name, Last Name, Country, Street Address, City, State, Zip Code, Email, and Phone number fields.
NOTE: Despite this form wanting a specific person’s contact info, UPS recommends that you use a “group inbox” for the email address for the primary contact as you cannot change the Primary Contact email address assigned to the application without losing access and being required to create a new application.
You can optionally specify a separate API Integration Owner, but this form currently appears to be partially broken with some of the fields not being labelled. You can also choose to add a secondary contact, but this form also appears partially broken. Lastly, a checkbox is present to allow you to subscribe to API Status and Update email alerts. We strongly recommend that you do so.
Once you’re done, click Next.
-
UPS will prompt you for an “App Name”. The value you choose doesn’t matter as it won’t be externally visible to anyone, but we do recommend that you make a note of whatever name you use, and use the same name when you configure UPSTI using the WRKUPSAUTH Command. UPS does not appear to have a name length limit, but their website handles the display of very long names poorly, and the WRKUPSAUTH Command only allows a name up to 32 characters long, so we recommend you limit your name accordingly.
NOTE: You can ignore the “Callback URL” field as it is not relevant to the method of authentication that UPSTI uses.
You should select a Billing Account Number from the UPS shipper accounts configured within your UPS.com account.
On the right side is a large Add Products section, with a multi-page list of different UPS Product APIs. Each UPS API will have a button on the right side that will either be a brown checkmark, or a yellow plus sign.
-
A brown checkmark indicates that the API is enabled for your application.
-
A yellow plus sign indicates that the API may be enabled for your application, but is not currently enabled.
This list controls which UPS APIs your credentials can access. Any credentials which has a yellow plus sign cannot be accessed with these credentials (though it’s possible to edit your application and add them later). Once you click a yellow plus sign, it will change to a brown checkmark, but even though the icon changes, UPS will not record the change until you click the Save button at the bottom of the page.
UPSTI relies on the UPS APIs in the list below, so you should ensure that each API in the list has a brown checkmark. By default, only Authorization (OAuth) will have a brown checkmark.
- Authorization (OAuth)
- Address Validation
- Rating
- Time in Transit
- Shipping
- Tracking
- Pickup
You should see these APIs appear in a list on the lower left side of the page with a status of “Pending” as each button changes to a brown checkmark. Once each of these APIs appears in that list, click the Save button.
-
-
Your UPS application should now be created successfully, and the Client ID and Client Secret can be viewed by clicking the small “eye” icon, and can be copied by clicking the “clipboard” icon. As previously mentioned, you will need the Client ID and Client Secret to complete the configuration of UPSTI using the WRKUPSAUTH Command.
NOTE: Currently the UPS website allows you to view the Client ID and Client Secret again after you leave this page, but this is very atypical (and insecure), so this behavior will hopefully change in the future. For this reason, we recommend securely documenting and storing these credentials somewhere according to your company’s policies rather than relying on being able to view them again via the UPS website in the future.
-
Use the WRKUPSAUTH Command to configure your application within UPSTI, and provide the Client ID and Client Secret you received in step 7.