VibeFox J&T Express 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.

J&T Express Malaysia API access (for live quotes only): live quotes exist only for J&T Express Malaysia, for delivery addresses in Malaysia. You need four values. Apply for a J&T VIP account on the J&T Express Malaysia website: J&T gives you the VIP customer code and the VIP API key. The API account and the private key for signing requests are issued by J&T for API integration. Ask your J&T account manager for them. J&T Philippines, Indonesia and other countries have no public quote API, so use the price table for them. If you only use the price table and fallback cost, you do not need J&T API access.

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-jt-express-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/JtExpressShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_JtExpressShipping 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 J&T Express. 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. Fill in the price table and / or the fallback cost. For live Malaysian quotes, also enter the J&T API credentials, the sender postcode and, if the base currency of your store is not MYR, the currency conversion rate (see Configuration). Set Enable J&T Express to Yes and click Save Config.

The module adds the J&T Express shipping method to Magento. Customers see it as J&T Express - Courier delivery (carrier title and method name). It is off after installation (Enable J&T Express = No). The module creates no tables of its own.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox J&T Express, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached J&T quotes. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Carrier title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that does not contain a number of 0 or more; a Currency conversion rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg).

While Enable J&T Express is Yes, the Information row at the top of the group warns you when live quotes are only partly configured: it lists the missing settings (one of the four API credentials or the sender postcode), or tells you that a currency conversion rate is needed because the base currency is not MYR. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods. Nothing is shown when no API credential is entered at all: the table and fallback cost are then used.

General

Enable J&T Express: shows or hides J&T Express at checkout. Default: No.

Carrier title: the carrier name shown in the cart and at checkout. Default: J&T Express. Required, at most 64 characters.

Method name: shown after the carrier title, as "Carrier title - Method name". Default: Courier delivery. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

The module has no tax field. If your store charges tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Magento then adds tax on top of the J&T Express price.

Api (optional, for live quotes to delivery addresses in Malaysia; all four credentials are required)

VIP customer code: your J&T Express VIP code. Clearing it also clears the saved VIP API key.

VIP API key: the API key (password) J&T Express gave you with the VIP code. It is never logged. Magento stores it 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.

API account: your J&T Express API account name. Clearing it also clears the saved private key.

API private key: the private key of the API account. It is used only to sign requests (SHA-256). It is never sent to J&T and never logged. Like the VIP API key, it is stored encrypted, shown only as a mask and deleted by clearing the field.

Sender postcode: the Malaysian postcode the parcels are sent from. Spaces and other characters that are not letters or digits are removed when you save. Leave it empty to use the ZIP/Postal Code of Stores > Configuration > Sales > Shipping Settings > Origin, when its Country is Malaysia.

Currency conversion rate: J&T Express Malaysia quotes are in MYR. If the base currency of your store is not MYR, enter how many units of the base currency one MYR is worth. Without it, live quotes are not used and the price table or fallback cost is used instead. If your base currency is MYR, leave it empty: quotes are used as they are. The rate must be greater than 0 or empty.

Prices (used for countries other than Malaysia, when live quotes are not configured, or when J&T gives no quote; prices in the base currency of your store, tax excluded)

Country prices: a table with one row per country. Click Add country to add a row and Delete to remove one. Choose * All other countries for all countries without their own row. Each row has a Base price and five weight tiers: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL above 5 kg. A tier price above 0 replaces the base price for carts in that tier. A tier of 0 uses the base price. A base price of 0 means free shipping. Empty, invalid and negative cells are saved as 0. If a country appears in two rows, the last row is kept. Countries without a row (when there is no * row) get no table price.

Fallback cost: the price used when neither J&T nor the table gives a price. Leave it empty to hide the method in that case. 0 means free shipping.

Price applies: Per order (default) charges the price once. Per item (table and fallback only) multiplies the table price for the weight tier of the whole cart, or the fallback cost, by the number of items in the cart. Live J&T quotes are always for the whole shipment.

Conditions

Minimum weight (kg): hide the method when the cart weighs less. 0 means no limit. It cannot be greater than Maximum weight (kg).

