VibeFox Blue Express for WooCommerce — Help
Requirements
WordPress: 5.8 or later.
WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.
PHP: 8.0 or later.
Blue Express account (for live rates only): live rates need a Blue Express e-commerce account and its API key (x-api-key). Request it from Blue Express: developers.bluex.cl or gpo.integraciones@bx.cl. The service you use (EX, PY or MD) must be enabled in your Blue Express contract. If you only use fixed prices, you do not need an API key.
Pickup points: the Blue Express map is loaded from widget-pudo.blue.cl in the customer's browser.
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_blue_express folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Blue Express, 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. Enter the API key, the service, the origin district code (for example SCL), the CLP exchange rate if your store currency is not CLP, and fixed prices (for example CL=4500). See Configuration.
6. Go to WooCommerce > Settings > Shipping > Shipping zones and add VibeFox Blue Express to your Chile zone. In the method settings choose the title and the delivery type (home delivery or pickup at a Blue Express point). Add it twice to offer both.
Configuration
The main settings are on WooCommerce > Settings > Shipping > VibeFox Blue Express. They apply to every shipping zone. Warnings about settings that would hide the method or the live rate (no API key, no CLP exchange rate, empty fixed price table) are shown at the top of the page. Saving the settings clears the cache.
Zone window (when you add the method to a shipping zone)
Title: the shipping method name shown to the customer for this zone. Leave it empty to use the global Name.
Delivery type: As in the global settings (default), Home delivery or Pickup at a Blue Express point (PUDO). Add the method twice to a zone to offer both home delivery and pickup.
General
Enable/Disable: switches the method off everywhere, in all shipping zones.
Name: the shipping method name shown at checkout. A zone can set its own title. Default: Blue Express.
Tax status: Blue Express prices include IVA. Choose None if WooCommerce should not add tax on top, or Taxable if it should.
Blue Express API (needed for live rates)
API key: your Blue Express API key (header x-api-key). Without it only the fixed prices are used.
Service: the Blue Express service used for the rate: Express (EX) (default), Prioritario (PY) or SameDay (MD). It must be enabled in your Blue Express contract.
Origin district code: the Blue Express district code of the place you ship from, for example SCL for Santiago (default). Ask Blue Express if unsure.
CLP per 1 (your currency): Blue Express prices are in Chilean pesos (CLP). If your store uses another currency, enter how many CLP one unit of it is worth, for example 1050. Without it, live rates are not used. Ignored when your store currency is CLP.
Price
Rate source: how the price is calculated.
Fixed prices: one line per country in the format COUNTRY_CODE=PRICE, in your store currency, for example CL=4500 in a CLP store or CL=4.50 in a EUR store. A comma or a point is accepted as the decimal separator. Invalid lines are reported when you save. Fixed prices can be used for any country.
Fixed price per: Order charges the price once. Item (price x quantity) multiplies it by the number of items in the cart. This applies to the fixed price only. The API rate is always for the whole shipment.
Conditions
Min weight (kg): hide the method when the cart weighs less. 0 means no limit.
Max weight (kg): hide the method when the cart weighs more. Default: 100. 0 means no limit.
Minimum order subtotal: show the method only from this cart subtotal (store currency). Leave empty to always show it.
Excluded shipping classes: if any cart item belongs to a selected WooCommerce shipping class, the method is hidden.
Free shipping
Free shipping: turn on free shipping from a cart subtotal.
Free from subtotal: the cart subtotal (store currency) from which shipping is free.
Pickup at Blue Express points (PUDO)
Pickup point by default: when on, Blue Express methods deliver to a Blue Express point chosen by the customer. This is the default for zone methods with Delivery type = As in the global settings. The customer must choose a point to place the order.
Availability without shipping zones
Ignore shipping zones: offer the method even when it is not added to the matching shipping zone. It then uses the global settings (no zone title or delivery type).
Countries: the destination countries for that mode. Leave empty to use all countries you ship to. Only used with Ignore shipping zones.
Advanced
Debug log: logs requests and decisions to WooCommerce > Status > Logs, source "vfd-blue-express". API errors are always logged. The API key and customer addresses are never logged.
Remove data on uninstall: when on, deleting the plugin removes its settings and zone methods. Deactivation never deletes settings. Pickup points saved in orders are kept.
How it works at checkout
When the customer enters a delivery address, the plugin checks the cart weight, Minimum order subtotal and Excluded shipping classes. If free shipping applies, the rate is 0 and no request goes to Blue Express.
For a live rate the address must be in Chile with a region and a city (commune). The plugin first asks Blue Express to recognise the commune, then requests the price for the service, the origin district, the destination and the parcels. Each product is sent with its weight and dimensions converted to kg and cm. Products without weight or size are sent as 0.01 kg, 10 x 10 x 10 cm. The declared value is sent in CLP. The CLP price is converted to your store currency.
Rates are cached for 1 hour and commune data for 12 hours. A failed API call is remembered for 5 minutes, and the timeout is 10 seconds, so a slow or unavailable API does not slow down every checkout refresh. API errors are never shown to the customer: the method is hidden, or the fixed price is used in the fallback mode. The reason is written to the log.
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 does not create shipments or labels in Blue Express, assign tracking numbers or show tracking updates. Create the shipment in your Blue Express account. There are no regional rate tables per commune: use the Blue Express API rate or one fixed price per country. Live rates work only for Chile.
Pickup points
With the delivery type Pickup at a Blue Express point (PUDO), the customer sees Choose pickup point under the Blue Express option, in the classic checkout and in the block checkout. The button opens the official Blue Express map, where the customer picks a point. The chosen point is shown with its name and address, and the button changes to Change pickup point. The rate is then recalculated with the Blue Express pickup (PUDO) price.
The order cannot be placed without a point: the customer sees Please choose a Blue Express pickup point. This is checked on the server.
The chosen point is saved in the order with its Blue Express agency code, name and address. In the admin order screen it is shown under the shipping address as Blue Express pickup point. Click Edit to choose another point on the Blue Express map or to enter the agency code, name and address by hand, then click Save pickup point. The change is recorded in an order note. The customer sees the point on the order page and in order e-mails (HTML and plain text). E-mails to the store also show the agency code. Existing orders keep their pickup point data.
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 Blue Express. 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, Blue Express 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
Blue Express 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 address (or Ignore shipping zones is on and the country is allowed). Read the warnings at the top of the settings page. Check the weight limits, Minimum order subtotal and Excluded shipping classes, and that Fixed prices has a line for the country if you use fixed prices or the fallback.
Live rates do not appear: with Blue Express API only the method is hidden when there is no rate. Turn on Debug log, reload the checkout and open WooCommerce > Status > Logs (source "vfd-blue-express"). Typical reasons: no API key, store currency not CLP without an exchange rate, missing region or commune in the address, a commune not recognised by Blue Express, or an API error (for example HTTP 401 or 403 when the API key is rejected). With Blue Express API, fixed price if the API gives no rate customers still get the fixed price while you fix the problem.
Tax is added on top of the Blue Express price: Blue Express prices include IVA. Set Tax status to None if WooCommerce should not add tax on top.
The map does not open: the map is loaded from widget-pudo.blue.cl in the customer's browser, so this address must be reachable and not blocked on your site.
Rates look outdated after a change: save the settings page. This clears the cached rates and commune data.
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 settings and only clears the cache. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cache are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Pickup points saved in orders are never removed.
Blue Express is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Blue Express.