VibeFox Mercado Envios for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
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 module 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 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 Mercado Envios 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. For live rates, paste the Access Token, choose the Mercado Envios country and, if your shop default currency is not ARS, BRL or MXN, the exchange rate. Optionally fill in Country prices and Fallback cost (used without live rates). Click Save.
On install the module creates the Mercado Envios carrier with the delivery time text Mercado Envios delivery. The carrier is assigned to all zones and all customer groups, without a tax rule. 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 Mercado Envios > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Mercado Envios rates and the last API error.
Warnings at the top of the page show configuration problems: a missing exchange rate, no access token and no price, the last Mercado Envios API error with its date, and a shop weight or dimension unit the module does not know (it is then read as kg or cm). If the carrier was deleted, the General section says The Mercado Envios carrier was not found — reset the module to create it again.
General
Add the zones of your customers to the Mercado Envios carrier in Shipping > Carriers, or use Ignore shipping zones below. These settings apply to every zone.
Enable Mercado Envios shipping: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Name: the carrier name shown to customers at checkout. Default: Mercado Envios. Required, 64 characters at most.
Tax: the tax rule of the carrier, or No tax (default). Mercado Envios quotes final prices. No tax shows them as quoted, a tax rule adds your 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 api.mercadopago.com and never logged. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To stop using live rates, tick Remove the saved access token (only the prices below are used then) and save.
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 shop default currency differs from the Mercado Envios currency: the price of 1 ARS, BRL or MXN in your default currency, for example 0.001. Without it live rates are not used. It must be a positive number. 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. They are in your shop default currency, tax excluded.
Country prices: a table of destination countries and prices. Click Add country to add a row and the trash icon 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. A Price of 0 means free shipping to that country. Both 9.99 and 9,99 are accepted. 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 carrier 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 product and multiplies it by its quantity. If one product gets no price, the carrier is hidden. Live Mercado Envios rates are always for the whole parcel.
Availability
Min weight: the minimum cart weight in kg for this carrier to appear. 0 means no limit.
Max weight: hide the carrier when the cart weighs more, in kg. Empty means 25 kg, 0 means no limit. Min weight greater than Max weight is rejected when you save.
Minimum subtotal: show the carrier only when the cart subtotal (after discounts, before tax) is at least this amount. Leave empty to always show it.
Ignore shipping zones: offer the carrier for the countries below without setting up its zones. On save the carrier is added to all zones, and zones created later are added too. Switching the option off removes the zones it added, and the carrier keeps its own zones.
Countries: the destination countries for that mode. Leave empty for all active countries of the shop. This field is used only when Ignore shipping zones is on.
Free shipping
Free shipping from: the cart subtotal (after discounts, before tax) from which this carrier is free. No API request is made in that case. Leave empty to disable.
Advanced
Debug log: writes API requests and rate calculation to logs/vfd_mrcv_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, even with this option off. The access token and customer addresses 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 settings, the carrier, cached rates 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 Mercado Envios price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to Mercado Envios.
For a destination in the Mercado Envios country with a valid postcode, the module describes the cart as one parcel: the largest width and length of the products, the heights of all products 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 default currency and then shown in the customer's cart currency.
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, rejects the token or limits the requests, 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 carrier is hidden. The customer never sees an API error.
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, print labels or track parcels. Create the shipment in your Mercado Libre or Mercado Pago account. It shows one price, the cheapest Mercado Envios option, not a choice between all options, and it has no pickup point (agency) selector.
Orders
When an order is placed with a live Mercado Envios rate, the module keeps the service name, the estimated delivery time in days and the live rate. In the back office the order page shows a Mercado Envios block with Mercado Envios service, Estimated delivery and Live rate (excl. tax). The customer sees Mercado Envios service and Estimated delivery on the order details page of their account. Existing orders are not affected by later rate changes.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mercado Envios is the first block on Modules > Module Manager > VibeFox Mercado Envios > 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-mercado-envios 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 Mercado Envios 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
Mercado Envios does not appear at checkout: check that the license is active and Enable Mercado Envios shipping is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or turn on Ignore shipping zones and check Countries). Check the warnings at the top of the module page, the weight limits and Minimum subtotal. The carrier needs a price: a working access token for addresses in the Mercado Envios country, or Country prices or Fallback cost. Products can also be limited to certain carriers in the product page.
Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the module page. 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, Fallback cost and the thresholds are in your shop default currency. Live rates come in the currency of your Mercado Pago account and are converted with Exchange rate when the shop uses another default currency.
Rates look outdated after a change: click Save on the module page. This clears the cached rates.
The page says the Mercado Envios 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 Mercado Envios and choose Uninstall. The license key and the license status are always removed. The cached rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and the saved service data of orders are removed. If it is off, the carrier is only disabled and all settings and order service data are kept. Installing the module again gives the carrier back its status from before the uninstall.
Mercado Envios and Mercado Pago are trademarks of their respective owner. This module is not affiliated with or endorsed by Mercado Envios or Mercado Pago.