EN
EUR
Back

VibeFox EasyPost 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.

EasyPost account (for live rates only): create an account on the EasyPost website, connect your carrier accounts (USPS, UPS, FedEx and others) in the EasyPost dashboard and copy the API key from EasyPost Dashboard > Account Settings > API Keys. EasyPost charges for purchased labels, not for rate requests. If you only use fallback prices, you do not need an EasyPost account.

Products: products need a weight, and better also dimensions.

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 EasyPost 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 EasyPost API key and fill in the Ship from address. The ZIP code is required for live rates.

5. If your default currency is not USD, enter the USD exchange rate. Optionally enter fallback prices (see Configuration). Click Save.

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

At the top of the page the module shows warnings when live rates cannot be used: no API key (with or without fallback prices), no ship-from ZIP code or country, or a default currency other than USD without an exchange rate. A note also appears when a test API key is set, an error when the carrier of the module was deleted, and a warning when your shop weight or dimension unit (International > Localization) is not one the module knows (kg, g, lb, oz; cm, mm, m, in).

When you save, a value that is not a number (or is negative) is not saved: a warning names the field and the previous value is kept. The same happens when USD exchange rate is 0, or when Minimum weight is greater than Maximum weight.

General

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

Name: the carrier name shown to the customer at checkout, at most 64 characters (a longer name is rejected and nothing is saved). Default: EasyPost Shipping. If the name is empty or has characters PrestaShop does not allow in a carrier name, the default name is used.

EasyPost account

API key: your EasyPost API key from EasyPost Dashboard > Account Settings > API Keys. A production key (starts with EZAK) returns real rates. A test key (starts with EZTK) returns EasyPost test rates; use it only for testing. After saving, the field stays empty and shows the saved key masked, for example EZAK******abcd. Leave the field empty to keep it. Type a new value only to change it.

Remove the saved API key: tick this box and click Save to delete the saved key.

Allowed carriers / services: optional, comma separated. Enter a carrier (USPS) or a carrier and service (USPS:Priority, UPS:Ground) as EasyPost names them. 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. If the Country is your shop country, empty fields are taken from the shop address in Shop Parameters > Contact > Stores (and the sender name from the shop name).

Sender name / company: the sender name or company.

Street address: the street of the ship-from address.

City: the ship-from city.

State: the two-letter state code, for example CA or NY.

ZIP code: the ship-from ZIP or postcode. Required for live rates.

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

Rates

Parcels: how the cart is sent to EasyPost.

One parcel per order (the cart is packed into one box): all units are stacked into one box and rated once. This is the default.
One parcel per item (every unit ships in its own box): every product is rated as its own parcel and the rate is charged for each unit. Fallback prices are charged per unit as well.

Weights are converted from your shop unit to ounces (minimum 1 oz) and dimensions to inches. If any product has no dimensions, the parcel is rated by weight only.

USD exchange rate: EasyPost rates are in USD. Enter the price of 1 USD in your default currency, for example 0.92. Without it live rates are not used, only fallback prices. Not needed when the default currency is USD. USD and CAD shops ask EasyPost to quote in their own currency. Both a point and a comma are accepted as the decimal separator.

Tax: the tax rule of the carrier, or No tax. EasyPost rates do not include sales tax. Choose the tax rules that apply to shipping.

Fallback prices

Used when there is no live rate: no API key, EasyPost cannot be reached, the key is rejected, or no carrier has a rate for the address. Prices are in your default currency, tax excluded. Leave both fields empty to hide the carrier in that case.

Country prices: one line per country: two-letter country code, a colon and the price, for example US:9.99. Lines in another format are ignored and listed in a warning when you save.

Other countries: the price for countries that are not in the list above. Leave it empty to hide the carrier for them.

Conditions

Free shipping from: the cart subtotal (products to ship, after discounts, before tax, in your default currency) from which shipping is free. No EasyPost request is made in that case. Leave it empty to turn it off.

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

