VibeFox Shippo 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.
Shippo account: create a Shippo account, connect or enable carriers (USPS, UPS, FedEx, DHL and others) and copy the API token from Shippo > Settings > Advanced > API. Shippo charges for purchased labels, not for rate requests. New Shippo accounts may need to be verified by Shippo before live rates are returned. Without a token, only the fallback prices are used.
Products: products should have a weight and dimensions. Products without dimensions use the default box size.
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_shippo-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_shippo.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_shippo-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 Shippo 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. Paste your Shippo API token and fill in the Ship from address. The postal code is required for live rates.
6. Choose the Shippo rate currency (USD when you ship from the US) and, if your store default currency is different, enter the Exchange rate.
7. Optionally enter fallback prices, turn on Enable Shippo shipping and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_shippo.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 Shippo, click Install (the green + button), then Edit (the pencil button).
4. Enter the license key and the settings as in steps 4 to 7 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 Shippo shipping and save. If you install the extension again after an uninstall, the Shippo settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Shippo > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Shippo rates. Only admin users with the modify permission for this extension can save the settings.
Warnings at the top of the page tell you when the method can never be shown or live rates cannot be used: no API token, no ship-from postal code or country, a missing exchange rate, or a store weight or length unit the extension does not know (use kg, g, lb or oz and cm, mm, m or in in System > Settings, tab Local). A notice reminds you when a test token is set. When you save, an invalid name, a value that is not a number, a negative number or price cell, a Minimum weight (kg) greater than Maximum weight (kg) or a sort order that is not a whole number is reported as an error, and nothing is saved until you correct it.
General
Enable Shippo shipping: offers the method at checkout. This is the extension status in Extensions > Extensions > Shipping.
Name: the shipping method name shown to the customer at checkout. Default: Shippo Shipping. Required, 64 characters at most, without the characters < > ; = # { }.
Tax class: the tax class of the shipping cost, or No tax. Shippo rates do not include sales tax. No tax shows them as quoted, a tax class adds tax on shipping by your tax rules.
Sort order: the position of the method among the shipping methods at checkout. A whole number.
Shippo account
API token: your Shippo API token. Use the live token (shippo_live_...) for real rates on the live store, or a test token (shippo_test_...) for Shippo test rates. The token is sent only to Shippo and is never logged. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Remove the saved API token: switch it on and save to delete the saved token.
Allowed carriers / services: optional, comma separated. Enter a carrier as Shippo names it (USPS, UPS, FedEx, DHL Express) or a Shippo service level token (usps_priority, ups_ground). The cheapest allowed rate is shown. Leave it empty to show the cheapest rate of any carrier.
Ship from (the address your parcels are sent from)
When the ship-from country is your store country, an empty sender name and state are taken from the store name and region in System > Settings. OpenCart has no structured store street, city or postcode, so enter them here.
Sender name / company: the sender name. It is also used to sign the customs declaration. If it is empty, the store name is used.
Street address: the sender street.
City: the sender city.
State / province: the two-letter state code, for example CA or NY. Some carriers need it.
Postal / ZIP code: required for live rates, for example 94105.
Country: the country you ship from. Default: United States.
Rates
Parcels: how the cart is sent to Shippo.
Default box size: length x width x height in your store length unit (shown in the field name), for example 30 x 20 x 10. Shippo needs the box size. It is used when a product in the cart has no dimensions. Leave it empty to use 30 x 20 x 10 cm. A value that cannot be read is ignored with a notice after saving, and the other settings are saved.
Shippo rate currency: the currency Shippo quotes your carriers in, which is the currency of the ship-from country: USD (US), CAD (Canada), GBP (UK), EUR (eurozone) or AUD (Australia). Default: USD. Rates Shippo returns in your store default currency are always used as they are.
Exchange rate: the price of 1 unit of the Shippo rate currency in your store default currency, for example 0.92. Not needed when both are the same. Without it, rates in the other currency are not used and the fallback prices apply. The extension does not convert currencies automatically.
Fallback prices (used when there is no live rate: no API token, Shippo unreachable, the token rejected, or no carrier rates for the address; prices in your store default currency, tax excluded; leave both empty to hide the method in that case)
Country prices: a price table by country and cart weight. Click Add country to add a row. The columns are Price and the weight tiers XS (up to 1 kg), S (1 to 2 kg), M (2 to 3 kg), L (3 to 5 kg) and XL (over 5 kg). An empty or 0 tier uses the Price column. The row * Default applies to countries without their own row. A row that is saved with all cells empty charges 0, so delete rows you do not fill in.
Other countries: the price for countries that are not in the table above (when there is no * Default row). Leave it empty to hide the method for them.
Conditions
Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which shipping is free. No Shippo request is made then. Leave it empty to turn it off.
Minimum subtotal: show the method only if 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.
Minimum weight (kg): the minimum cart weight to show the method. 0 means no limit (default).
Maximum weight (kg): the method is hidden above this cart weight. Default: 30. 0 means no limit. An empty field is saved as 30.
Availability without shipping zones
Normally the geo zone decides where the method is offered. Alternatively it can be offered by country, independent of the geo zone.
Geo zone: offer the method only for addresses in this geo zone. All zones (default) means no limit. Not used while Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.
Ignore shipping zones: offer the method for the countries below, whether or not they are in the geo zone.
Countries: the destination countries for that mode. Leave it empty to use all enabled countries of the store. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs Shippo requests to storage/logs/vfd_shpo_debug.log.php (on OpenCart 4 system/storage/logs/vfd_shpo_debug.log.php). The file cannot be read from the web. API errors are always logged, even when this option is off. The API token and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_shpo_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 Shippo settings and the log. When off (default), they are kept for a re-install. Cached rates are always removed. The carrier and service saved with orders are order history and are kept.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The API token 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 API token is not changed.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the Shippo price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, the method is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension then checks the conditions: the countries of Ignore shipping zones, cart weight and minimum subtotal. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the price is 0 and no request goes to Shippo.
The extension then sends Shippo the ship-from address, the customer's address and the parcel. For countries where OpenCart requires a postcode, the request waits until the customer has entered it. For international shipments a customs declaration with the item names (with the chosen options), quantities, weights and values is added. Shippo returns the rates of your carriers, and the extension uses the cheapest allowed rate. The price is calculated in your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.
In the per order mode, items are stacked into one box: the longest and middle sides of the largest items, and the smallest sides of all units added up. If any product has no dimensions, the default box size is used for the whole parcel. In the per item mode, every product is rated as its own parcel and the rate is multiplied by its quantity.
Each answer is cached for 1 hour per address and parcel. When Shippo answers without a usable rate, the address is remembered for 10 minutes. After a timeout, a rejected token, a server error or a rate limit, the extension pauses requests for 5 minutes and uses the fallback prices. The request timeout is 10 seconds.
If there is no live rate, the price comes from the fallback table, then from Other countries. If neither applies, the method is hidden. The customer never sees an error. The reason is written to the debug log.
The extension calculates rates only. It does not buy labels, track parcels, validate addresses, offer pickup or drop-off locations, insurance, signature options or return labels. Only the cheapest allowed rate is shown, not a list of all services. There is no box packing beyond the stacking described above, and no rate markup or handling fee.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Shippo in the window Shipping method options. The method works the same way as on OpenCart 3.
Orders
When an order is placed with a live Shippo rate, the extension keeps the chosen Carrier / service and, for one parcel per order, the Estimated delivery days. Open the order in Sales > Orders: they appear in the Shippo panel above the order history, so you can buy the matching label in Shippo. The data is saved with the order: later changes of the cart or the settings do not change it. The panel is also shown after you switch the method off. Orders with a fallback price or free shipping have no Shippo panel.
OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The saved Shippo rate is updated with it. If the customer changes to another shipping method, or the fallback price applies now, the saved rate is removed from the order.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Shippo is the first block on Extensions > Extensions > Shipping > VibeFox Shippo > 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-shippo 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, Shippo 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
Shippo does not appear at checkout: check that the license is active and Enable Shippo shipping is on. Check Geo zone (or, with Ignore shipping zones on, Countries), the weight limits and Minimum subtotal. Without a live rate, check that the country, * Default or Other countries has a price. Check that the products have Requires Shipping set to Yes.
Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension page. Common reasons: no API token or ship-from postal code, a store default currency different from the Shippo rate currency without an exchange rate, the customer's postcode not entered yet, no carrier of your Shippo account serves the address, or the Shippo account is not verified yet.
Test rates on the live store: a test token (shippo_test_...) returns Shippo test rates. Use the live token (shippo_live_...).
Free shipping for unexpected countries: check the price table for an empty row, especially an empty * Default row. A row with all cells empty charges 0.
Wrong weights or box sizes: if the page warns about an unknown weight or length unit, set a kg, g, lb or oz weight class and a cm, mm, m or in length class in System > Settings, tab Local.
Rates look outdated after a change: click Save on the extension page. This clears the cached Shippo rates.
The page says "Warning: You do not have permission to modify VibeFox Shippo!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_shippo (OpenCart 3) or extension/vfd_shippo/shipping/vfd_shippo (OpenCart 4) in System > Users > User Groups.
For developers: the Shippo API address can be replaced with the setting vfd_shpo_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 Shippo. The license key and license status of this extension are always removed. OpenCart always resets Enable Shippo shipping, Sort order, Tax class and Geo zone. The cached rates are always removed. If Remove data on uninstall is on, the Shippo 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. Existing orders keep their shipping method, cost and Shippo carrier and service data.
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 Shippo in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
Shippo is a trademark of its respective owner. This extension is not affiliated with or endorsed by Shippo.