VibeFox FedEx for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later with the cURL extension.

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 extension 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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_fedex-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_fedex.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_fedex-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox FedEx and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

5. 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. Turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_fedex.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox FedEx, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable/Disable and save. If you install the extension again after an uninstall, the FedEx settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox FedEx > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached FedEx token and rates. Only admin users with the modify permission for this extension can save the settings.

At the top of the page the extension shows warnings: only some of the three API credentials are filled in, no API keys and no fixed prices (the method is then never shown), no ship-from ZIP, no ship-from state for the US or Canada, a store currency without an exchange rate for rates in the FedEx account currency, a weight unit the extension does not know when there is no kg weight class (add one in System > Localisation > Weight Classes), or, with a box size, a length unit it does not know. Number fields accept a decimal point or comma. When you save, an invalid number or box size, an exchange rate of 0, an account currency that is not a 3-letter code, an invalid name or sort order are reported and not saved; the field keeps its previous value and the other fields are saved (The other settings were saved.). A minimum weight greater than the maximum weight is reported too, and both weights keep their previous values.

General

The settings apply to every geo zone. FedEx is offered as one shipping option at checkout: the cheapest FedEx service, or the fixed price when FedEx returns no rate.

Enable/Disable: turns FedEx shipping on or off at checkout. Default: off.

Name: the shipping method name shown to the customer at checkout, at most 64 characters, without < > ; = # { }. Default: FedEx. Required.

Tax class: the tax class of the shipping cost, or No tax (default). With a tax class OpenCart 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.

Sort order: the position of FedEx among the shipping methods at checkout. A whole number.

FedEx API (live rates)

The section links to the FedEx Developer Portal. Without keys the fixed prices are used.

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. Clearing it also removes the saved Secret Key.

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. Clearing the API Key removes it too. Type a new value only to change it.

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 (L x W x H): optional box dimensions in the store length unit shown in the field name, 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 store default currency too.

Exchange rate: only needed when FedEx returns rates only in the account currency and your store 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, and an amount in another currency is never shown as your currency.

Cache: the button Clear cached FedEx token and rates empties the cache at once. FedEx tokens are cached until they expire, rates for 1 hour and failed requests for 5 to 10 minutes.

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. OpenCart has no store postcode, so enter it here.

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 method in that case.

Country prices: a list of destination countries and prices in your store default currency, tax excluded. Click Add row to add a row and the × button to remove one. Choose * Any other country for a price used for every country without its own row. Rows without a valid country and price are ignored and reported when you save.

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

Fixed price is: Per order (default) 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 subtotal of the products that need shipping (after the coupon, before tax) from which this method is free. No FedEx request is made then. Leave it empty to never give free shipping.

Minimum subtotal: show the method only when the same 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 (default).

Max weight (kg): the maximum cart weight. The method is hidden if it is exceeded. 0 means no limit (default).

Default product weight (kg): the weight used for products without a weight, for FedEx rates and for the weight limits above. Default: 0.5; an empty field also means 0.5 kg. Product weights are converted from the weight class of each product.

Geo zone: offer FedEx only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used when Ignore shipping zones is on.

Availability without shipping zones

Ignore shipping zones: do not check the geo zone; offer the method for the countries below. Default: off.

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

Advanced

Debug log: writes API requests and rate calculations to storage/logs/vfd_fdx_debug.log.php (on OpenCart 4 system/storage/logs/vfd_fdx_debug.log.php). The file cannot be read from the web. API errors are always logged, even when the log is off. Keys, tokens, the account number and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_fdx_debug.old.log.php and a new log is started.

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 extension deletes the FedEx settings, cached tokens and rates and the log. When off (default), everything is kept for a re-install. The FedEx rates of placed orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The Secret Key is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved Secret Key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the FedEx price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, FedEx is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The subtotal is the price of these products after the coupon discount and before tax; gift certificates, reward points and store credit are not taken into account. The extension then 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, if the API Key, Secret Key and account number are set, the extension 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 stores whose weight class is lb or oz), the box size if set and your default currency as the preferred currency. For countries with Postcode Required on in OpenCart, the request is made only after the customer has entered a postcode. 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 extension 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. The price is rounded to the decimals of your default currency and shown to the customer in their currency with the tax of the selected Tax class.

The token is cached until it expires 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 extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks FedEx in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order with FedEx is placed, the rate shown to the customer is saved with the order. In Sales > Orders the order page has a FedEx shipping panel. 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. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again: the saved FedEx rate is updated with it, and it is removed when the customer switches to another shipping method.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox FedEx is the first block on Extensions > Extensions > Shipping > VibeFox FedEx > Edit, 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: opencart-shipping-fedex and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, FedEx is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Check Geo zone, or Ignore shipping zones and Countries. Check the warnings at the top of the extension page, the weight limits and Minimum subtotal. Without a live rate the method needs a country price, a * Any other country row or a Fallback cost. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension 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 store 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 extension page clears the cache. You can also click Clear cached FedEx token and rates.

The page says "Warning: You do not have permission to modify VibeFox FedEx!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_fedex (OpenCart 3) or extension/vfd_fedex/shipping/vfd_fedex (OpenCart 4) in System > Users > User Groups.

For developers: other extensions can change the API address, the allowed FedEx services and the rate request through the OpenCart events vfd_fedex/api_base_url, vfd_fedex/allowed_services and vfd_fedex/rate_request (registered as catalog/vfd_fedex/...); the setting vfd_fdx_api_url replaces the API address for tests and has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox FedEx. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax class and Geo zone. Cached tokens and rates are always removed. If Remove data on uninstall is on, the FedEx settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The FedEx rates of placed orders are kept in both cases, and orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox FedEx in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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