VibeFox FedEx for Adobe Commerce — Ajuda

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, with the cURL and JSON extensions.

FedEx account and API keys (for live rates only): in the FedEx Developer Portal (developer.fedex.com) create a project with the Rate API, link your FedEx shipping account and copy the API Key and Secret Key. You also need your 9-digit FedEx account number. Test keys work only with Sandbox set to Yes, production keys only with Sandbox set to No. The module uses the FedEx REST API with OAuth 2.0; it does not need a meter number or a web services password. If you only use fixed prices, you do not need FedEx keys.

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

2. Run bin/magento module:enable Vibefox_FedexShipping 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 FedEx. 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. Enter the API key, the Secret key, the 9-digit FedEx account number and the Ship from address (ZIP and, for the US and Canada, the 2-letter state). Set Sandbox to No when you use production keys. Optionally enter fixed prices as a fallback. Set Enable FedEx to Yes and click Save Config.

The module adds the FedEx shipping method to Magento. Customers see it as FedEx - Shipping (carrier title and method name). It is off after installation (Enable FedEx = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox FedEx, 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; Carrier title and Method name also for a store view. Remove data on uninstall is read only from the Default Config scope, so set it there. Save Config saves the whole page and clears the cached FedEx token and rates. Number fields accept "9.99" and "9,99".

A wrong value is not saved: Magento shows a warning, the field keeps its previous value and the other fields are saved. This applies to an empty Carrier title or Method name, one longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that does not contain a number of zero or more; an Exchange rate of 0; a FedEx account currency that is not a 3-letter code; a Box size that is not three positive numbers. A Min weight (kg) greater than the Max weight (kg) is reported too, and both weights keep their previous values.

While Enable FedEx is Yes, warnings after saving remind you of settings that stop live rates or hide the method: only some of the API key, Secret key and account number are filled in; no complete API credentials and no fixed prices (the method is then hidden at checkout); no ship-from postal code; no 2-letter ship-from state for the US or Canada; a base currency that differs from the FedEx account currency without an exchange rate. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable FedEx: shows or hides FedEx at checkout. Default: No.

Carrier title: the carrier name shown in the cart and at checkout. Default: FedEx. Required, at most 64 characters.

Method name: shown after the carrier title, as "Carrier title - Method name". Default: Shipping. Required, at most 64 characters.

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

FedEx API (needed for live rates only)

Without complete keys the fixed prices are used. The section has the button Clear cached FedEx token and rates.

Sandbox: Yes uses the FedEx sandbox (apis-sandbox.fedex.com) with test keys. Set it to No for real rates (apis.fedex.com) with production keys. Default: Yes.

API key: the API Key (client_id) of your FedEx Developer Portal project.

Secret key: the Secret Key (client_secret) of the same project. Magento stores both keys encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config. Clearing the API key removes the saved Secret key too.

FedEx account number: the 9-digit FedEx shipping account linked to the project. Account (negotiated) rates are quoted for it. Spaces are ignored.

Rates: Account rates (your negotiated FedEx prices, the default) or List rates (FedEx published prices).

Residential delivery: quote customer addresses as residential (FedEx Home Delivery, residential surcharge). Set it to No if you ship mostly to businesses. Default: Yes.

Box size: optional box dimensions, length x width x height, for example 30x20x15: in inches when the weight unit of your store is pounds, otherwise in centimetres. FedEx then applies dimensional weight. Leave it empty to quote by weight only. Magento products have no standard dimensions, so this one box is used for every cart.

FedEx account currency: the currency of your FedEx account, for example USD for US accounts or CAD for Canada. Default: USD. FedEx is always asked to quote in the base currency of your store too.

Exchange rate: only needed when FedEx returns rates only in the account currency and the base currency of your store is different: the price of 1 unit of the account currency in your base currency, for example 0.92. Without it such rates are not used.

Cache: the button Clear cached FedEx token and rates empties the cached FedEx access token and quotes of the module.

Ship from

The address FedEx picks up from or where you drop off the parcels. Used for live rates.

Country: the country you ship from. Default: United States.

State / province code: the 2-letter code, required for the US and Canada, for example TN, CA or ON.

City: the ship-from city.

ZIP / postal code: the ship-from postal code. FedEx needs it to quote rates.

Fixed prices

Used when no complete API keys are entered and as a fallback when FedEx returns no rate (API down, wrong keys, no service). They are in the base currency of your store, tax excluded. Leave both price fields empty to hide the method in that case.

Country prices: a table of destination countries and prices. Click Add country to add a row, choose the country and enter the Price; * All other countries covers every country without its own row. Click Delete to remove a row. Rows without a valid price are dropped on save with the warning FedEx: an invalid country price row was ignored.

Fallback cost: a flat price when no country price matches. Leave it empty to hide the method. 0 means free.

Fixed price is: Per order charges the price once. Per item multiplies it by the number of items in the cart. This applies to fixed prices only. FedEx live rates are always quoted for the whole cart weight.

Conditions

Free shipping from: delivery is free if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. No request goes to FedEx. Leave it empty to never give free shipping.

Minimum subtotal: show the method only when the cart subtotal is at least this amount. Leave it empty to always show it.

Min weight (kg): the minimum cart weight for the method to appear. 0 means no limit.

Max weight (kg): hide the method if the cart is heavier. Default: 0, which means no limit.

Default product weight (kg): the weight used for products without a weight, for FedEx rates and for the weight limits above. Default: 0.5.

Product weights are converted from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). With lbs the weight is sent to FedEx in pounds and the box size in inches, with kgs in kilograms and centimetres.

