VibeFox USPS for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later, with the cURL extension.

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 extension uses the current USPS APIs with OAuth 2.0. The old Web Tools User ID does not work with it. 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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_usps-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_usps.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_usps-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox USPS and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

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

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

6. Optionally enter fixed prices as a fallback, turn on Enable USPS shipping and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_usps.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox USPS, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 6 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable USPS shipping and save. If you install the extension again after an uninstall, the USPS settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox USPS > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save clears the cached USPS token and rates. Only admin users with the modify permission for this extension can save the settings, clear the cache or clear the log.

A value that is not valid is not saved: the page names the field, puts the previous value back and says The other settings were saved. This applies to a name that is empty, too long or has forbidden characters, a negative or non-numeric number, a ZIP code that is not 5 digits, a wrong box size, a Min weight (kg) above Max weight (kg) (both limits keep their values), a sort order that is not a whole number, and an unknown tax class or geo zone. Country prices that are not numbers are cleared and listed. Warnings above the settings tell you when only one of the two keys is set, there are no keys and no fixed prices (the method is then never shown), the ZIP code is missing, no service is selected, the USD exchange rate is missing, the test environment is on, or the store weight or length unit is not known to the extension.

General

The settings apply to every geo zone. USPS is offered as one shipping option at checkout.

Enable USPS shipping: offers USPS shipping at checkout. Default: off.

Name: the shipping method name shown to the customer at checkout. Default: USPS. Required, at most 64 characters, without < > ; = # { }.

Tax class: the tax class of the shipping cost. USPS prices do not include taxes. No tax (default) means shipping is not taxed.

Sort order: the position of USPS among the shipping methods at checkout. A whole number.

USPS API (live rates)

Consumer Key: the Consumer Key (client_id) of your USPS developer app. Clearing it also removes the saved Consumer Secret.

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. Clearing the Consumer Key removes it too. Type a new value only to change it.

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 price list is used.

Services: the USPS services that may be quoted. The cheapest selected service USPS offers for the parcel is shown. Choose from USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) and Library Mail (libraries and schools only). Default: Ground Advantage, Priority Mail and First-Class Package International. Flat Rate, Cubic, Hold for Pickup and Sunday prices are never used. If no service is selected, live rates are not used.

USD exchange rate: USPS prices are in USD. If your store default currency is not USD, enter the price of 1 USD in your currency, for example 0.92. It must be greater than 0. Without it, live rates are not used and the fixed prices apply. If your store currency is USD, it is not needed. The rate is not updated automatically.

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

Ship from and parcel (USPS prices depend on the origin ZIP, the weight and the parcel size; the cart is quoted as one parcel)

Ship from ZIP code: the 5-digit US ZIP code the parcels are mailed from. ZIP+4 is cut to 5 digits. OpenCart has no store postcode, so enter it here.

Box size (L x W x H): optional box dimensions in the length unit of your store (shown in the field name), for example 30x20x15. Leave it empty to use the product dimensions: the longest length, the widest width and the heights stacked. Products without dimensions are quoted as a 10 x 8 x 4 inch box.

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

Fixed prices (prices in your store default currency, tax excluded; used when no API keys are entered and as a fallback when USPS returns no rate; 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 remove button to delete one. The weight tiers are 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. * Default (any other country) applies to all other countries.

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 (default) charges the price once, for the weight of the whole cart. Per item (each item priced by its own weight x quantity) prices every product by its own weight and multiplies it by its quantity. USPS live rates are always quoted for the whole parcel.

Conditions

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) 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 subtotal of the products that need shipping (after the coupon, before tax) 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 (default).

Max weight (kg): the method is hidden above this cart weight. Default: 30. Empty means 30 kg, 0 means no limit. USPS accepts up to 70 lb (31.7 kg): heavier parcels get the fixed prices.

Geo zone: offer USPS only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used with Ignore shipping zones.

Availability without shipping zones

Ignore shipping zones: do not check the geo zone. The method is offered for the countries below.

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

Advanced

Debug log: logs API requests and rate calculation to storage/logs/vfd_usps_debug.log.php (on OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). The file cannot be read from the web. API errors are always logged, even when this option is off. Keys, tokens, ZIP codes and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_usps_debug.old.log.php and a new log is started.

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 extension deletes the USPS settings and the log. Cached rates are always removed. The USPS services of placed orders are always kept. When off, the settings are kept for a re-install.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The Consumer Secret is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved Consumer Secret is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the USPS price. If a Geo zone is set and the address is outside it, USPS is not offered (with Ignore shipping zones the country list decides instead). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. Gift certificates, reward points and store credit are not taken into account. The extension then checks the conditions: cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to USPS.

The extension gets an OAuth token from USPS and keeps it until shortly before it expires. 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 and needs the customer's 5-digit ZIP code: without it, there is no request. For other countries it asks the international prices.

The request contains the ship-from ZIP code, the cart weight, the parcel size and the price type. Parcels over 70 lb get the fixed prices. The customer sees one option with the cheapest selected service. The USD price is converted to your default currency, rounded to its decimals, and shown in the customer's currency with the tax of the selected Tax class.

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 method is hidden. The customer never sees USPS error texts. The reason is written to the debug log.

The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks USPS in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order is placed with USPS, the extension saves how the shipping price was found. The order page in Sales > Orders shows a USPS panel with 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 Calculated price (excl. tax). These values are saved when the order is placed.

OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The saved values are updated with it. If the customer changes to another shipping method, they are removed from the order. On OpenCart 4 the USPS panel is shown above the History section.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox USPS is the first block on Extensions > Extensions > Shipping > VibeFox USPS > Edit, 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: opencart-shipping-usps and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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 and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Check Geo zone, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum subtotal. Without working USPS keys the method needs a fixed price (Country prices or Fallback cost). Check that the products have Requires Shipping set to Yes.

Live rates do not appear: check the warnings at the top of the Edit page: both keys, the ZIP code, at least one service and, for stores not in USD, the exchange rate. US customers must enter a ZIP code. Turn on Debug log, reload the checkout and look at the Log field on the extension page.

Rates are not real prices: switch off Test environment.

The page warns about the weight or length unit: without a weight class with the unit kg, unknown weight units are read as kg. Add a kg weight class in System > Localisation > Weight Classes. An unknown store length unit is treated as cm. Use cm, mm, m or in as the length class of the store (System > Settings, tab Option).

Rates look outdated after a change: click Save on the extension page or Clear cached USPS token and rates.

The page says "Warning: You do not have permission to modify VibeFox USPS!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_usps (OpenCart 3) or extension/vfd_usps/shipping/vfd_usps (OpenCart 4) in System > Users > User Groups.

For developers: the USPS API address can be replaced with the setting vfd_usps_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox USPS. The license key and license status of this extension are always removed. OpenCart always resets Enable USPS shipping, Sort order, Tax class and Geo zone. The cached USPS token and rates are always removed. If Remove data on uninstall is on, the USPS settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The USPS data of placed orders is never removed, and existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox USPS in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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