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

Cargoson account (for live prices only): live prices use the Cargoson freight price API. Freight price queries need a Cargoson subscription with API access (Advanced plan or higher at the time of writing). The API key is issued in your Cargoson account; ask Cargoson support if your plan does not show API settings. Prices come from the carriers and price lists connected to that account. If you only use fixed prices, you do not need a Cargoson account.

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_cargoson-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_cargoson.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_cargoson-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 Cargoson 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. Choose how the shipping cost is calculated and fill in the matching sections: the fixed prices and, for live prices, the API key and the collection postcode (see Configuration). Turn on Enable Cargoson and click Save.

OpenCart 4

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. After saving you see Settings saved. Cached Cargoson prices were cleared. Decimal numbers can be typed with a point or a comma. Nothing is saved and the page lists the errors if Method title is empty or longer than 64 characters, a number field contains text or a negative number, Currency conversion rate is 0, Minimum weight (kg) is greater than Maximum weight (kg), Price currency is not a 3-letter code, a row of the price table has an invalid country or price, or Sort order is not a whole number. If the store weight unit is not known to the extension, a warning after saving says that product weights are taken as kilograms; add a weight class with the unit kg in System > Localisation > Weight Classes. Only admin users with the modify permission for this extension can save the settings.

General

The customer sees one Cargoson rate. You can limit the method to a geo zone or to countries in Availability.

Enable Cargoson: shows or hides Cargoson at checkout. Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout, at most 64 characters. Default: Cargoson. Required.

Shipping cost: how the price is calculated.

The reason for a missing live price is written to the debug log. It is never shown to the customer.

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

Cargoson API (required for live prices only)

API key: the API key from your Cargoson account. It is sent only to Cargoson and is never shown to customers or written to the log. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Remove the saved API key: turn it on and save to delete the saved key.

Carrier: which prices are used. The customer sees one rate.

Package type code: the Cargoson package type sent with the price query. Default: CLL. The Cargoson API examples use EUR (EUR pallet) and FIN (FIN pallet). For parcels use the package code of your Cargoson account. The order is sent as one package with the total cart weight.

Price currency: the currency of the prices in your Cargoson account, as a 3-letter code. Default: EUR. The API returns amounts without a currency code.

Currency conversion rate: needed only if the price currency differs from your store default currency: 1 unit of the Cargoson currency = X units of your default currency. Leave it empty to reject such prices, so a customer is never charged in the wrong currency.

Ship from (collection address) (used for live prices)

Collection country: the country you ship from. The first option, Store country, uses the country of your store.

Collection postcode: the postcode you ship from. Cargoson requires it for live prices. The OpenCart store address is free text, so the postcode is never taken from it: enter it here.

The collection date sent to Cargoson is today in the store time zone, or the next Monday on weekends.

Fixed prices (used when Shipping cost is Fixed prices, and as the fallback for live prices)

Price per country and size: a list of rows with a Country, a Price and prices by cart weight in your store default currency, tax excluded: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg, XL above 5 kg. An empty or 0 size price uses the Price column; an empty Price means no fixed rate for that size. Click Add country to add a row. Choose * All other countries for prices used for every country without its own row. Countries without a row (when there is no * row) get no fixed rate, so the method is hidden for them. Prices must be numbers of 0 or more. An empty row is ignored.

Fixed price applies: Per order (default) charges the price once. Per item (price × quantity) multiplies it by the number of items in the cart. Live Cargoson prices are always per shipment.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default).

Maximum weight (kg): hide the method above this cart weight. Default: 25. 0 means no limit.

Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.

Free shipping: turn on free Cargoson delivery from the amount below.

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which delivery is free. Used only when Free shipping is on.

Tax class: the tax class of the shipping cost, or No tax (default). Carrier prices in Cargoson are usually net (without VAT). Choose No tax if your prices already include tax.

Availability

Geo zone: offer Cargoson only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: do not check the geo zone; the country list below decides.

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

Advanced

Debug log: logs every rate calculation to storage/logs/vfd_cgs_debug.log.php. The file cannot be read from the web. API errors and rejected prices are always logged, even when this option is off. The API key and the customer postcode are never logged. When the file reaches 5 MB, it is moved to vfd_cgs_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 Cargoson settings, cached prices and the log. When off (default), they are kept for a re-install. The Cargoson quotes of placed orders are always kept.

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 kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Cargoson price. If a Geo zone is set, Ignore shipping zones is off and the address is outside the zone, Cargoson is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. Product weights are converted from their weight class to kilograms. The extension then checks the conditions: allowed countries, cart weight and minimum order amount. The order amount 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 Cargoson.

In the fixed mode the price is taken from the table. In the live modes the extension sends Cargoson the collection date, the collection country and postcode, the delivery country and postcode, and one package with the package type code and the total cart weight (at least 0.1 kg). A live price is requested only when the delivery address has a postcode. Cargoson returns the prices of your carriers; the extension picks the cheapest one (of the selected carrier, if set) and converts it to your default currency if needed. 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 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 Cargoson on every refresh. The API timeout is 10 seconds. If Cargoson returns an error, no price for the route or a price in another currency without a conversion rate, the customer sees no error. The method is hidden, or the fixed price is used in the fallback mode.

The extension calculates rates only. It does not create shipments or bookings in Cargoson, print labels or track parcels, and customers cannot choose a parcel machine or pickup point. The cart is quoted as one package with the total weight; package dimensions are not sent. Only the single cheapest price is shown, not a list of carriers.

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

Orders

When a customer places an order with Cargoson, the rate calculated at checkout is saved with the order. In Sales > Orders the order page shows a Cargoson shipping panel:

Carrier, Service and Cargoson service ID: the quoted Cargoson carrier and service, shown when a live price was used.

Price source: Cargoson live price, Fixed price or Free shipping threshold.

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

The panel is also shown while the method is switched off. On OpenCart 4 the order is created once at the confirmation step and updated each time the customer comes back to it, so the saved quote is the last one calculated at checkout; if the customer switches to another shipping method, the Cargoson quote of the order is removed. Changing the order in the admin does not change the quote. The quote does not change later. Book the shipment in Cargoson or with its own integrations.

License key

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

Cargoson does not appear at checkout: check that the license is active and Enable Cargoson is on. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum order amount. In the fixed mode, check that the country or * All other countries has a price for the cart size. Check that the products have Requires Shipping set to Yes.

Live prices do not appear: look at the Log field on the extension page. API errors are always logged; turn on Debug log to see every calculation. Typical reasons: no delivery postcode entered yet, no Collection postcode, the API key rejected (wrong or expired key, or no API access on your Cargoson plan), no carrier for the route or weight, or a price in another currency. With Cargoson live prices, fixed prices if the API fails customers still get the fixed price while you fix the problem.

Cargoson rejects the package type: use the package code your Cargoson account uses in Package type code. The reason appears in the log.

Price in another currency is rejected: set Price currency to the currency of your Cargoson prices and enter Currency conversion rate.

Tax is charged twice on shipping: your Cargoson prices already include VAT. Set Tax class to No tax.

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

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

For developers: the Cargoson API address can be replaced with the setting vfd_cgs_api_url (for tests); it has no field on the settings page.

Uninstall

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

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