VibeFox USPS for Adobe Commerce — Помощь
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4, with the cURL and JSON extensions.
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
The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-usps-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/UspsShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_UspsShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox USPS. Paste your VibeFox license key into License key in the license block, the first row of the group, 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 the base currency of your store is not USD, enter the USD exchange rate. Optionally enter fixed prices as a fallback (see Configuration). Set Enable to Yes and click Save Config.
The module adds the USPS shipping method to Magento. Customers see it as USPS - Delivery (method title and method name). It is off after installation (Enable = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox USPS, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached USPS token and rates. Amounts accept "9.99" and "9,99".
A value that is not valid is not saved: the previous value stays and a warning names the field, while the other fields are saved. This applies to an empty Method title or Method name, one longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that does not contain a non-negative number; a USD exchange rate of 0; a Ship from ZIP code without 5 digits and a Box size that cannot be read. If Min weight is greater than Max weight, both previous limits are kept.
While Enable is Yes, warnings after saving tell you when only one of the keys is set, there are no keys and no fixed prices (the method is then hidden at checkout), the ship-from ZIP code is missing, no service is selected, the USD exchange rate is missing although the base currency is not USD, or the test environment is on. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable: shows or hides USPS at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: USPS. Required, at most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Delivery. Required, at most 64 characters.
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. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved secret, type a new value to change it. To delete the saved secret, clear the field and click Save Config. Clearing the Consumer Key removes the saved secret too.
Test environment: Yes uses the USPS Testing Environment for Mailers (apis-tem.usps.com), only for apps that have access to it. Leave it at No for real prices (apis.usps.com). Default: No.
Prices: which USPS prices are used.
Services: the USPS services that may be offered. One checkout option shows the cheapest selected regular single-piece service that USPS offers for the parcel. Flat Rate, Cubic, Hold for Pickup, Sunday and letter prices are never used. Default: USPS Ground Advantage, Priority Mail and First-Class Package International Service. If no service is selected (or only No live services), live rates are not used.
USD exchange rate: USPS prices are in USD. If the base currency of your store is not USD, enter the price of 1 USD in that currency, for example 0.92. The rate must be greater than 0. Without it, live rates are not used and the fixed prices apply. Not needed when your base currency is USD.
Cached USPS token and rates: the button Clear cached USPS token and rates empties the cache at once. The cache is stored encrypted in the database. Quotes are cached for 1 hour, a failed quote for 10 minutes. After a timeout, a server error, a 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 shortened to five digits.
Box size (cm): optional length x width x height of the whole parcel in centimetres, for example 30x20x15. Magento products have no standard dimensions, so without a box size a 10 x 8 x 4 inch box is used.
Default product weight (kg): the weight per unit used for products without a weight, in USPS rates, weight limits and weight tiers. Default: 0.5. An empty field restores 0.5 kg.
Product weights are converted from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs) to pounds for USPS and to kg for the limits and tiers.
Fixed prices (prices in the base currency of your store, 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 method in that case)
Country prices: prices by destination country and cart weight. Click Add country to add a row and Delete 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 * All other countries 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 warning.
Fallback cost: a flat price when no country price matches. Leave it empty to hide the method in that case. 0 means free.
Fixed price is: Per order (default) 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: delivery is free if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. No request goes to USPS then. Leave it empty to turn it off.
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 the method to appear. Default: 0, which 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 removes the limit, an empty field restores 30 kg.
Advanced
Ship to Applicable Countries: All Allowed Countries offers USPS for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Debug log: writes API requests and rate calculations to var/log/vfd_usps_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Keys, tokens and ZIP codes are never written to the log.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the USPS settings and the log (see Uninstall). The license key and the cached token and rates are always removed. Orders and their saved USPS rate history are never deleted.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
How it works at checkout
At the shipping step Magento asks the module for the USPS price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum subtotal. If free shipping applies, the price is 0 and no request goes to USPS. A Magento cart price rule with free shipping also makes the price 0; the countries and the weight limits still apply.
The module gets an OAuth token from USPS and keeps it until shortly before it expires. A token that USPS rejects is renewed once 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 base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it (Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping). USPS prices do not include tax.
Each quote is cached for 1 hour. A failed quote is remembered for 10 minutes. After a timeout, a server error, a 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 method is hidden. The customer never sees USPS error texts. The reason is written to the log.
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 USPS, the module saves how the shipping price was found. On the admin order page (Sales > Orders > View, Information tab) the USPS block shows the USPS service (for a live rate, for example USPS Ground Advantage), the Price source: USPS live rate, Fixed price or Free shipping, and the Rate (excl. tax) in the base currency. The block also works for older orders, when the module is switched off and after a re-install.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox USPS is the first row of the VibeFox USPS group in Stores > Configuration > Sales > Delivery Methods, 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 store. Below them are the line Product: magento-shipping-usps and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the USPS method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.
Troubleshooting
USPS does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum subtotal. Without working USPS keys the method needs a fixed price (Country prices or Fallback cost).
Live rates do not appear: check the warnings after Save Config (they are shown while Enable is Yes). Turn on Debug log, reload the checkout and look at the Log field in the Advanced section. 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 the 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 click Save Config. You can also click Clear cached USPS token and rates.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_UspsShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_UspsShipping to remove the data, then bin/magento module:disable Vibefox_UspsShipping, delete the folder app/code/Vibefox/UspsShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached token and rates are always removed. If Remove data on uninstall is Yes, the USPS settings (including the Consumer Key and Consumer Secret) and the log are removed too. If it is No, the settings are kept for a re-install. Orders and their saved USPS rate history (service, price source and rate) are never deleted.
USPS is a trademark of its respective owner. This module is not affiliated with or endorsed by USPS.