VibeFox EasyPost for Adobe Commerce — المساعدة
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.
EasyPost account (for live rates only): create an account on the EasyPost website, connect your carrier accounts (USPS, UPS, FedEx and others) in EasyPost 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. Dimensions are used only if your store has product dimension attributes (see Rates).
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-easypost-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/EasypostShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_EasypostShipping 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 EasyPost. 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. Paste your EasyPost API key and fill in the Ship from address. The ZIP code and the country are required for live rates. If the base currency of your store is not USD, enter the USD exchange rate. Optionally enter fallback prices (see Configuration). Set Enable EasyPost shipping to Yes and click Save Config.
The module adds the EasyPost Shipping method to Magento. Customers see it as EasyPost Shipping - Standard (method title and method name). It is off after installation (Enable EasyPost shipping = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox EasyPost, 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; Method title and Method name also for a store view. Save Config saves the whole page and clears the cached EasyPost rates. Amounts accept "9.99" and "9,99".
If Method title or Method name is longer than 64 characters, or Sort order is not a whole number, Magento shows an error and nothing on the page is saved. A number field that does not contain a number (or contains a negative one) is not saved: a warning names the field and the previous value is kept, the rest of the page is saved. The same happens when USD exchange rate is 0. When Minimum cart weight is greater than Maximum cart weight, a warning appears and both weights keep their previous values.
While Enable EasyPost shipping is Yes, warnings after saving remind you of settings that stop live rates: an empty API key (only the fallback prices are used, or, without fallback prices, the method is never shown), an empty ship-from ZIP code or country, and a base currency other than USD without the USD exchange rate. A note also appears when a test API key is set. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable EasyPost shipping: shows or hides EasyPost shipping at checkout. Default: No.
Method title: the shipping method name shown to the customer in the cart and at checkout (the carrier title in Magento). Default: EasyPost Shipping. At most 64 characters. If the field is empty, the default is used. If it contains one of the characters < > ; = # { }, a warning appears and the default is used.
Method name: shown after the method title, as "Method title - Method name". Default: Standard. At most 64 characters. If the field is empty, the default is used.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
EasyPost account (needed for live rates only)
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. Magento stores the key 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 the saved key, clear the field and click Save Config. Only the fallback prices are used then.
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. EasyPost needs the ZIP code and the country. If the Country is the same as the country in Stores > Configuration > Sales > Shipping Settings > Origin, empty fields are taken from that address (and the sender name from the store name in General > Store Information).
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. It is saved in capital letters.
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.
Product weights are converted to ounces (minimum 1 oz) from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions. If your store has the product attributes ts_dimensions_length, ts_dimensions_width and ts_dimensions_height, or length, width and height, their values are used: in inches when the weight unit is lbs, in centimeters when it is kgs. 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 the base currency of your store, for example 0.92 for EUR. The rate must be greater than 0. Without it live rates are not used, only fallback prices. Not needed when the base currency is USD. Stores with the base currency USD or CAD ask EasyPost to quote in their own currency.
The module has no tax field. EasyPost rates do not include sales tax. To charge tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for 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 the base currency of your store, 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 dropped on save, and a warning lists them.
Other countries: the price for countries that are not in the list above. Leave it empty to hide the method for them. 0 means free.
Conditions
Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which shipping is free. No EasyPost request is made in that case. Leave it empty to turn it off.
Minimum order amount: show the method only if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. Leave it empty to always show it.
Minimum cart weight: hide the method when the cart weighs less, in the weight unit of your store. 0 means no limit.
Maximum cart weight: hide the method when the cart weighs more, in the weight unit of your store. 0 means no limit.
Ship to Applicable Countries: All Allowed Countries offers EasyPost for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Magento checks the list before the rates are requested.
Advanced
Debug log: writes rate calculations and EasyPost requests to var/log/vfd_ep_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. API errors are always logged, even when this is off. The API key and customer addresses are never logged. Turn it off when you are done.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the EasyPost settings and the log (see Uninstall). Only the value in the Default Config scope counts. The license key and the cached rates are always removed. The EasyPost data of orders is never deleted.
How it works at checkout
At the shipping step Magento asks the module for the EasyPost price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the cart weight and Minimum order amount; Magento itself checks the countries. 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 and converts it to your base currency. Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. For countries that need a postcode, the request is made only when the delivery address has one; until then the fallback price is used. A Magento cart price rule with free shipping makes the price 0.
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. Flush Magento Cache in System > Cache Management also clears the cached rates.
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 is placed with EasyPost, the rate shown at checkout is kept with the order. On the admin order page (Sales > Orders > View, Information tab) the EasyPost shipping block shows:
EasyPost 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. Not shown for fallback prices and free shipping.
Estimated delivery: 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.
Shipping price: the calculated price in the base currency, tax excluded.
Use these values to buy the label in your EasyPost account. The block also works for older orders and when the module is switched off.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox EasyPost is the first row of the VibeFox EasyPost group in Stores > Configuration > Sales > Delivery Methods, 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: magento-shipping-easypost 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 EasyPost 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
EasyPost does not appear at checkout: check that the license is active and Enable EasyPost shipping is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Without a live rate the method needs a price for the country in Country prices or an Other countries price.
Live rates do not appear: read the warnings after Save Config, then turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Common reasons: no API key or ship-from ZIP code, a base currency other than USD 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 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. To add tax on shipping, set Tax Class for Shipping in Stores > Configuration > Sales > Tax > Tax Classes.
Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached EasyPost rates.
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_EasypostShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_EasypostShipping to remove the data, then bin/magento module:disable Vibefox_EasypostShipping, delete the folder app/code/Vibefox/EasypostShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached rates are always removed. If Remove data on uninstall is Yes, the EasyPost settings and the log are removed too. If it is No, the settings are kept for a re-install. The EasyPost data of orders (service, delivery days, price source and price) stays with the orders.
EasyPost is a trademark of its respective owner. This module is not affiliated with or endorsed by EasyPost.