Connect USPS: live rates, labels, and tracking

Get your Consumer Key and Consumer Secret from USPS Developer Portal, paste them into Integration, test, map services, and start rating and shipping.

The USPS connector gets rates, buys labels, and tracks shipments through the USPS APIs. One pair of OAuth credentials — Consumer Key and Consumer Secret — covers rates and tracking; buying labels additionally needs your USPS payment account identifiers.

Prerequisites#

• Access to USPS Developer Portal (developers.usps.com) and an app under Apps — your Consumer Key and Consumer Secret live on that app page.
• Decide the environment first: start with the test environment (TEM) before production.
• Rates and tracking only need the OAuth pair — no account field is needed for them.
• Before buying labels, have your USPS payment account identifiers ready: CRID, MID, and EPS. They are needed when you buy a label, not when you create this connection.

Get your credentials#

1. Go to USPS Developer Portal (developers.usps.com) → Apps → open your app.
2. On the app page, copy the Consumer Key. It is used as the OAuth client_id.
3. On the same app page, copy the Consumer Secret. It is used as the OAuth client_secret.
4. Save the Consumer Secret somewhere safe right away. If you lose it, generate a new one in USPS Developer Portal.

Fill it into Integration#

1. Open Integration → Connector Marketplace → USPS → New connection.
2. Consumer Key (client_id) — required: paste the Consumer Key from your app page in USPS Developer Portal. The field is labelled “Consumer Key” in the wizard.
3. Consumer Secret (client_secret) — required: paste the Consumer Secret from the same app page. It is encrypted at rest and never echoed back.
4. Use sandbox (sandbox) — optional: fill “true” to use the test environment TEM (apis-tem.usps.com). Leave it empty to use production (apis.usps.com).
5. CRID / MID / EPS — do not look for them here: they are payment account identifiers for buying labels, not fields in this connection wizard. Have them ready before you buy labels.

Test the connection#

Click Test connection. The test only exchanges your Consumer Key and Consumer Secret for an OAuth token to check the credentials work — it does not quote a rate, buy a label, or check tracking. A pass means the key, the secret, and the environment you picked match; if it fails, note the error and check the FAQ below before changing anything else.

Mapping / pick a template#

USPS needs no order mapping — it works on parcels, not orders. What you map here is carrier services: in the connection settings, pair each shipping service you use internally with the matching USPS service, and keep only the services you actually ship with enabled, so rate shopping only quotes services you really offer.

Activate#

After activation, the connection is available for rate shopping and label buying at ship time, and tracking updates come back and land on the shipment. Before your first real label, make sure your payment account identifiers (CRID / MID / EPS) are ready — the connection test does not check them. Watch the first few shipments in Runs / Logs before trusting it unattended.

FAQ#

Test fails with 401

The Consumer Key or Consumer Secret is wrong: the two values were swapped, or one was copied with a missing character or an extra space, so USPS rejects the token exchange.

Go back to USPS Developer Portal (developers.usps.com) → Apps → your app, copy the Consumer Key into the Consumer Key field and the Consumer Secret into the Consumer Secret field exactly as shown, then test again.

Test environment and production are mixed up

The environment and the credentials do not match: Use sandbox is filled with “true” so calls go to the test environment TEM, but you are testing as if it were production — or Use sandbox is empty for production while you still expect test behaviour.

Make the setting match what you want to test, then test again: for the test environment fill Use sandbox with “true”; for production leave Use sandbox empty. Keep test and production as separate connections if you use both.

Test passes but buying a label fails

This is expected when the payment side is not ready: the test only checks the OAuth exchange for rates and tracking, while buying a label additionally needs your USPS payment account identifiers — CRID, MID, and EPS.

Prepare your CRID, MID, and EPS before buying labels — they are not connection wizard fields, so a passed test does not cover them. Once they are ready, try buying the label again and check the error in Runs / Logs if it still fails.

Label bought but tracking never updates

Tracking updates arrive on USPS’s schedule, not instantly, and a label that has not been handed to USPS yet has no movement to show.

Confirm the parcel has actually been handed over, then wait and check again. If nothing arrives after 24 hours, check Runs / Logs for tracking errors on that shipment.