Carrier credentials

What this is

When a supply partner's FedEx or UPS account is connected, tracking numbers reach ConsignTrak without anyone scanning or uploading them. FedEx sends a message the moment a label is created. ConsignTrak asks UPS for new labels about once a minute. Carrier credentials is where an Administrator connects each account. Each supply partner has one FedEx row and one UPS row.

What the office sees once it's working is on Automatic carrier updates.

Not yet tested against live carriers

These screens are documented from ConsignTrak itself. They haven't yet been used with a real FedEx or UPS account, because that needs the carriers' developer-portal sign-up to finish first. The steps on the carrier's side below are general directions, not a click-by-click guide. The shared demo used for this manual doesn't have carrier connections switched on, so this page has no screenshots.

Before you start

• Role: Administrator. Nobody else sees Carrier credentials.
• Settings: whoever hosts ConsignTrak must have switched carrier connections on for your site. If they haven't, the page shows an error instead of the list (see Common problems).
• You'll need:
  • The supply partner already set up in ConsignTrak.
  • Someone with access to that supply partner's account on the carrier's developer website: FedEx Developer Portal or UPS Developer Portal. That's usually the supply partner's own shipping or IT contact.
  • For UPS, the supply partner's UPS shipper number: the six-character account number printed on their UPS invoices and labels.
  • The ConsignTrak order number in the reference field of every label (Reference 1 in UPS software, Customer Reference in FedEx). That's how the carrier's report finds its order. Without it, reports arrive but don't match.

Step by step

Open the list

1. Open your account menu. Choose your initials in the top-right corner, then Carrier credentials.

2. Find the supply partner. The list has two rows per supply partner, one for FEDEX and one for UPS. A row nobody has set up says Not configured and offers Configure.

Connect FedEx

3. Get the secret from FedEx. In the FedEx Developer Portal, the supply partner's contact sets up an Advanced Integrated Visibility (AIV) webhook subscription for their shipping account. FedEx pairs that subscription with a shared secret, which FedEx uses to sign every message it sends. Copy that secret.

4. Choose Configure on the supply partner's FEDEX row. The FedEx credentials form opens with the supply partner's name and manufacturer code under the title.

5. Paste the secret into HMAC secret and choose Save credentials.

6. Copy the secret somewhere safe. The Carrier credentials saved page shows the secret once, with a Copy button. ConsignTrak keeps an encrypted copy but never shows it again.

7. Get the webhook address. Choose Back to edit. The form now shows a Webhook URL. Copy it into the FedEx AIV subscription as the address FedEx sends its messages to. Then choose Done or the back arrow.

Which way does the FedEx secret go?

The form says the secret is published by FedEx. The saved page says to register it in FedEx. Either way, the same value must be in both places. If FedEx lets you type your own secret, use the value you saved in ConsignTrak. We've asked for the wording to be made consistent.

Connect UPS

3. Get the app credentials from UPS. In the UPS Developer Portal, the supply partner's contact creates an app (or opens an existing one) with access to UPS tracking. Under Apps → Credentials, UPS shows a Client ID and a Client Secret. Copy both.

4. Choose Configure on the supply partner's UPS row.

5. Fill in the form:

   • OAuth client ID: the Client ID from UPS.
   • OAuth client secret: the Client Secret from UPS.
   • UPS Shipper Number: the supply partner's UPS account number.
   • Poll interval (seconds): how often to ask UPS. Leave it at 60 unless UPS has warned the supply partner about request limits.

6. Choose Save credentials. The saved page repeats the client ID, client secret and shipper number once, each with a Copy button. Nothing needs to go back to UPS; the values came from there. Choose Done.

Check it worked

There's no Test connection button. To check a new connection:

1. Ship an order for that supply partner through the carrier, with the order number in the label's reference field.
2. Open Carrier health from your account menu. Within a few minutes the supply partner's card should show a Last event time and turn Healthy. See Carrier health.
3. Open the order. Its Tracking section should show the box.

If the card shows Failing, the secret or the UPS credentials are wrong. Rotate them (below) with the right values.

Replace (rotate) credentials

Rotate when the supply partner changes its secret, when someone who knew it leaves, or when Carrier health shows signature or login failures.

1. Choose Edit on the row. A connected row says Edit instead of Configure.
2. Type the new values. Every field must be filled again. Secrets show as dots with "(enter to rotate)", and the UPS client ID shows its first four characters with "(enter to replace)". The shipper number and poll interval keep their current values.
3. Choose Rotate credentials. The button turns red and asks you to click again — click it a second time to confirm. The old values stop working at once, and the saved page shows the new ones one time.
4. For FedEx, update the webhook address. Rotating also changes the Webhook URL. Choose Back to edit, copy the new address, and replace the old one in the FedEx subscription. Until you do, FedEx's messages are refused.

Disconnect a carrier

1. Choose Edit on the row.
2. Choose Delete credentials in the red Danger zone box. The button turns red and asks you to click again — click it a second time to confirm.

ConsignTrak stops accepting that carrier's messages for that supply partner at once. Tracking can still come in by scanning or file import.

Every field and option

Carrier credentials list

