Updating Your USPS Credentials in Spirit Sale (Migration to New USPS APIs)

Updating Your USPS Credentials in Spirit Sale (Migration to New USPS APIs)

Info

Who Does This Apply To

This information only applies to Spirit Sale stores still using the older USPS Web Tools (Legacy) API for live shipping rates.
You do NOT need to follow this guide if:
  1. You don't use USPS for shipping.
  2. You already migrated to the new USPS OAuth 2.0 API, or
  3. Your USPS Developer account was created after USPS adopted their new API, and
  4. Your USPS settings already show:
    1. Use USPS Legacy Server = OFF, and
    2. Your USPS Consumer Key and USPS Consumer Secret are entered and 
    3. USPS shipping options and rates are presented at checkout.
How to quickly check your USPS setup in Spirit Sale
  1. Log into your Spirit Sale Dashboard

  2. Go to Settings → Shipping Setup → USPS

  3. Look for the Use USPS Legacy Server toggle

    • If it is OFF, you are already using the new API

  4. Check if your Consumer Key and Consumer Secret fields are filled

If the Legacy toggle is OFF and credentials are present, no action is required.
You are already connected to the new USPS API.

Overview

USPS is retiring their older Web Tools API, which many Spirit Sale stores still use to load live shipping rates during checkout. USPS has already begun limiting parts of the Web Tools system, and merchants using the old API may notice:
  • Missing USPS shipping options
  • Checkout rate errors
  • Intermittent failures even though nothing changed in Spirit Sale
To ensure uninterrupted shipping rates, USPS now requires merchants to migrate to the new USPS APIs (OAuth 2.0).
Spirit Sale fully supports the new system, but each merchant must update their own USPS credentials through the USPS Developer Portal.
This article explains the full migration process.

Support Responsibilities (Important)

USPS is responsible for all API credential and migration issues

USPS controls:
  1. The USPS Developer Portal
  2. Consumer Key and Consumer Secret generation
  3. API activation and permissions
  4. Credential validation and errors
  5. Migration from Web Tools to the new USPS APIs
Because of this, only USPS can resolve issues with credentials, including invalid API keys, missing permissions, or portal errors.

Contact USPS API Technical Support at:

This is the correct contact for all authentication, migration, and credential issues.

Spirit Sale support is limited to platform configuration

We are happy to help with:
  1. Locating USPS settings inside Spirit Sale
  2. Ensuring your credential fields and toggle settings are correct
  3. Interpreting Spirit Sale error messages
  4. Diagnosing issues on the Spirit Sale side (e.g., UI, saving settings, API request handling)
However, Spirit Sale cannot fix, retrieve, reset, or validate your USPS credentials, and USPS will not allow us to act on your behalf.

Alert
Security Reminder
Do not send your USPS password, Consumer Key, or Consumer Secret to Spirit Sale Support.

Before You Begin: Important Notes

1. Spirit Sale Support cannot access your USPS credentials

For security reasons, do not send your USPS password, Consumer Key, or Consumer Secret to Spirit Sale Support.
You will enter these directly into your dashboard.

2. USPS migration is required

USPS controls this transition and requires merchants to update their own API access.

3. Ensure you have access to the USPS Developer Portal and have your USPS Developer account ready.

You will need access to your USPS Developer Account.

4. If your Spirit Sale store suddenly loses USPS rates…

It is likely due to USPS limiting parts of the Web Tools system. Migrating to the new API typically resolves this immediately.

Part 1 - Obtain Your New USPS API Credentials

To use the new USPS rating system, you must retrieve your USPS Consumer Key and USPS Consumer Secret.

Steps

  1. Visit the USPS Developer Portal
    (Search: “USPS APIs Developer Portal” in your browser.)
  2. Sign in or create a USPS Developer account.
  3. Create a new Application within the portal.
  4. Locate your:
    • Consumer Key 
    • Consumer Secret
  5. Copy both values for use in Spirit Sale.

Need Help Retrieving Your USPS Credentials?

If you encounter difficulty accessing or locating your USPS Consumer Key or Secret, contact:

