VibeFox USPS for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 module 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox USPS in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the Consumer Key and Consumer Secret, the 5-digit Ship from ZIP code and choose the services. If your shop default currency is not USD, enter the USD exchange rate. Optionally enter fixed prices as a fallback. Click Save.

On install the module creates the USPS carrier with the delivery time text Delivery by USPS. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox USPS > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached USPS token and rates.

A value that is not valid is not saved: the previous value stays and an error names the field, while the other fields are saved. Warnings at the top of the page tell you when only one of the keys is set, there are no keys and no fixed prices (the carrier is then never shown), the ship-from ZIP code is missing, no service is selected, the USD exchange rate is missing, the test environment is on, the shop weight or dimension unit is unknown (set it in International > Localization, Local units), or the USPS carrier was deleted.

General

Enable USPS shipping: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the carrier name shown to the customer at checkout. Default: USPS. Required, up to 64 characters.

Tax status: the tax rule of the carrier. USPS prices do not include taxes. Choose a tax rule to add shipping tax, or None if shipping is not taxed.

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. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. Clearing the Consumer Key removes the saved secret too.

Test environment: use the USPS Testing Environment for Mailers (apis-tem.usps.com). Only for apps that have access to it. Leave it off for real prices (apis.usps.com). 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. If no service is selected, live rates are not used.

USD exchange rate: USPS prices are in USD. If your shop default currency is not USD, enter the price of 1 USD in that currency, for example 0.92. Without it, live rates are not used and the fixed prices apply. Not needed when the default currency is USD. Must be greater than 0.

Cache: the button Clear cached USPS token and rates empties the cache at once. Quotes are cached for 1 hour, a failed quote for 10 minutes. After a timeout, server error, rate limit or rejected keys, USPS is not called for 5 minutes.

Ship from and parcel (USPS prices depend on the origin ZIP code, the weight and the parcel size; the cart is quoted as one parcel, and parcels over 70 lb use the fixed prices)

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 shop 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: the weight in kg used for products without a weight, in USPS rates, weight limits and weight tiers. Default: 0.5.

Fixed prices (prices in your shop default currency, tax excluded; 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 carrier in that case)

Country prices: prices by destination country and cart weight. Click Add country to add a row and the trash icon 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 (any other country) applies to any other country. A country row without any price sends that country to Fallback cost. 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 carrier in that case.

Fixed price is: Per order charges the price once, by the weight of the whole cart. Per item (each item priced by its own weight x quantity) prices every product by the weight of one unit (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 (after discounts, before tax) from which this carrier is free. No request goes to USPS then. Leave it empty to never offer free shipping.

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

Min weight: the minimum cart weight in kg for this carrier to appear. 0 means no limit.

Max weight: the carrier is hidden above this cart weight in kg. Default: 30. USPS accepts up to 70 lb (31.7 kg). 0 means no limit. If Min weight is greater than Max weight, an error is shown and the previous limits are kept.

Availability without shipping zones

Ignore shipping zones: offer the carrier in every zone for the countries below. Saving links the carrier to all zones of the shop, also to zones created later. Switching it off gives the carrier its previous zones back.

Countries: the destination countries for that mode. Leave empty to allow all countries the shop ships to. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs API requests and rate calculation to logs/vfd_usps_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. Keys, tokens and customer addresses are never logged.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the module deletes the USPS settings, the carrier, the saved order services, cached rates and logs. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the USPS price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to USPS.

The module gets an OAuth token from USPS and keeps it until shortly before it expires. A token that USPS rejects is renewed and the quote repeated. For destinations in the US and its territories (Puerto Rico, the US Virgin Islands, Guam, American Samoa, the Northern Mariana Islands, Micronesia, the Marshall Islands and Palau) 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 from USD to your default currency and then shown in the customer's cart 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.

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

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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

When an order is placed with the USPS carrier, the module saves how the shipping price was found. The admin order page shows a USPS block with the USPS service (for a live rate, for example USPS Ground Advantage) and the Price source: USPS live rate, Fixed price or Free shipping.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox USPS is the first block on Modules > Module Manager > VibeFox USPS > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-usps and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the USPS carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

USPS does not appear at checkout: check that the license is active and Enable USPS shipping is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum subtotal. Without working USPS keys the carrier needs a fixed price (Country prices or Fallback cost). Products can also be limited to certain carriers in the product page.

Live rates do not appear: check the warnings at the top of the module page. Turn on Debug log, reload the checkout and look at the Log field. Wrong keys, the wrong environment and USPS error messages are logged there. Domestic rates need the customer's 5-digit ZIP code.

My shop 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 page says the USPS carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox USPS and choose Uninstall. The license key and the license status are always removed. The cached token and rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, saved order services and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again, or Reset, gives the saved carrier back its previous status: a carrier that was on is on again, a disabled one stays disabled.

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