Minimum weight: hide the carrier when the cart weighs less, in your shop weight unit (shown in the field label). 0 means no limit.

Maximum weight: hide the carrier when the cart weighs more, in your shop weight unit. 0 means no limit.

Availability without shipping zones

Normally the carrier is offered in the zones assigned to it 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 to the carrier. When you save with this option on, the carrier is assigned to all zones, including zones created later. When you turn it off, the carrier gets its previous zones back.

Countries: the destination countries for that mode. Use Ctrl+click to select several. Leave empty to use all active countries of your shop. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes EasyPost requests to modules/vfd_easypost/logs/vfd_ep.log.php. The file cannot be opened from the web and is rotated at 5 MB. API errors are always logged, even when this option is off. The API key and customer addresses are never logged.

Remove data on uninstall: when on, uninstalling the module deletes its settings, tables and log. Disabling the module never deletes settings.

Log: the panel below the settings shows the latest 100 lines of the log. Click Clear log to empty it.

How it works at checkout

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

Otherwise the module sends EasyPost the ship-from address, the delivery address and the parcel, and receives the rates of all your carrier accounts. It picks the cheapest allowed rate, converts it to your default currency and shows it in the customer's cart currency. For countries that need a postcode, the request is made only when the delivery address has one. Before the customer has an address, only the visitor's country is known, so countries that need a postcode get the fallback price until the address is entered.

Each answer is cached for 1 hour for the same address and parcel. An address without usable rates is remembered for 10 minutes. After a timeout, a rejected key, a rate limit or an EasyPost server error, no requests are made for 5 minutes. The API timeout is 10 seconds. In all these cases the customer sees no error: the fallback price is used, or the carrier is hidden if there is no fallback price. The reason is written to the 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, or add insurance or signature options. It shows one option (the cheapest allowed rate), not a list of services. There is no box packing beyond stacking the items into one parcel, and no rate markup or handling fee.

Orders

When an order with the EasyPost carrier is placed, the rate shown at checkout is kept with the order. The back office order page shows the EasyPost shipping block:

Carrier / service: the EasyPost carrier and service of the rate, for example USPS Priority. In the one-parcel-per-item mode all services used are listed.

Estimated delivery days: the delivery days returned by EasyPost (one-parcel-per-order mode only, when EasyPost returns them).

Price source: Live EasyPost rate, Fallback price (no live rate) or Free shipping threshold.

Calculated price (excl. tax): the price in your default currency.

Later changes of the cart in the back office do not change these values. Use them to buy the label in your EasyPost account. Rates of abandoned carts are removed after 30 days.

License key

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

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

Live rates do not appear: read the warnings at the top of the module page, then turn on Debug log, reload the checkout and look at the Log panel. Common reasons: no API key or ship-from ZIP code, a non-USD shop without the USD exchange rate, the delivery address has no ZIP code yet, no carrier of your EasyPost account serves the address, or Allowed carriers / services filters out all rates.

Rates look like test prices: a test key (EZTK...) is set. Use a production key (EZAK...) on the live shop.

Rates stopped for a few minutes: after a timeout, a rejected key or an EasyPost server error, the module pauses requests for 5 minutes and uses fallback prices. Check the API key and the log.

Is tax included? EasyPost rates do not include sales tax. Choose the tax rule in Tax to add tax on shipping.

Rates look outdated after a change: click Save on the module page. This clears the cached EasyPost rates.

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

Developer hooks: the hooks actionVfdEpShipmentRequest (request body), actionVfdEpSelectedRate (chosen rate) and actionVfdEpApiUrl (API base URL) adjust the module.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox EasyPost and choose Uninstall. The license key and license status are always removed. The carrier is removed from the checkout (orders keep their history), and the cached rates are always removed. If Remove data on uninstall is on, the settings, the saved order rates and the log are removed too. If it is off, the settings and the EasyPost data of placed orders are kept for a re-install. Installing or resetting the module creates a new carrier. If the settings were kept, it gets the status (enabled or disabled) of the previous carrier.

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