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

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 (the extension page has a link): 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 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_jt_express-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_jt_express.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_jt_express-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 J&T Express 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. 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 your store default currency is not MYR, the currency conversion rate (see Configuration). Turn on Enable J&T Express and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_jt_express.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 J&T Express, 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 J&T Express and save. If you install the extension again after an uninstall, the J&T Express settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox J&T Express > 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 J&T quotes. If a value is wrong, nothing is saved and the page shows the reason: an invalid method title, an amount that is not a number of 0 or more, a Currency conversion rate of 0, a Min weight (kg) greater than Max weight (kg), or a sort order that is not a whole number. Only admin users with the modify permission for this extension can save the settings.

Warnings above the settings (shown again after each save) tell you when live quotes are only partly configured: they list the missing API settings, or say that your store currency is not MYR and the conversion rate is missing. Another warning appears if your store has no weight class with the unit kg in System > Localisation > Weight Classes. Product weights are then converted by their unit name (kg, g, lb, oz), and other units are read as kg.

General

The method is offered for the selected geo zone, or for the countries of Ignore shipping zones. The settings on this page apply to every zone.

Enable J&T Express: shows or hides the method at checkout (the status of this extension). Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout. Default: J&T Express. Required, up to 64 characters, without the characters < > ; = # { }.

Tax class: the tax class of the shipping cost, or No tax (default). A tax class adds your shipping tax on top of the cost. Choose No tax if the J&T price already includes everything you want to charge.

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

J&T Express Malaysia API (live quotes) (optional, for delivery addresses in Malaysia; all four credentials are required)

The quote is requested from J&T Express Malaysia for every Malaysian postcode and cached for an hour. Without the credentials, and for other countries, the price table and the fallback cost are used.

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. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To remove it, clear VIP customer code and save.

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 not shown again after saving. To remove it, clear API account and save.

Sender postcode: the Malaysian postcode the parcels are sent from, for example 50000. Required for live quotes: the OpenCart store address is free text, so the postcode is never taken from it.

Currency conversion rate: J&T Express Malaysia quotes are in MYR. If your store default currency is not MYR, enter how many units of your currency one MYR is worth (1 MYR = X), for example 0.20. Without it, live quotes are not used and the price table or fallback cost is used instead. If your default currency is MYR, the field says so and is not needed: quotes are used as they are. The rate must be greater than 0.

Price table and fallback (used for countries other than Malaysia, when live quotes are not configured, or when J&T gives no quote; prices in your store default currency, tax excluded)

Country prices: a table with one row per country. Click Add country to add a row and the remove button to delete one. Choose * Any other country 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, and an empty base price is saved as 0. 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.

Table / fallback price is: Per order (default) charges the price once. Per item (multiplied by the number of items) multiplies it by the number of items in the cart. Live J&T quotes are always for the whole order.

Conditions

Free shipping from: the cart subtotal (products that need shipping, after the coupon, before tax) from which shipping is free. Leave it empty for no free shipping.

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

Min weight (kg): hide the method when the cart weighs less. Product weights are converted with their weight class. 0 means no limit (default). It cannot be greater than Max weight (kg).

Max weight (kg): hide the method when the cart weighs more. Default: 50. 0 means no limit.

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 when Ignore shipping zones is on.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below, whatever the geo zone is. Default: off.

Countries: the destination countries for that mode, chosen from the countries enabled in your store. Leave it empty to allow all countries. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes price calculations to storage/logs/vfd_jtex_debug.log.php (on OpenCart 4 system/storage/logs/vfd_jtex_debug.log.php). The file cannot be read from the web. J&T API errors are always logged, even with this option off. No keys, passwords, the customer code or customer postcodes are written. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_jtex_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the J&T Express settings and the log. When off (default), they are kept for a re-install. Cached quotes are always removed.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The VIP API key and the private key are 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 keys are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the J&T Express 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 then checks the conditions: allowed countries (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 the 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 default currency is not MYR, a conversion rate is set. The extension 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 default 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. The price is calculated in your default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.

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.

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

The extension 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. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method. Create and track shipments in your J&T account as usual. The extension 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 extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox J&T Express is the first block on Extensions > Extensions > Shipping > VibeFox J&T Express > 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-jt-express 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 J&T Express 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

J&T Express does not appear at checkout: check that the license is active and Enable J&T Express is on. Check Geo zone (or that Ignore shipping zones is on and the country is in Countries), the weight limits and Minimum subtotal. Check that Country prices has a row for the country or a * row, or that Fallback cost is set. Check that the products have Requires Shipping set to Yes. Turn on Debug log and look at the Log field on the extension page.

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 not in MYR, the Currency conversion rate. Check the warnings at the top of the extension page. 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.

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

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

For developers: other extensions can change the quote request body (for example the service type) with the OpenCart event vfd_jt_express/quote_request, and the quote endpoint with vfd_jt_express/api_url.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox J&T Express. The license key and license status of this extension are always removed. OpenCart always resets Enable J&T Express, Sort order, Tax class and Geo zone. The cached quotes are always removed. If Remove data on uninstall is on, the J&T Express 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. 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 J&T Express in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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