VibeFox USPS for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

USPS Developer Portal app (for live rates only): sign in to the USPS Developer Portal (developers.usps.com) with a free USPS business account, create an app and copy its Consumer Key and Consumer Secret. The plugin uses the current USPS APIs with OAuth 2.0. USPS shut down the old Web Tools API (User ID and XML) on 25 January 2026, so a Web Tools User ID does not work any more. Without keys, only the fixed prices are used.

Ship-from ZIP code: live rates need the 5-digit US ZIP code the parcels are mailed from.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_usps folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox USPS, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the Consumer Key and Consumer Secret, the 5-digit Ship from ZIP code and choose the services. If your store currency is not USD, enter the USD exchange rate.

6. Add VibeFox USPS to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

7. Optionally enter fixed prices as a fallback.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox USPS. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name of this option at checkout. Leave it empty to use the global Name.

Every time you save the settings, the cached USPS token and rates are cleared. You can also click Clear cached USPS token and rates in the USPS API section. Warnings above the settings tell you when only one of the keys is set, there are no keys and no fixed prices, the ship-from ZIP code is missing, no service is selected, the USD exchange rate is missing, or the test environment is on.

General

Enable/Disable: turns the method on or off in all zones at once.

Name: the shipping method name shown at checkout. Default: USPS.

Tax status: USPS prices do not include taxes. Taxable lets WooCommerce add its shipping tax to the cost, None does not.

USPS API (live rates)

Consumer Key: the Consumer Key (client_id) of your USPS developer app.

Consumer Secret: the Consumer Secret (client_secret) of the same app.

Test environment: use the USPS Testing Environment for Mailers. Only for apps that have access to it. Leave it off for real prices. Default: off.

Prices: which USPS prices are used.

Services: the USPS services that may be offered. The cheapest selected service USPS offers for the parcel is shown. Flat Rate, Cubic, Hold for Pickup and Sunday prices are never used. Default: USPS Ground Advantage, Priority Mail and First-Class Package International Service.

USD exchange rate: USPS prices are in USD. If your store currency is not USD, enter the price of 1 USD in your store currency, for example 0.92. Without it, live rates are not used and the fixed prices apply. Not needed when the store currency is USD.

Ship from and parcel (USPS prices depend on the origin ZIP code, the weight and the parcel size)

Ship from ZIP code: the 5-digit US ZIP code the parcels are mailed from. A ZIP+4 code is cut to 5 digits. Other values are rejected with a message.

Box size: optional box dimensions in your store dimension unit, for example 30x20x15. Leave it empty to build the size from the product dimensions: the longest length, the widest width and the heights stacked. If a product has no dimensions, a 10 x 8 x 4 inch box is used.

Default product weight (kg): the weight used for products without a weight, in USPS rates, weight limits and weight tiers. Default: 0.5.

Fixed prices (prices in your store currency; used when no API keys are entered and as a fallback when USPS returns no rate: API down, wrong keys, no service or a destination without a US ZIP code; leave both empty to hide the method in that case)

Country prices: prices by destination country and cart weight. Click + Add country to add a row and the cross to remove one. The columns are Price and the weight tiers XS (up to 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) and XL (over 5 kg). An empty or 0 tier uses Price. The row * Default applies to any other country. Values that are not numbers are cleared with a message.

Fallback cost: a flat price when no country price matches. Leave it empty to hide the method in that case.

Fixed price is: Per order charges the price once. Per item (each item priced by its own weight x quantity) prices every item by its own weight (the default weight when it has none) and multiplies it by its quantity. USPS live rates are always quoted for the whole parcel.

Conditions

Free shipping from: the cart subtotal from which this method is free. No request goes to USPS then. Leave it empty to never offer free shipping.

Minimum subtotal: show the method only when the cart subtotal is at least this amount. Leave it empty to always show it.

Min weight (kg): the minimum cart weight for this method to appear. 0 means no limit.

Max weight (kg): the method is hidden above this cart weight. Default: 30. USPS accepts up to 70 lb (31.7 kg). 0 means no limit.

Excluded shipping classes: hide the method if the cart contains a product from any of these WooCommerce shipping classes.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below even without adding it to a shipping zone.

Countries: the destination countries for that mode. Leave empty to use all shipping countries of the store. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs API requests and rate calculation to WooCommerce > Status > Logs, source vfd-usps. API errors are always logged, even when this option is off. Keys, tokens and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes all plugin settings and zone methods. Deactivating never deletes settings.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: cart weight, minimum subtotal and excluded shipping classes. If free shipping applies, the method is shown with a price of 0 and no request goes to USPS.

The plugin gets an OAuth token from USPS and keeps it until it expires. A token that USPS rejects is renewed and the quote repeated. For destinations in the US and its territories (including Puerto Rico, the US Virgin Islands and Guam) it asks the Domestic Prices API and needs the customer's 5-digit ZIP code. For other countries it asks the International Prices API with the country and postal code.

The request contains the ship-from ZIP code, the cart weight in pounds, the parcel size in inches and the price type. Parcels over 70 lb get the fixed prices. The customer sees one option with the cheapest selected service, converted to your store currency.

Each quote is cached for 1 hour. A failed quote is remembered for 10 minutes. After a timeout, server error, rate limit or rejected keys, USPS is not called for 5 minutes. The HTTP timeout is 10 seconds. Deactivating the plugin clears the cached token and rates.

If USPS gives no rate, the price comes from Country prices, then from Fallback cost. If neither applies, the method is hidden. The customer never sees USPS error texts.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin calculates rates only. It does not buy postage or shipping labels, book pickups, track parcels or let customers choose a Post Office or pickup location. It shows one option, not several USPS services. There is no box packing: the cart is quoted as one parcel. Insurance and other extra services are not included.

Orders

For a live rate, the shipping line of the order stores the USPS service, for example USPS Ground Advantage. The shop manager sees it on the admin order screen.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox USPS. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, USPS is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

USPS does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum subtotal and Excluded shipping classes. Without working USPS keys the method needs a fixed price (Country prices or Fallback cost).

Live rates do not appear: check the warnings at the top of the settings page. Turn on Debug log and open WooCommerce > Status > Logs, source vfd-usps. Wrong keys, the wrong environment and USPS error messages are logged there. Domestic rates need the customer's 5-digit ZIP code.

My store is not in USD: USPS quotes only in USD. Enter USD exchange rate. Without it the live rate is not used and the fixed price is shown instead.

A Web Tools User ID does not work: the old Web Tools API is shut down. Create an app in the USPS Developer Portal and use its Consumer Key and Consumer Secret.

Rates look outdated after a change: the cache is cleared when you save the settings. You can also click Clear cached USPS token and rates.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps the settings and only clears the cached token and rates. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached token and rates are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

USPS is a trademark of its respective owner. This plugin is not affiliated with or endorsed by USPS.