VibeFox Cargoson for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_cargoson folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Cargoson, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

6. Add VibeFox Cargoson to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Cargoson. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name shown to the customer for this zone. Leave it empty to use the global Method title.

Every time you save the settings, the cached Cargoson prices are cleared. Decimal numbers can be typed with a point or a comma.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. Default: Cargoson. A zone can override it.

Shipping cost: how the price is calculated.

Fixed prices (table below): the price comes from the Price per country and size table. No Cargoson account needed.

Cargoson live prices (API): the price is requested from Cargoson for each cart. If Cargoson returns no price, the method is hidden for that cart.

Cargoson live prices, fixed prices if the API fails: the price is requested from Cargoson. If Cargoson does not answer, rejects the API key or has no carrier for the route, the fixed price is used.

The reason for a missing live price is written to the WooCommerce 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.com and is never shown to customers or written to the log.

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

Any carrier (cheapest price): the cheapest price Cargoson returns. This is the default.

DPD, Omniva, Smartpost / Posti, Venipak, UPS, FedEx, DHL, GLS: the cheapest price of this carrier only, matched by the carrier name Cargoson returns (also legal names, for example AS Eesti Post for Omniva).

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 currency: 1 unit of the Cargoson currency = X units of your store 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 store country.

Collection postcode: the postcode you ship from. Cargoson requires it. If it is empty and the collection country is your store country, the store postcode from WooCommerce > Settings > General is used.

The collection date sent to Cargoson is today, 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 of countries with a Price column and prices by cart weight in your store currency: 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 cross to remove one. The row * Default applies to all countries without their own row. Countries without a row (when there is no * row) get no fixed rate, so the method is hidden for them.

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 means no limit.

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

Excluded shipping classes: hide the method if the cart contains a product from any of these WooCommerce shipping classes.

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 status: Taxable adds shipping tax according to your WooCommerce tax settings, None does not. Carrier prices in Cargoson are usually net (without VAT). Choose None if your prices already include tax.

Availability without shipping zones

Ignore shipping zones: offer Cargoson for the countries below even if it is not added to a shipping zone.

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

Advanced

Debug log: logs every rate calculation in WooCommerce > Status > Logs, source vfd_cargoson. API errors are always logged, even when this option is off. The API key and the customer postcode are never logged.

Remove data on uninstall: when on, deleting the plugin removes all Cargoson settings, zone methods and cached prices. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. If free shipping applies, the customer gets a free rate and no request goes to Cargoson.

In the fixed mode the price is taken from the table. In the live modes the plugin 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). Product weights are converted from your store unit to kilograms. A live price is requested only after the customer has entered a postcode. Cargoson returns the prices of your carriers; the plugin picks the cheapest one (of the selected carrier, if set) and converts it to your store currency if needed.

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 method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

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

When a live price is used, the order's shipping line stores the quoted Carrier, Service and Cargoson service ID. They are shown on the order edit screen, so you know what to book in Cargoson. Book the shipment in Cargoson or with its own integrations.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Cargoson. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Cargoson does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. In the fixed mode, check that the country or * Default has a price for the cart size.

Live prices do not appear: open WooCommerce > Status > Logs, source vfd_cargoson. 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.

Rates look outdated after a change: save the settings page. This clears the cached Cargoson prices.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods and cached prices are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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