VibeFox Cargoson for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Cargoson in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. 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). Click Save.

On install the module creates the Cargoson carrier with the delivery time text Delivery by the cheapest Cargoson carrier. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Cargoson > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. 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 shows an error if a number field contains text or a negative number, Currency conversion rate is 0, Minimum weight is greater than Maximum weight, Method title is longer than 64 characters, Price currency is not a 3-letter code, or a row of the price table has an invalid country code or price. If the shop weight unit is not known to the module, a warning after saving says that product weights are taken as kilograms; set the unit in International > Localization (Local units).

General

Enable Cargoson: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Method title: the carrier name shown in the cart and at checkout. Default: Cargoson. Required. This is also the carrier name in Shipping > Carriers.

Shipping cost: how the price is calculated.

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

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: appears when a key is saved. Turn it on and save to delete the 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 shop 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. By default it is your shop country.

Collection postcode: the postcode you ship from. Cargoson requires it. If it is empty and the collection country is your shop country, the shop postcode from Shop Parameters > Contact > Stores is used.

The collection date sent to Cargoson is today in the shop 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 table with a Country column (2-letter code), a Price column and prices by cart weight in your shop 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 and the trash icon to remove one. Use * as the country code for all countries without their own row. Countries without a row (when there is no * row) get no fixed rate, so the carrier is hidden for them. Prices must be numbers of 0 or more. An empty row is ignored.

Fixed price applies: Per order 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: hide the carrier below this cart weight, in kg. 0 means no limit.

Maximum weight: hide the carrier above this cart weight, in kg. Default: 25. 0 means no limit.

Minimum order amount: show the carrier only when the cart subtotal (after discounts, before tax) is at least this amount. Leave empty to always show it.

Free shipping: turn on free delivery when the order amount below is reached.

Free shipping from: the cart subtotal (after discounts, before tax) from which delivery is free. Used only when Free shipping is on.

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

Availability without shipping zones

Normally the carrier is offered in the zones assigned to it in Shipping > Carriers.

Ignore shipping zones: offer Cargoson for the countries below, whatever zones are assigned to the carrier. When you turn it on and save, the carrier is assigned to all zones; zones created later are assigned too. When you turn it off and save, the carrier gets its previous zones back.

Countries: the destination countries for that mode. Leave empty to use all countries you ship to (active countries). This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs every rate calculation to logs/vfd_cgs_debug.log.php in the module folder. The file cannot be opened 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.

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

Remove data on uninstall: when on, uninstalling the module deletes the Cargoson settings, the carrier, cached prices, quotes of orders and logs. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the Cargoson price. Only physical products count: virtual products add no weight and are not included in the order amount. Product weights are converted from your shop unit to kilograms. The module first checks the conditions: delivery country, cart weight and minimum order amount. 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 module 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 module 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 and then shown in the customer's cart currency.

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 carrier is hidden, or the fixed price is used in the fallback mode.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

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

Orders

The order page of a Cargoson order shows a Cargoson shipping block with the rate calculated at checkout:

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 shop default currency.

The quote is saved when the order is placed and does not change later. Book the shipment in Cargoson or with its own integrations.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Cargoson is the first block on Modules > Module Manager > VibeFox Cargoson > Configure, 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 shop. Below them are the line Product: presta-shipping-cargoson and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the Cargoson carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or Ignore shipping zones is on and the country is in Countries). Check the weight limits and Minimum order amount. In the fixed mode, check that the country or * has a price for the cart size. Products can also be limited to certain carriers in the product page.

Live prices do not appear: look at the Log field on the module 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 to No tax.

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

The page says the Cargoson carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Cargoson and choose Uninstall. The license key and license status are always removed. The cached prices are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, the quotes of orders and the log are removed. If it is off, the carrier is only disabled, the settings and the quotes of placed orders are kept, and only quotes of carts without an order are removed. Installing the module again gives the saved carrier its previous status, so Reset does not switch on a carrier you had disabled.

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