Maximum weight (kg): hide the method when the cart weighs more. Default: 50. 0 or an empty field means no limit.

Minimum order amount: show the method only when the cart subtotal reaches this amount. Leave it empty to always show it.

Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which shipping is free. No request goes to J&T then. Leave it empty for no free shipping.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). The cart weight is the sum of product weights. Magento products have no standard dimensions, so volumetric weight is not calculated.

Ship to Applicable Countries: All Allowed Countries offers J&T Express for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Live quotes are requested for Malaysia only; other countries use the table and fallback cost.

Advanced

Debug log: writes price calculations to var/log/vfd_jtex_debug.log.php in the Magento folder. The file cannot be opened from the web. J&T API errors are always logged, even with this option off. No keys, passwords or customer postcodes are written. Turn the log 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 J&T Express settings and the log (see Uninstall). The license key and the cached quotes are always removed. Default: No.

How it works at checkout

At the shipping step Magento asks the module for the J&T Express price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The method is offered once the customer has entered a delivery country. The module first checks the countries, the cart weight and Minimum order amount. If the cart subtotal reaches Free shipping from, the price is 0 and no request goes to J&T.

Otherwise the cost is taken from the first source that gives a price:

1. Live J&T quote: only when all four API credentials and a sender postcode are set, the delivery country is Malaysia, the customer has entered a 5-digit postcode and, for stores whose base currency is not MYR, a conversion rate is set. The module sends J&T the sender and delivery postcodes and the cart weight (at least 0.1 kg) for the standard service EZ, one parcel, and converts the returned MYR price to your base currency.

2. Country prices: the row of the delivery country, or the * row, with the price for the cart weight tier.

3. Fallback cost.

If none of them gives a price, the method is hidden for that cart. Per item applies only to the table and fallback prices. A Magento cart price rule with free shipping makes an available J&T Express price 0. The price is calculated in your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

Each J&T answer is cached for 1 hour, so the same cart does not trigger a new request. A failed request is cached for 10 minutes, so the checkout does not wait for J&T on every refresh. The request timeout is 10 seconds. If J&T returns an error, a zero price or no answer, the customer sees no error. The table or fallback price is used, and the reason is written to the log.

The order keeps the standard Magento shipping method, description and shipping amount. The module calculates shipping costs only. It does not create consignment notes, waybills or labels, book pickups, cancel or track shipments, or let customers choose a pickup point. Create and track shipments in your J&T account as usual. The module was built against the request format of the official J&T Express Malaysia plugin. Confirm the prices with your J&T account before going live.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox J&T Express is the first row of the VibeFox J&T Express 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-jt-express 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 J&T Express 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

J&T Express does not appear at checkout: check that the license is active and Enable J&T Express 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. Check that Country prices has a row for the country or a * row, or that Fallback cost is set. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section.

The price comes from the table, not from J&T: live quotes need all four API credentials, a sender postcode, a Malaysian delivery address with a 5-digit postcode and, for stores whose base currency is not MYR, the Currency conversion rate. Check the warnings in the Information row of the group. If J&T rejects the request or does not answer, the error is logged and the table or fallback price is used. The failed request is retried after 10 minutes.

No live quotes for the Philippines or Indonesia: J&T offers no public quote API for these countries. Use the price table and the fallback cost there.

A country gets free shipping by mistake: its row has a base price of 0 (an empty base price is saved as 0). Enter a base price or remove the row. Also check Free shipping from and your cart price rules with free shipping.

Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached J&T quotes.

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_JtExpressShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_JtExpressShipping to remove the data, then bin/magento module:disable Vibefox_JtExpressShipping, delete the folder app/code/Vibefox/JtExpressShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached quotes are always removed. If Remove data on uninstall is Yes, the J&T Express settings and the log are removed too. If it is No, the settings are kept for a re-install. Setting Enable J&T Express to No only hides the method and keeps all settings. Existing orders keep their shipping method and shipping amount.

J&T Express is a trademark of its respective owner. This module is not affiliated with or endorsed by J&T Express.