Troubleshooting
"Test connection" Fails
- Double-check the Client ID/Secret were copied without extra spaces.
- Confirm the Environment dropdown (Production vs. Sandbox) matches the credentials you generated - sandbox credentials will not authenticate against production.
- Enable Debug mode (Advanced tab) and check the logged response for the carrier's exact error message.
USPS Label Errors
| Error | Cause and fix |
|---|---|
| "USPS label creation needs your CRID, Mailer ID (MID) and EPS account number." | Enter all three on the USPS tab. See Payment account |
| "... (Insufficient OAuth scope.)" | Your USPS app doesn't have Labels API access yet. Request it from USPS |
| "USPS payment authorization failed. Check your CRID, MID and EPS account number." | One of the three is wrong - the EPS field needs your EPS account number, not your USPS.com / Click-N-Ship account number |
| "Flat Rate packaging isn't available for ..." | The package type doesn't exist for that service. Choose Priority Mail (or Express for the envelope), or Your Packaging |
FedEx Label Errors
| Error | Cause and fix |
|---|---|
| "We could not authorize your credentials..." | The FedEx API for that feature isn't added to your FedEx project. See APIs your FedEx project needs |
| "International shipments need at least one physical product..." | International labels declare the order's physical items for customs; the order has none |
Any Label Purchase Rejected
- Validate your shipper address on the Shipper address tab - an invalid origin address fails every label purchase.
- Check the weight in the order panel - it's calculated from product weights, so products without a weight make it too low.
- Enable Debug mode and check the carrier's full response.
Address Validation Fails
- USPS - "not authorized for access to Addresses API" means your USPS account needs an Addresses API license. See USPS address validation.
- FedEx - an authorization error means the Address Validation API isn't added to your FedEx project.
Live Rates Not Showing at Checkout
- Confirm the carrier is Enabled on its settings tab and Test connection succeeds.
- Confirm your shipper address has a ZIP code, and the customer has entered a postcode.
- Confirm the shipping method was added to the relevant shipping zone under WooCommerce → Settings → Shipping, and the services you expect are ticked in Show services.
- USPS checkout quotes only the Default service from the USPS tab - make sure that service is ticked in Show services.
- Rate results are cached for 30 minutes - change the cart contents or wait for the cache to expire when testing rate changes.
Tracking Not Updating
- Confirm the
shiplabel_sync_tracking_statusescron event is scheduled:wp cron event list | grep shiplabel. - WP-Cron only fires on site visits by default - on low-traffic stores, set up a real system cron hitting
wp-cron.php. - For FedEx, confirm the Track API is added to your FedEx project.
- If you use the tracking webhook with a secret, confirm the sender signs requests with exactly the secret saved on the Advanced tab.
"Your session has expired" Message
ShipLabel refreshes its security tokens automatically while an admin page stays open, so actions keep working. If you still see "Your session has expired. Please reload the page and try again.", you've been logged out of WordPress - log in again and reload the page.
"Download label" Shows "rest_forbidden"
Download links are tied to your login session and expire after about a day. Reload the order or Label history page to get fresh links. (Versions before 1.1.0 always failed here - update ShipLabel.)
Enable Debug mode on the Advanced tab for full carrier API request/response logging when diagnosing any of the issues above. Turn it off again once resolved - the logs contain customer addresses.