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

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

2. Run bin/magento module:enable Vibefox_CargosonShipping 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 Cargoson. 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. 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). Set Enable Cargoson to Yes and click Save Config.

The module adds the Cargoson shipping method to Magento. Customers see it as Cargoson - Cheapest carrier (method title and method name). It is off after installation (Enable Cargoson = No). The module also adds one table that keeps the Cargoson quote of each order.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Cargoson, 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. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached Cargoson prices. Decimal numbers can be typed with a point or a comma.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; a number field that contains text or a negative number; a Currency conversion rate of 0; a Minimum weight greater than the Maximum weight; a Price currency that is not a 3-letter code; a row of the price table with an invalid country or price.

General

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

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

Method name: shown after the method title, as "Method title - Method name". Default: Cheapest carrier. Required, at most 64 characters.

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

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

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 (at least 0.1 kg).

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 the base currency of the website: 1 unit of the Cargoson currency = X units of the base currency. Leave it empty to reject such prices (an error in the log), 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 default, Shipping origin country, is the country in Stores > Configuration > Sales > Shipping Settings > Origin.

Collection postcode: the postcode you ship from. Cargoson requires it. If it is empty and the collection country is the origin country, the ZIP/postal code of Shipping Settings > Origin is used.

The collection date sent to Cargoson is today in the time zone of the store, 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, a Price column and prices by cart weight in the base 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 Delete to remove one. Choose * All other countries 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. A row without prices 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 (kg): hide the method below this cart weight. 0 means no limit.

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

Minimum order amount: show the method only when the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) is at least this amount. Leave empty to always show it.

Free shipping: set to Yes for free delivery when the amount below is reached. Default: No.

Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) from which delivery is free. Used only when Free shipping is Yes.

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

Ship to Specific Countries: the destination countries for Specific Countries.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so package dimensions are not sent. The module has no tax field: tax on shipping follows Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Carrier prices in Cargoson are usually net (without VAT).

Advanced

Debug log: writes every rate calculation to var/log/vfd_cgs_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors and rejected prices are always logged, even when this 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 Yes, uninstalling the module with its data deletes the Cargoson settings and the log (see Uninstall). When No, they are kept for a re-install. The license key and the cached prices are always removed. The Cargoson quotes saved with orders are order history and are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the Cargoson price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. Magento first checks the destination country, then the module checks the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Cargoson. A Magento cart price rule with free shipping also makes the price 0.

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 base currency if needed. Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

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

On the admin order page of a Cargoson order (Sales > Orders > View, Information tab) a Cargoson shipping block shows 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 (also for free shipping by a cart price rule).

Calculated price (excl. tax): the price in the base currency.

The quote is saved when the order is placed and does not change later. The customer does not see it. The block also works for older orders and when the module is switched off. 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 row of the VibeFox Cargoson 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-cargoson 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 Cargoson 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

Cargoson does not appear at checkout: check that the license is active and Enable Cargoson 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. In the fixed mode, check that the country or * All other countries has a price for the cart size.

Live prices do not appear: look at the Log field in the Advanced section. 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. Do not tax shipping in Tax Class for Shipping, or enter net prices.

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

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

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

The license key, the license status and the cached prices are always removed. If Remove data on uninstall is Yes, the Cargoson settings and the log are removed too. If it is No, the settings are kept for a re-install. The Cargoson quotes of orders stay with the orders.

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