VibeFox Shippo for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

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 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 Shippo 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. Paste your Shippo API token and fill in the Ship from address. The postal code is required for live rates.

5. Choose the Shippo rate currency (USD when you ship from the US) and, if your shop default currency is different, enter the Exchange rate.

6. Optionally enter fallback prices in the country and weight table, then click Save.

On install the module creates the carrier Shippo Shipping with the delivery time text Shippo carriers (USPS, UPS, FedEx, DHL). 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 Shippo > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Shippo rates.

Warnings at the top of the page tell you when the carrier 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 shop weight or dimension unit the module does not know (set kg, g, lb or oz and cm, mm, m or in in International > Localization, Local units). A notice reminds you when a test token is set. When you save, a value that is not a number, a negative number or a Minimum weight (kg) greater than Maximum weight (kg) is reported as an error, and nothing is saved until you correct it.

General

Enable Shippo 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: Shippo Shipping. Required, 64 characters at most.

Tax: the tax rule of the carrier, or No tax. Shippo rates do not include sales tax. No tax shows them as quoted, a tax rule adds tax on shipping by your tax rules.

Shippo account

API token: your Shippo API token. Use the live token (shippo_live_...) for real rates on the live shop, 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, or tick Remove the saved API token to delete it.

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 shop address in Shop Parameters > Contact > Stores when it is in the same country)

Sender name / company: the sender name. It is also used to sign the customs declaration. If it is empty, the shop 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.

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 shop dimension 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.

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 shop default currency are always used as they are.

Exchange rate: the price of 1 unit of the Shippo rate currency in your shop 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 module 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 shop default currency, tax excluded; leave both empty to hide the carrier in that case)

Country prices: a price table by 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 (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 carrier for them.

Conditions

Free shipping from: the cart subtotal (after discounts, before tax) from which shipping is free. No Shippo request is made then. Leave it empty to turn it off.

Minimum subtotal: show the carrier only if the cart subtotal (after discounts, before tax) is at least this amount. Leave it empty to always show it.

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

Maximum weight (kg): the carrier 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 carrier is offered in its shipping zones in Shipping > Carriers. Alternatively it can be offered by country, independent of zones.

Ignore shipping zones: offer the carrier for the countries below, whether or not their zone is assigned. While this is on, the carrier is added to all zones, including zones created later. Switching it off removes those added zones again, and the carrier keeps its own zones.

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

Advanced

Debug log: logs Shippo requests to logs/vfd_shpo_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. The API token 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 module settings, the carrier and the log. When off, everything is kept for a re-install. Cached rates are always removed. The carrier and service saved with orders are order history and are kept.

How it works at checkout

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

The module then sends Shippo the ship-from address, the customer's address and the parcel. For countries where PrestaShop 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 module uses the cheapest allowed rate. The price is calculated in your shop default currency and then shown in the customer's cart currency.

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 module 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 carrier is hidden. The customer never sees an error. The reason is written to the debug 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 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

When an order is placed with a live Shippo rate, the module keeps the chosen Carrier / service and, for one parcel per order, the Estimated delivery days. They appear in the Shippo block on the back office order page, so you can buy the matching label in Shippo. The data is frozen with the order: later changes of the cart do not change it. Orders with a fallback price or free shipping have no Shippo block.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Shippo is the first block on Modules > Module Manager > VibeFox Shippo > 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-shippo 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 Shippo 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

Shippo does not appear at checkout: check that the license is active and Enable Shippo shipping is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or Ignore shipping zones is on and the country is allowed). Check the weight limits and Minimum subtotal. Without a live rate, check that the country, * Default or Other countries has a price. Products can also be limited to certain carriers in the product page.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the module page. Common reasons: no API token or ship-from postal code, a shop default 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 shop: 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: click Save on the module page. This clears the cached Shippo rates.

The page says the Shippo 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 Shippo and choose Uninstall. The license key and the license status are always removed. The cached rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again gives the carrier back the status it had before. Existing orders keep their Shippo carrier and service data.

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