Field or control	What it means	Required	Default	What changes when you set it
Carrier credentials (heading) and intro	Explains the page. The intro links to the manual tracking import for carriers other than FedEx and UPS.	—	—	The link opens Import tracking.
Supply partner	The supply partner's name and manufacturer code.	—	—	Read-only.
Carrier	FEDEX or UPS. Every supply partner has one row for each.	—	—	Read-only.
Status	Not configured: nothing saved. Configured: saved but not used yet. Healthy: used in the last hour. Stale: not used for over an hour. Decrypt failed or Error: the saved values can't be read (see Common problems).	—	Not configured	Read-only. For the fuller picture use Carrier health.
Last used	When FedEx last sent an accepted message, or when ConsignTrak last asked UPS successfully. "—" if never.	—	—	Read-only.
Poll interval	How often ConsignTrak asks UPS, in seconds. It also shows on FedEx rows, but FedEx sends its own messages, so it means nothing there.	—	—	Read-only; change it on the UPS form.
Configure / Edit	Opens the form for that row. Configure when nothing is saved, Edit when it is.	—	—	Opens the form.

FedEx credentials form

Field or control	What it means	Required	Default	What changes when you set it
← (back arrow)	Back to the list without saving.	—	—	Nothing saved.
HMAC secret	The shared secret for the supply partner's FedEx webhook subscription. FedEx signs each message with it, and ConsignTrak refuses any message whose signature doesn't match. Stored encrypted.	Yes	Empty; shows dots when saved	Saving or rotating replaces it.
Webhook URL	The address FedEx sends messages to. Appears only after the first save. Copy it into the FedEx subscription.	—	—	Read-only. Changes every time you rotate.
Save credentials	Saves a new connection. Shown only when nothing is saved yet.	—	—	Opens the saved page.
Rotate credentials	Replaces saved values. Click twice to confirm.	—	—	Old values stop working at once.
Cancel	Back to the list without saving.	—	—	Nothing saved.
Danger zone → Delete credentials	Disconnects this carrier for this supply partner. Click twice to confirm. Shown only when something is saved.	—	—	Messages are refused from then on.

UPS credentials form

Field or control	What it means	Required	Default	What changes when you set it
← (back arrow)	Back to the list without saving.	—	—	Nothing saved.
OAuth client ID	The Client ID of the supply partner's app in the UPS Developer Portal.	Yes	Empty; first four characters shown when saved	Saving or rotating replaces it.
OAuth client secret	The Client Secret of that app. Stored encrypted.	Yes	Empty; dots when saved	Saving or rotating replaces it.
UPS Shipper Number	The supply partner's UPS account number. ConsignTrak only asks about labels from this account; without it, UPS would answer for every account on the profile.	Yes	Empty; current value when saved	Changes which account ConsignTrak asks about.
Poll interval (seconds)	How long to wait between checks with UPS: 30 to 3600. ConsignTrak checks at most once a minute, so values under 60 behave like 60. Lower is fresher; higher uses fewer of the supply partner's UPS requests.	No	60	Takes effect from the next check.
Save credentials, Rotate credentials, Cancel, Danger zone → Delete credentials	As on the FedEx form.	—	—	As on the FedEx form.

Carrier credentials saved page

Field or control	What it means	Required	Default	What changes when you set it
This is the only time you will see these secrets	ConsignTrak never shows these values again. Keep a copy wherever the supply partner keeps its carrier secrets.	—	—	—
HMAC secret (FedEx)	The secret you just saved.	—	—	Read-only.
OAuth client ID, OAuth client secret (UPS)	The values you just saved.	—	—	Read-only.
Shipper number (UPS)	Shown to confirm. Not a secret.	—	—	Read-only.
Copy	Copies the value beside it.	—	—	Nothing saved.
Back to edit	Returns to the form. For FedEx, this is where the Webhook URL is.	—	—	—
Done / ←	Back to the list.	—	—	—

What happens next

• FedEx: each new label on that account makes FedEx send ConsignTrak a message. ConsignTrak checks the signature, finds the order and adds the box.
• UPS: about once a minute, ConsignTrak asks UPS about that supply partner's open orders and adds any boxes it finds.
• Every night, ConsignTrak compares each connected account with what it received that day. Anything it missed goes to the office's Pending tracking queue.
• Each save, rotate and delete is recorded in the audit trail with the Administrator's name.
• The supply partner's card on Carrier health changes from Not configured to Stale until the first message arrives, then Healthy.

Common problems

"carrier ingestion not configured (JWCOOLER_CARRIER_ENCRYPTION_KEY missing)" — Carrier connections aren't switched on where your ConsignTrak runs. Only whoever hosts ConsignTrak can fix this. Send them the message exactly as shown. Carrier health shows the same message.

"HMAC secret is required", "OAuth client ID is required", "OAuth client secret is required", "UPS Shipper Number is required (Tracking-by-reference scopes by shipper number)" — A required field was empty. Fill it and save again. When rotating, every field must be filled again, even ones that haven't changed.

"no existing credentials to rotate — use Save instead" — Someone deleted the credentials while the form was open. Go back to the list and choose Configure.

Status says Decrypt failed — ConsignTrak can't read the saved values, usually because the hosting setup changed. Open Edit, enter the values again from the carrier's portal, and choose Rotate credentials.

Saved, but Carrier health never shows a Last event — Check the label's reference field holds the ConsignTrak order number. For FedEx, check the webhook address in FedEx matches the one on the form, especially after a rotate. If both are right, ask whoever hosts ConsignTrak whether automatic carrier updates are switched on.

The supply partner uses another carrier — Only FedEx and UPS connect. For USPS, DHL or regional carriers, scan at shipping or import a file.

Watch the video

B30 · Connecting FedEx and UPS, and reading carrier health — this episode is not recorded yet.See all training videos