VibeFox Mercado Envios 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.
Mercado Pago account (for live rates only): live rates come from the Mercado Envios calculator of your Mercado Pago account in Argentina, Brazil or Mexico. Mercado Envios must be enabled for the account. Parcels are quoted from the shipping address configured in that account. You need the production Access Token (it starts with APP_USR-): in the Mercado Pago developer panel open your application and its production credentials. There is no login button: you paste the token into the settings. If you only use prices per country, you do not need a Mercado Pago 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_mercado_envios folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Mercado Envios, 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. For live rates, paste the Access Token, choose the Mercado Envios country and, if your store currency is not ARS, BRL or MXN, the exchange rate. Optionally fill in Country prices and Fallback cost (used without live rates).
6. Add VibeFox Mercado Envios 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 Mercado Envios. 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 of this option at checkout. Leave it empty to use the global Name.
Warnings at the top of the page show configuration problems: a missing exchange rate, no access token and no price, and the last Mercado Envios API error with its date. Every time you save the settings, the cached rates are cleared.
General
Enable/Disable: turns Mercado Envios shipping on or off in all zones at once.
Name: the shipping method name shown to customers at checkout. Default: Mercado Envios.
Tax status: Mercado Envios quotes final prices. None shows them as quoted, Taxable adds your WooCommerce shipping tax on top.
Mercado Envios API (live rates) (without a token only the prices below are used)
Access token: your Mercado Pago production Access Token (APP_USR-...). It is sent only to Mercado Pago and never logged.
Mercado Envios country: the country of your Mercado Pago account: Argentina (ARS) (default), Brazil (BRL) or Mexico (MXN). Live rates are requested only for destinations in this country and are quoted in its currency.
Exchange rate: only needed when your store currency differs from the Mercado Envios currency: the price of 1 ARS, BRL or MXN in your store currency, for example 0.001. Without it live rates are not used. Both a point and a comma are accepted as the decimal separator.
Prices without live rates
These prices are used when there is no access token, for destinations outside the Mercado Envios country, and when the API gives no rate.
Country prices: prices in your store currency. Click + Add country to add a row and the cross to remove one. Choose * All other countries for every country without its own row. Price is the price for the country. The columns XS (up to 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) and XL (over 5 kg) replace it for that cart weight. An empty or 0 column uses Price. Values that are not numbers are reported after saving and cleared. Rows without any price are dropped when you save.
Fallback cost: used when neither the API nor Country prices give a price. Leave it empty to hide the method in that case.
Calculation type: Per order charges the price once. Per item (each item priced by its own weight x quantity) looks up Country prices (or the Fallback cost) for the weight of each item and multiplies it by its quantity. Live Mercado Envios rates are always for the whole parcel.
Availability
Min weight (kg): the minimum cart weight for this method to appear. 0 means no limit.
Max weight (kg): hide the method when the cart weighs more. Default: 25. 0 means no limit.
Minimum subtotal: show the method only when the cart subtotal is at least this amount. Leave empty to always show it.
Excluded shipping classes: hide the method when any cart item belongs to one of these WooCommerce shipping classes.
Ignore shipping zones: offer the method for the countries below even without adding it to a shipping zone.
Countries: the destination countries for that mode. Leave empty for all countries. This field is used only when Ignore shipping zones is on.
Free shipping
Free shipping from: the cart subtotal from which this method is free. No API request is made in that case. Leave empty to disable.
Advanced
Debug log: logs API requests and rate calculation to WooCommerce > Status > Logs (source vfd-mercado-envios). Errors are always logged, even with this option off. The access token and customer addresses are never logged.
Remove data on uninstall: when on, deleting the plugin removes all plugin settings and zone methods. Deactivating the plugin never deletes settings.
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: cart weight, minimum subtotal and excluded shipping classes. If free shipping applies, the method costs 0 and no request goes to Mercado Envios.
For a destination in the Mercado Envios country with a valid postcode, the plugin describes the cart as one parcel: the largest width and length of the items, the heights of all items added up, and the total weight in grams. Each side and the weight are raised to the Mercado Envios minimums of the country, so products without dimensions or weight still get a rate. The cart value is sent as the item price in the Mercado Envios currency. The cheapest option returned by Mercado Envios is converted to your store currency and shown under your method name.
Each quote is cached for 1 hour, so the same cart does not trigger a new request. A failed quote is not repeated for 5 minutes. If Mercado Pago cannot be reached or rejects the token, all live quotes pause for 5 minutes, so the checkout does not wait for the API on every refresh. The API timeout is 10 seconds.
The prices without live rates are used instead when there is no token, the destination is outside the Mercado Envios country, the postcode is missing or not valid, the exchange rate is missing, the parcel is heavier than the Mercado Envios limit of the country (25 kg in Argentina, 15 kg in Brazil, 30 kg in Mexico), or Mercado Envios returns an error or no option for the address. The row of the country (or the * row) is used, else the fallback cost. If there is no price, the method is hidden. The customer never sees an API error.
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, print labels or track parcels. Create the shipment in your Mercado Libre or Mercado Pago account. It shows one rate per method, the cheapest Mercado Envios option, not a choice between all options, and it has no pickup point (agency) selector.
Orders
When the order is placed with a live rate, the service name and the estimated delivery time in days are saved on the order shipping line as Mercado Envios service and Estimated delivery. Existing orders keep their shipping lines.
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 Mercado Envios. 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, Mercado Envios 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
Mercado Envios 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 warnings at the top of the settings page, the weight limits, Minimum subtotal and Excluded shipping classes. The method needs a price: a working access token for addresses in the Mercado Envios country, or Country prices or Fallback cost.
Live rates do not appear: turn on Debug log, reload the checkout and open WooCommerce > Status > Logs, source vfd-mercado-envios. Typical reasons: no token, a destination outside the Mercado Envios country, a missing or invalid postcode, a missing Exchange rate, a parcel over the weight limit, or no Mercado Envios option for the address.
HTTP 401 or 403 in the warnings: the access token is invalid or expired. Copy the production Access Token again from the Mercado Pago developer panel.
Mercado Envios answered in another currency: the account country does not match Mercado Envios country. Choose the country of your Mercado Pago account.
In which currency are the prices: Country prices and Fallback cost are in your store currency. Live rates come in the currency of your Mercado Pago account and are converted with Exchange rate when the store uses another currency.
Rates look outdated after a change: save the settings page. This clears the cached rates.
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. Only the rate cache is cleared. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin, the cached rates and the last API error 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. Existing orders keep their shipping lines.
Mercado Envios and Mercado Pago are trademarks of their respective owner. This plugin is not affiliated with or endorsed by Mercado Envios or Mercado Pago.