VibeFox Shippo for Adobe Commerce — Hilfe

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. Live rates need the cURL extension.

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. Magento products have no standard dimensions, so every parcel uses the default box size.

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-shippo-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/ShippoShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_ShippoShipping 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 Shippo. 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. Paste your Shippo API token and fill in the Ship from address; the postal code is required for live rates. Choose the Shippo rate currency (USD when you ship from the US) and, if the base currency of your store is different, enter the Exchange rate. Optionally enter fallback prices. Set Enable to Yes and click Save Config.

The module adds the Shippo shipping method to Magento. Customers see it as Shippo - Courier delivery (method title and method name). It is off after installation (Enable = No). The module also adds its own table for the rate data of carts and orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Shippo, 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 Shippo rates. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 bytes or with one of the characters < > ; = # { }; a State / province longer than 64 bytes; a Sort order that is not a whole number; a number field or a price in the table that is not a number of 0 or more; a Minimum weight (kg) greater than the Maximum weight (kg). A Default box size (cm) that cannot be read is the exception: it is cleared with a warning, and the other valid settings are saved.

While Enable is Yes, warnings after saving tell you when the method can never be shown or live rates cannot be used: no API token (only fallback prices are used, or the method is hidden when there are none), no ship-from postal code or country, a missing exchange rate when the rate currency differs from the base currency, or a weight unit the module does not know. A warning also reminds you when a test token (shippo_test_...) is set. 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 Shippo at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: Shippo. Required, at most 64 bytes.

Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 bytes.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

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. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved token, type a new value to change it. To delete the saved token, clear the field and click Save Config. Only the fallback prices are used then.

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 shipping origin of your store (Stores > Configuration > Sales > Shipping Settings > Origin) and the store name (Stores > Configuration > General > General > Store Information), but only when the origin is in the same country as Country below.

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 (cm): length x width x height in cm, for example 30 x 20 x 10. Shippo needs the box size, and Magento has no standard product dimensions, so all parcels use this box. Leave it empty to use 30 x 20 x 10 cm. A value that cannot be read is cleared with a warning after saving.

Shippo rate currency: the currency Shippo quotes your carriers in, which is the currency of the ship-from country: USD, CAD, GBP, EUR or AUD. Default: USD. Rates Shippo returns in the base currency of your store are always used as they are.

Exchange rate: the value of 1 unit of the rate currency in the base currency, for example 0.92. Not needed when both are the same. Zero or empty disables conversion: 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 the base currency, tax excluded; leave both empty to hide the method in that case)

Price per country and weight: a price table by country and cart weight. Click Add country to add a row and Delete to remove one. The columns are Base 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 Base column. The row * All other countries applies to countries without their own row; a new row starts with it. If a country is listed twice, the last row wins. An existing row with an empty Base gives free shipping, 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 * All other countries row). Leave it empty to hide the method for them.

Conditions

Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) 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 the method. Empty or 0 means no minimum.

Maximum weight (kg): the method is hidden above this cart weight. Empty means 30 kg; 0 means no maximum.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

Availability

Ship to Applicable Countries: All Allowed Countries offers Shippo for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Advanced

Debug log: writes Shippo requests and rate calculations to var/log/vfd_shpo_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged, even when this is off. The API token and customer addresses are never logged.

Debug log viewer: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the Shippo settings and the log (see Uninstall). When No, they are kept for a re-install. The license key, the cached rates and the rate data of carts that were not ordered are always removed. The Shippo data of orders is kept in both cases.

The module has no tax field. If your store taxes shipping, set a tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Shippo rates do not include sales tax.

How it works at checkout

At the shipping step Magento asks the module for the Shippo 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 from applies, the price is 0 and no request goes to Shippo. A Magento cart price rule with free shipping also makes the price 0, while the countries, weight limits and Minimum subtotal still apply.

The module then sends Shippo the ship-from address, the customer's address and the parcel. For countries where Magento 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 in the base currency is added. Shippo returns the rates of your carriers, and the module uses the cheapest allowed rate. The price is calculated in the base currency of your store; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

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

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 default box, and no rate markup or handling fee.

Orders

When an order is placed with a live Shippo rate, the module keeps the Carrier / service, the Estimated delivery days (when Shippo returns them; with one parcel per item they are not shown) and the Live rate in base currency. They appear in the Shippo shipping block on the admin order page (Sales > Orders > View, Information tab), 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. The block also works for older orders and when the module is switched off. Orders with a fallback price or free shipping have no Shippo block.

If a customer cancels an online payment on the payment provider's page and Magento gives the same cart back, the new rate is kept separately: the first order keeps its own Shippo data, and the order placed again gets the data of its new rate.

License key

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

Shippo 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 a live rate, check that the country, * All other countries or Other countries has a price.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Debug log viewer in the Advanced section. Common reasons: no API token or ship-from postal code, a base 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 a row with an empty Base, especially an empty * All other countries row. Such a row charges 0.

Wrong weights: check Weight Unit in Stores > Configuration > General > General > Locale Options. The module reads lbs or kgs; an unknown unit is read as kg, with a warning after saving.

Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached Shippo 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, the settings and the Shippo data of orders stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_ShippoShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_ShippoShipping to remove the data, then bin/magento module:disable Vibefox_ShippoShipping, delete the folder app/code/Vibefox/ShippoShipping and run bin/magento setup:upgrade.

The license key, the license status, the cached rates and the rate data of carts that were not ordered are always removed. If Remove data on uninstall is Yes, the Shippo settings and the log are removed too. If it is No, the settings and the log are kept for a re-install. 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.