USPS API Technical Support
apisupport@usps.gov

Suggested message:
Quote
“I am migrating from the USPS Web Tools API to the new USPS APIs (OAuth 2.0). I need assistance retrieving or generating my Consumer Key (Client ID) and Consumer Secret.”
USPS generally responds within 1–2 business days.

Part 2 - Update Your USPS Credentials Inside Spirit Sale

Once you have your new USPS credentials, follow the steps below to update your store:

Steps

  1. Log into your Spirit Sale Dashboard.
  2. Navigate to:
    Settings → Shipping Setup → USPS

  3. Toggle ON the option:
    “Use OAUTH2 Integration.”

  4. Toggle OFF the option:
    “Use USPS Legacy Server.”
    This enables Spirit Sale’s new USPS API connection.

  5. Enter your:
    • USPS Consumer Key
    • USPS Consumer Secret
  6. Click the green “Update” button to save your changes.
    Your new USPS settings will not take effect until this button is pressed.

What You Should See When You Click Update

Spirit Sale provides an immediate on-screen confirmation to let you know whether your USPS credentials were accepted:

If credentials are correct:
A message will appear in the bottom-right corner of the screen:
“Success: Carrier shipping configuration updated.”

If credentials are incorrect or USPS rejects them:
A warning box will appear at the top of the screen stating:
“Your credentials have been updated, but the carrier informs they are not valid. Please check them.”
If you see this warning, confirm your credentials and contact USPS if needed.


Part 3 - Verify Your USPS Rates Are Working

After updating your credentials:
  1. Go to your storefront.
  2. Add an item to the cart.
  3. Proceed to checkout and enter a valid U.S. shipping address.
  4. You should now see USPS options such as:
    • USPS Ground Advantage
    • USPS Priority Mail
    • USPS Priority Mail Express
If these appear correctly, your migration is complete.

Troubleshooting

If USPS rates do not appear:

1. Check your Spirit Sale settings
  • Ensure Use USPS Legacy Server is turned OFF.
  • Confirm you clicked the green Update button.
  • Look for the Success or Warning message.

2. Verify your USPS credentials
Make sure:
  • Your Consumer Key is correct
  • Your Consumer Secret is correct
3. Contact USPS API Support
If USPS continues rejecting your credentials, email:

Ask them to verify your application and API access.

Frequently Asked Questions (FAQ)

Do I need to migrate now?
Yes. USPS is phasing out Web Tools, and rate disruptions will increase until full retirement.

Can Spirit Sale migrate my USPS account?
No. USPS requires each merchant to manage credentials privately and directly.

What if I do not migrate?
USPS rates may stop working. You may temporarily use flat-rate or other carriers, but USPS live rates require the new API.



    • Related Articles

    • How to Create USPS API Credentials

      Overview This article walks you through the steps for creating USPS API credentials using the USPS Developer Portal↗. These credentials allow your your Spirit Sale stores to securely access USPS APIs for services such live shipping rates. Steps to ...

    • How to Set Up Your Stripe API Keys With Spirit Sale

      Overview Spirit Sale integrates directly with Stripe to process payments. To connect your store, you’ll need your live publishable key and live secret key from Stripe. Important Notes: Only standard live keys are supported. Restricted keys will not ...

    • How to Feature a Product in Spirit Sale

      1.) When logged into your Spirit Sale backend. Navigate to Store Fronts --> Stores. 2.) Then select the store where you want to select items to feature. 3.) Then select the Products tab 4.) Under Actions click the Edit button next to the product ...

    • How to add upcharges for optional designs on a product

      Either create a new product or find and open a product you would like to edit by going to Products --> Products from your Spirit Sale dashboard, then open a product. In the properties of a product click the Manage Variants tab. Under the Manage ...

    • Add Multiple Pickup Locations to Store

      From the Spirit Sale dashboard go to: Store Fronts --> Stores Find your store and click the Edit button. Under Store Details scroll down to the Shipping Methods section. Click the Edit button within the PICKUP AT LOCATION box. Type in the address of ...