VibeFox FedEx for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later with the cURL extension. The module refuses to install without them.

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 switched on, production keys only with it switched off. 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

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 FedEx 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. 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). Switch Sandbox off when you use production keys. Optionally enter fixed prices as a fallback. Click Save.

On install the module creates the FedEx carrier with the delivery time text FedEx delivery. 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 FedEx > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached FedEx token and rates.

At the top of the page the module shows warnings: only some of the three API credentials are filled in, no API keys and no fixed prices (the carrier is then never shown), no ship-from ZIP, no ship-from state for the US or Canada, a shop currency that differs from the FedEx account currency without an exchange rate, a shop weight unit (or, with a box size, a dimension unit) the module does not know, or a deleted carrier. Number fields accept a decimal point or comma. An invalid number or box size, an exchange rate of 0, an account currency that is not a 3-letter code and a name longer than 64 characters are not saved and are reported; the field keeps its previous value and the other fields are saved. A minimum weight greater than the maximum weight is reported too, and both weights keep their previous values.

General

Enable/Disable: turns FedEx shipping on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the shipping method name shown to the customer at checkout (the carrier name). Default: FedEx. Required.

Tax status: the tax rule of the carrier, or No tax. With a tax rule (and taxes enabled in the shop) PrestaShop adds tax to the shipping cost, so the FedEx charge without taxes is used. With No tax the FedEx net charge is used as it is.

FedEx API (live rates)

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

Sandbox: use the FedEx sandbox (apis-sandbox.fedex.com) with test keys. Switch it off for real rates (apis.fedex.com) with production keys. Default: on.

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

Secret Key: the Secret Key (client_secret) of the same project. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. 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.

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

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

Box size: optional box dimensions in your shop dimension unit, for example 30x20x15. FedEx then applies dimensional weight. Leave it empty to quote by weight only.

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 shop default currency too.

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

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 API keys are entered and as a fallback when FedEx returns no rate (API down, wrong keys, no service). Leave both fields empty to hide the carrier in that case.

Country prices: a table of 2-letter destination country codes and prices in your shop default currency, tax excluded. Click Add row to add a country and the trash icon to remove one. Use * as the country code for any other country. Rows that are not a country code (or *) with a price are ignored and reported when you save.

Fallback cost: a flat price when no country price matches. Leave it empty to hide the carrier.

Fixed price is: Per order charges the price once. Per item (price x number of items) 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: the cart subtotal (after discounts, before tax) from which this carrier is free. Leave it empty to never give free shipping.

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

Min weight: the minimum cart weight in kg for the carrier to appear. 0 means no limit.

Max weight: the maximum cart weight in kg. The carrier is hidden if it is exceeded. 0 means no limit.

Default product weight: the weight in kg used for products without a weight, for FedEx rates and for the weight limits above. Default: 0.5. Product weights are converted from your shop weight unit (kg, g, lb or oz), set in International > Localization (Local units).

Availability without shipping zones

Ignore shipping zones: offer the carrier for the countries below even if their zone is not assigned to it. On save the carrier is linked to every zone, also to zones created later. Switching it off gives the carrier its previous zones back.

Countries: the destination countries for that mode. Leave empty for all countries of the shop. Used only when Ignore shipping zones is on.

Advanced

Debug log: logs API requests and rate calculation to logs/vfd_fdx_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged. 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 on, uninstalling the module deletes all module settings, the carrier and the stored FedEx services of orders. When off, everything is kept for a re-install.

How it works at checkout

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

Otherwise the module gets an OAuth token and sends the FedEx Rate API the ship-from address, the delivery address, the cart weight (in kg, or in lb for shops that use lb or oz), the box size if set and your default currency as the preferred currency. For countries that need a postcode, the request is made only after the customer has entered one. 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 default currency, converts a rate in the FedEx account currency with your exchange rate and drops rates it cannot convert. The cheapest service is used for the price, and the price is shown in the customer's cart 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 carrier is hidden. 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 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

On the order page in the back office, orders with the FedEx carrier have a FedEx shipping block. It shows the FedEx service of the rate (for live rates), the Price source (FedEx live rate, Fixed price (no live rate) or Free shipping threshold) and the Calculated price (excl. tax) in your default currency. The values are frozen when the order is placed: later changes to the settings do not change them.

License key

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

FedEx does not appear at checkout: check that the license is active and Enable/Disable is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or turn on Ignore shipping zones and check Countries). Check the warnings at the top of the module page, the weight limits and Minimum subtotal. Without a live rate the carrier needs a country price, a * row or a Fallback cost. 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. Wrong keys, the wrong environment (test keys with Sandbox off, or production keys with it on), a missing delivery postcode and FedEx error codes are logged there.

My shop is not in USD: FedEx is asked for the rate in your default 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: saving the module page clears the cache. You can also click Clear cached FedEx token and rates.

The page says the FedEx carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Only some services should be offered: developers can restrict services with the actionVfdFdxAllowedServices hook. The hooks actionVfdFdxRateRequest and actionVfdFdxApiBaseUrl change the rate request and the API address.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox FedEx and choose Uninstall. The license key and the license status are always removed. Cached tokens and rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and the stored FedEx services of orders are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again (or Reset) gives the saved carrier back its status from before the uninstall.

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