Ship to Applicable Countries: All Allowed Countries offers FedEx 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: logs API requests and rate calculations to var/log/vfd_fdx_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Keys, tokens 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 Yes in the Default Config scope, uninstalling the module with its data deletes the FedEx settings and the log (see Uninstall). The license key and the cached token and rates are always removed. The FedEx data of orders is never deleted.

How it works at checkout

At the shipping step Magento asks the module for the FedEx price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. Magento first checks the countries; the module then checks the cart weight and Minimum subtotal. If free shipping applies, the price is 0 and no request goes to FedEx. A Magento cart price rule with free shipping also makes the FedEx price 0; the method still needs a live rate or a fixed price to appear.

Otherwise the module gets an OAuth token and sends the FedEx Rate API the ship-from address, the delivery address, the cart weight, the box size if set, the Residential delivery setting and your base currency as the preferred currency. For countries that need a postcode, the request is made only after the customer has entered one (countries in Zip/Postal Code is Optional for of your store are quoted without it). For international shipments the customs value of the cart is sent. State codes are sent only for the US and Canada.

FedEx returns the available services. For each service the module takes the account or list rate you chose, prefers a rate in your base currency, converts a rate in the FedEx account currency with your exchange rate and drops rates it cannot convert. If your store taxes shipping (a class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping), the FedEx charge without taxes is used, so Magento adds tax only once; otherwise the FedEx net charge is used as it is. The cheapest service is used for the price. Magento then shows it in the customer's currency.

The token is cached per environment and key and requested again automatically when FedEx rejects it. Quotes are cached for 1 hour. A failed rate request is remembered for 10 minutes and a failed token request for 5 minutes, so an outage does not slow down every checkout update. The API timeout is 15 seconds. If FedEx does not answer, the customer sees no error: the fixed price is used, or the method is hidden. The reason is written to the debug log.

The module calculates rates only. It does not create FedEx shipments, print labels, book pickups, track parcels or let customers choose a FedEx location. It shows one option (the cheapest service), not several, and there is no box packing: the cart is quoted as one package.

Orders

When an order is placed with FedEx, the module stores the rate with the order. On the admin order page (Sales > Orders > View, Information tab) the FedEx shipping block shows the Service (the FedEx service of a live rate), the Price source (FedEx live rate, Fixed price (no live rate) or Free shipping) and the Rate in your base currency. The values are frozen when the order is placed: later changes to the settings do not change them. The block also works for older orders and when the method is switched off.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox FedEx is the first row of the VibeFox FedEx group in Stores > Configuration > Sales > Delivery Methods, above the settings, in the Default Config scope. 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-fedex 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 FedEx 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

FedEx does not appear at checkout: check that the license is active and Enable FedEx is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the warnings after Save Config, the weight limits and Minimum subtotal. Without a live rate the method needs a country price, a * All other countries row or a Fallback cost.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Wrong keys, the wrong environment (test keys with Sandbox = No, or production keys with Sandbox = Yes), a missing delivery postcode and FedEx error codes are logged there. Check that the FedEx account number and the Ship from ZIP and state are filled in.

My store is not in USD: FedEx is asked for the rate in your base currency. If your account returns only its own currency, set FedEx account currency and Exchange rate. Without an exchange rate such rates are ignored and the fixed price is used, so a USD amount is never shown as euros.

Does "Per item" multiply the FedEx rate? No. Per item applies to fixed prices only.

Rates look outdated after a change: click Save Config on the Delivery Methods page or Clear cached FedEx token and rates. Flushing the Magento cache in System > Cache Management clears them too.

Only some services should be offered: developers can restrict services with the Magento event vfd_fdx_allowed_services. The events vfd_fdx_rate_request and vfd_fdx_api_base_url change the rate request and the API address.

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 and the settings stay. To remove the data, uninstall the module with the Magento command:

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

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

The license key, the license status and the cached FedEx token and rates are always removed. If Remove data on uninstall is Yes in the Default Config scope, the FedEx settings and the log are removed too. If it is No, the settings are kept for a re-install. The FedEx data of orders (service, price source and rate) stays with the orders.

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