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

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

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_easypost-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_easypost.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_easypost-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 EasyPost 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. Paste your EasyPost API key and fill in the Ship from address. The ZIP code is required for live rates.

6. If your default currency is not USD, enter the USD exchange rate. Optionally enter fallback prices (see Configuration). Turn on Enable EasyPost shipping and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_easypost.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 EasyPost, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 6 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 EasyPost shipping and save. If you install the extension again after an uninstall, the settings you kept are used again.

Configuration

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

At the top of the page the extension 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, and a warning when your store weight or length unit (System > Settings > Option) is not one the extension knows (kg, g, lb, oz; cm, mm, m, in).

When you save, a name longer than 64 characters, a Sort order that is not a whole number, or an unknown tax class or geo zone stops the save, and nothing is saved. A value that is not a number (or is negative) is not saved: a warning names the field and the previous value is kept, while the other settings are saved. The same happens when USD exchange rate is 0, or when Minimum weight is greater than Maximum weight.

General

Enable EasyPost shipping: offers the method at checkout. This is the status of the extension in Extensions > Extensions > Shipping. Default: off.

Name: the shipping method name shown to the customer at checkout, at most 64 characters. Default: EasyPost Shipping. If the name is empty, the default name is used. A name with the characters < > ; = # { } is replaced by the default name, with a warning.

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

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 Saved key: EZAK******abcd. Leave the field empty to keep it. Type a new value only to change it. Without a key only the fallback prices are used.

Remove the saved API key: turn it on 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 store country, the empty Sender name / company is taken from the store name and the empty State from the region of your store (System > Settings). OpenCart has no store postcode, so the ZIP code must be entered here.

Sender name / company: the sender name or company. Empty means the store name (same country only).

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, for example 94105. 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 store weight unit to ounces (minimum 1 oz) and dimensions from your store length unit 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 stores ask EasyPost to quote in their own currency. Both a point and a comma are accepted as the decimal separator.

Tax class: the tax class applied to shipping, or No tax. EasyPost rates do not include sales tax.

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 method 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 method for them.

Conditions

Free shipping from: the cart subtotal (products to ship, after the coupon, 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 method only if the cart subtotal (products to ship, after the coupon, before tax) is at least this amount. Leave it empty to always show it.

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

Maximum weight: hide the method when the cart weighs more, in your store weight unit. 0 means no limit (default).

Availability

Normally the geo zone decides where the method is offered. Alternatively it can be offered by country, independent of the geo zone.

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

Ignore shipping zones: offer the method for the countries below, whether or not they are in the geo zone.

Countries: the destination countries for that mode. Leave it empty to use all enabled countries of your store. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes EasyPost requests to storage/logs/vfd_ep.log.php (on OpenCart 4 system/storage/logs/vfd_ep.log.php). The file cannot be read from the web. When it reaches 5 MB, it is moved to vfd_ep.old.log.php and a new log is started. API errors and warnings are always logged, even when this option is off. The API key and customer addresses are never logged.

Log: shows the size and the latest 100 lines of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes its settings and the log. The EasyPost data of placed orders is kept. Disabling the method never deletes settings.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API 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 API key is not changed.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the EasyPost price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, the method 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 extension first checks the conditions: destination country (with Ignore shipping zones), cart weight and minimum subtotal. The subtotal is the price of the products that need shipping, after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the price is 0 and no request goes to EasyPost.

Otherwise the extension 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 currency with the tax of the selected Tax class. For countries marked Postcode Required in System > Localisation > Countries, the request is made only when the delivery address has a postcode. In the standard OpenCart data this flag is off for the United States, so a US address without a ZIP code is also sent; EasyPost then returns an error and the fallback price is used.

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 method is hidden if there is no fallback price. The reason is written to the log.

The extension 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.

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

Orders

When an order with the EasyPost method is placed, the rate shown at checkout is kept with the order. The admin order page (Sales > Orders) shows the EasyPost shipping panel above the history:

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.

The panel is shown even if the extension is disabled later. Later changes of the order in the admin do not change these values. Use them to buy the label in your EasyPost account. OpenCart creates an order record each time the checkout reaches the confirmation step; the saved rates of such unfinished orders are removed after 30 days.

On OpenCart 4 the checkout keeps one order and updates it each time the customer confirms again. The saved rate is updated with it: it is the rate the customer saw at checkout. If the customer switches to another shipping method, the panel is no longer shown for that order.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox EasyPost is the first block on Extensions > Extensions > Shipping > VibeFox EasyPost > 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-easypost 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, the EasyPost shipping method 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

EasyPost does not appear at checkout: check that the license is active and Enable EasyPost shipping is on. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum subtotal. Without a live rate the method needs a fallback price for the country or for Other countries. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: read the warnings at the top of the extension page, then turn on Debug log, reload the checkout and look at the Log field. Common reasons: no API key or ship-from ZIP code, a non-USD store 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 store.

Rates stopped for a few minutes: after a timeout, a rejected key or an EasyPost server error, the extension 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 class in Tax class to add tax on shipping.

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

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

For developers: other extensions can adjust the request body, the chosen rate and the API base URL with the OpenCart events vfd_easypost/shipment_request, vfd_easypost/selected_rate and vfd_easypost/api_url.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox EasyPost. The license key and license status of this extension are always removed. OpenCart always resets Enable EasyPost shipping, Sort order, Tax class and Geo zone. The extension always removes its events and the cached rates. If Remove data on uninstall is on, the other settings and the log are deleted as well. If it is off, the settings are kept and are used again when you install the extension again. The EasyPost data of placed orders is never deleted, and existing 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 EasyPost in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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