Waybill for Jira

Getting carrier API credentials

How to get free API credentials from UPS, FedEx, USPS and DHL, step by step.

Waybill does not include any carrier credentials. Each Jira site uses its own, which are free for tracking at normal volumes. You only need to set up the carriers you actually ship with, and you can add more later. Only Jira administrators can enter credentials, on the Carrier credentials tab under Jira settings → Apps → Waybill.

Carrier websites change their sign-up screens from time to time. The steps below describe the general path; if a button is named differently, look for the closest match.

Before you start

  • Use a company email address and profile for every developer account. Some carriers reject personal or incomplete profiles.
  • You want production credentials, not sandbox or test ones. Test credentials do not return real shipments.
  • Keep the Client ID/Key and the Secret somewhere safe. Most carriers show the secret only once.
  • After entering credentials in the app, press Verify & save. If the carrier rejects them, the app tells you and does not save them.

UPS

You need: Client ID and Client Secret.

  1. Go to developer.ups.com and log in with a UPS.com profile. If you do not have one, create one first at ups.com (a UPS account number can be linked but is not always required for tracking).
  2. Open Apps and choose to Add Apps (create an application).
  3. When asked what you want to do, choose the option for integrating UPS with your own business systems.
  4. Give the app a name (for example "Waybill for Jira"), and select your UPS account or business details if asked.
  5. Add the Tracking product to the application. You can leave other products off.
  6. Save the application. Copy the Client ID and Client Secret.
  7. In Jira, paste them into the UPS section and press Verify & save.

Notes:

  • UPS uses OAuth. The app manages tokens for you.
  • If the app says UPS rejected the credentials, confirm the Tracking product is added and the application is in a production (not testing) state.

FedEx

You need: API Key and Secret Key.

  1. Go to developer.fedex.com and choose Log in / Sign up. Sign in with a FedEx.com profile, or create one.
  2. Choose that you are a FedEx shipper integrating FedEx APIs into your own application (not an integrator or reseller).
  3. Create an organization/company profile if asked, and accept the terms.
  4. Go to My Projects and create a new project.
  5. Select the Track API (Track by tracking number) for the project.
  6. Complete the project's setup, then open it and find the production API Key and Secret Key. Sandbox keys may also be shown; do not use those.
  7. In Jira, paste them into the FedEx section as API Key and Secret Key, then press Verify & save.

Notes:

  • FedEx may ask for a FedEx account number when a project moves to production. Use your company's account.
  • New production keys can take a few minutes to become active.

USPS

Status: not yet verified against live shipments. USPS support is built to USPS's published tracking API, but has not been tested with real shipments. It should work; if lookups fail or look wrong, please contact support.

You need: Consumer Key and Consumer Secret.

  1. Go to developers.usps.com and follow the link to the USPS Customer Onboarding Portal (COP). Sign in or create a business account. This registers your business for API access.
  2. In the COP business portal, open My Apps and create a new application.
  3. Open the application's settings and find the Credentials section. Copy the Consumer Key and Consumer Secret.
  4. The Tracking API is included with the default access. If tracking is not available for your app, contact USPS support through their API service request form.
  5. In Jira, paste the key and secret into the USPS section and press Verify & save.

Notes:

  • USPS applies a default request quota to new applications. Ask USPS for an increase if you track a large volume.
  • The USPS "TEM" test environment is not used by this app.

DHL

Status: not yet verified against live shipments. DHL support is built to DHL's published tracking API, but has not been tested with real shipments. It should work; if lookups fail or look wrong, please contact support.

You need: API Key.

  1. Go to developer.dhl.com and register with your company email. Fill in a real company name in your profile; DHL checks this and rejects profiles that look automated or personal.
  2. Find the Shipment Tracking - Unified API and choose to create an app (or add the API to an existing app).
  3. Request access to the API. Approval is not always instant while DHL verifies your profile.
  4. When approved, open your user dashboard (developer.dhl.com/user/apps), select your app, find the API under Credentials, and choose Show to reveal the Consumer Key. This is the API key.
  5. In Jira, paste it into the DHL section and press Verify & save.

Notes:

  • The initial free service level allows about 250 requests per day and one request every 5 seconds. That is enough for testing and small volumes. For more, request a higher service level from DHL.
  • The API covers DHL Express, eCommerce, Freight and other DHL divisions.
  • If you track many DHL shipments, choose a longer refresh interval so you stay within the daily limit.
  • Waybill spaces DHL requests at least 5 seconds apart to respect the one-request-every-5-seconds limit, and pauses DHL lookups for a while if DHL reports the limit has been reached.

Rotating or removing credentials

To replace credentials, type the new values in that carrier's section and press Verify & save. To stop using a carrier, press Remove. Work items using that carrier will show "Carrier Not Configured" the next time they refresh.