VibeFox Shippo 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.

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

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_shippo folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Shippo, 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. Paste your Shippo API token and fill in the Ship from address. The postal code is required.

6. Choose the Shippo rate currency (USD when you ship from the US) and, if your store uses another currency, enter the exchange rate.

7. Optionally enter fallback prices in the country and weight table.

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

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Shippo. 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 customers see for this zone. Leave it empty to use the global Name.

Every time you save the settings, the cached Shippo rates are cleared. Warnings above the settings 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, or a missing exchange rate. A notice reminds you when a test token is set.

General

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

Name: the shipping method name shown at checkout. A zone can override it with its own Title. Default: Shippo Shipping.

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.

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; empty fields are taken from the store address in WooCommerce > Settings > General when it is in the same country)

Sender name / company: the sender name. It is also used to sign the customs declaration.

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.

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 dimension unit, 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.

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 the store currency are always used as they are.

Exchange rate: the price of 1 unit of the Shippo rate currency in your store 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 plugin does not convert currencies automatically.

Tax status: Taxable lets WooCommerce add tax on shipping by your tax rules, None does not. Shippo rates do not include sales tax.

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 currency; 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 and the cross to remove one. The columns are Price and the weight tiers XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up 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 new row starts as * Default. 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 cart subtotal 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 cart subtotal is at least this amount. Leave it empty to always show it.

Minimum weight (kg): the minimum cart weight to show this method. 0 means no limit.

Maximum weight (kg): the method is hidden above this cart weight. Default: 30. 0 means no limit.

Disabled shipping classes: hide the method if the cart contains a product of one of these WooCommerce shipping classes.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below, whether or not it is added to a zone.

Countries: the destination countries for that mode. Leave empty to use all countries the store ships to. This field is used only when Ignore shipping zones is on. A method added to a shipping zone always works for the countries of its zone.

Advanced

Debug log: logs Shippo requests to WooCommerce > Status > Logs, source vfd-shippo. API errors are always logged, even when this option is off. The API token and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes its settings and its shipping zone methods. Deactivating the plugin 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 disabled shipping classes. If free shipping applies, the method is shown with a price of 0 and no request goes to Shippo.

The plugin then sends Shippo the ship-from address, the customer's address and the parcel. For countries where WooCommerce requires a postal code, the request waits until the customer has entered it. For international shipments a customs declaration with the item names, quantities, weights and values is added. Shippo returns the rates of your carriers, and the plugin shows the cheapest allowed rate in your store currency under the method name.

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 plugin 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 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 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.

Orders

The shipping line of the order stores the chosen Carrier / service and, for one parcel per order, the Estimated delivery days. You see them on the admin order screen and can buy the matching label in Shippo.

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 Shippo. 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, Shippo 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

Shippo 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 Disabled shipping classes. Without a live rate, check that the country, * Default or Other countries has a price.

Live rates do not appear: turn on Debug log, reload the checkout and open WooCommerce > Status > Logs, source vfd-shippo. Common reasons: no API token or ship-from postal code, a store currency different from the Shippo rate currency without an exchange rate, the customer's postal code 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.

Rates look outdated after a change: save the settings page. This clears the cached Shippo rates.

For developers: the filters vfd_shpo_shipment_request, vfd_shpo_customs_declaration, vfd_shpo_selected_rate and vfd_shpo_api_url change the request body, the customs declaration, the chosen rate and the API URL.

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 all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached 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.

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