Mercado Libre Store Management
Mercado Libre Store Management connects a Mercado Libre seller account to Odoo. This page is the installation and configuration guide for the module you downloaded from your ECOSIRE dashboard. Everything below describes the mercadolibre_store_management module; where release 2.2.6 differs from the earlier 2.1.9 build, the difference is named.
| Technical name | mercadolibre_store_management |
| Odoo versions | 17.0, 18.0, 19.0, 20.0 (Community or Enterprise) |
| Current shipped version | 17.0 → 17.0.2.2.6, 18.0 → 18.0.2.2.6, 19.0 → 19.0.2.2.6, 20.0 → 20.0.2.2.6 (release 2.2.6; the "New in 2.2.x" sections below describe what it adds over 2.1.9. Release 2.2.5, listed here on 2026-10-15, was never shipped: its changes are part of 2.2.6) |
| Price | $499 USD — one-time, per Odoo version |
| Odoo module licence | OPL-1 |
| Category | Connector |
Requirements
| Requirement | Detail |
|---|---|
| Odoo | 17.0, 18.0, 19.0 or 20.0, Community or Enterprise. Self-hosted or Odoo.sh — Odoo Online (SaaS) cannot install third-party modules |
| Odoo apps | base, sale_management, stock, account, delivery, mail, web, product, contacts — Odoo installs any that are missing |
| Python packages | requests |
| Platform account | A Mercado Libre seller/partner account with API access |
Install the Python packages into the same interpreter that runs Odoo:
sudo -u odoo pip install requests
Installation
1. Download the ZIP for your Odoo version
Download the archive for the Odoo major version you run. The connector installs directly from that archive.
2. Extract into your addons path
unzip mercadolibre_store_management_v19_*.zip -d /opt/odoo/addons/
ls /opt/odoo/addons/mercadolibre_store_management/__manifest__.py # sanity check
The archive contains a single top-level mercadolibre_store_management/ directory. If your ls check fails, the module folder ended up one level too deep — move it up so __manifest__.py sits directly inside mercadolibre_store_management/.
3. Restart Odoo and install
sudo systemctl restart odoo
- Go to Apps and click Update Apps List (developer mode must be on).
- Search for Mercado Libre Store Management and click Install.
- Odoo pulls in the Odoo apps listed above automatically.
When the install finishes, a MercadoLibre menu appears in the main Odoo app switcher.
Installation notes
Install the archive for your Odoo major version, update the Apps List and install it normally. No separate ECOSIRE component is needed.
Configuration
Connect to Mercado Libre
Open MercadoLibre → Configuration → Settings and create a record (model mercadolibre.configuration). The connection fields are:
| Label | Technical name | Required | Values |
|---|---|---|---|
| Client ID (App ID) | client_id | Yes | Text |
| Client Secret | client_secret | Yes | Text |
| Access Token | access_token | No | Text |
| Refresh Token | refresh_token | No | Text |
| Seller ID | mercadolibre_seller_id | No | Text |
| Site / Country | site_id | Yes | Selection: MLA, MLB, MLC, MCO, MLM, MLU, MPE, MEC, MCR, MRD, MPA, MHN, MNI, MSV, MGT, MBO |
| Order Confirmation | order_auto_confirm | No | Selection: manual, on_payment, always |
| Delivery Processing | order_auto_deliver | No | Selection: manual, on_shipped, always |
Client ID (App ID) and Client Secret are required, as is Site / Country (MLA, MLB, MLM, MCO, MLC …) because it selects the consent host and marketplace rules. Use Login with MercadoLibre to complete the OAuth grant rather than pasting tokens; the redirect URI you register in the Mercado Libre OAuth client must point at your Odoo domain.
The same record carries the behaviour checkboxes — sync_products, sync_orders, sync_customers, sync_inventory, auto_sync_products, auto_sync_orders, auto_sync_customers, auto_push_products, auto_push_prices, auto_push_stock, auto_register_payment, order_auto_invoice, group_pack_orders, product_overwrite_name, product_overwrite_description, product_overwrite_price, partner_overwrite_fiscal, and from 2.2.6 export_price_include_taxes. They gate what the connector is allowed to do automatically once it is connected. Leave anything you are not ready for switched off, and turn them on one at a time.
Credentials are issued from the Mercado Libre developer applications console. The connector talks to api.mercadolibre.com, with OAuth at api.mercadolibre.com/oauth and per-country consent hosts such as auth.mercadolibre.com.ar / auth.mercadolivre.com.br.
When the fields are filled in, click Test Connection. The record's status moves to connected only when the platform answers successfully — do not run a first import until it does.
Prices sent to Mercado Libre (2.2.6)
Mercado Libre shows buyers the final, tax-included price. Under Commerce Settings → Pricing on the same record:
| Label | Technical name | Default | What it does |
|---|---|---|---|
| Add Product Sales Taxes on Export | export_price_include_taxes | New installs: on. Upgraded stores: off | When the export takes a price from the price list or from the product's sales price, it adds the product's Customer Taxes, calculated by Odoo as on a sale order. A tax set as "Included in price" is already in the number and is not added again. |
| Fiscal Position on Export | export_fiscal_position_id | Empty | Optional. Maps the product's Customer Taxes before they are added, as a sale order to a Mercado Libre buyer would. |
New installs: tax-included prices on. Upgraded stores: unchanged until you turn it on. A store that existed before 2.2.6 keeps sending the same prices it sent before the upgrade. To switch it on, open Mercado Libre → Configuration → Settings, open your store, go to the Commerce Settings tab and turn on Add Product Sales Taxes on Export under Pricing. Turn it on once your Odoo prices are tax-excluded; leave it off if you already priced tax-included in Odoo, or the tax is added twice.
The Price Override on an account binding and the product's MELI Price are the marketplace price itself and are always sent exactly as typed. In COP, CLP and PYG, prices are sent in whole units, because Mercado Libre rejects decimals in those currencies.
Scheduled actions
Release 2.2.6, the build you download today, installs 19 of the scheduled actions below (Settings → Technical → Scheduled Actions). The earlier 2.1.9 build installed all 21; the upgrade removes the two Product Ads jobs, because on 2.1.9 they have no Advertiser ID to call with and record a failure on every run.
| Scheduled action | Runs every | Enabled on install |
|---|---|---|
| mercadolibre: Sync Products | 1 hours | Yes |
| mercadolibre: Sync Orders | 30 minutes | Yes |
| mercadolibre: Sync Customers | 6 hours | Yes |
| mercadolibre: Sync Inventory | 15 minutes | Yes |
| mercadolibre: Test Connection | 1 days | Yes |
| mercadolibre: Cleanup Old Logs | 1 days | Yes |
| MercadoLibre: Real-time Stock Push (5 min) | 5 minutes | No |
| mercadolibre: Process Notifications | 5 minutes | Yes |
| MercadoLibre: Auto Push Products (30 min) | 30 minutes | No |
| MercadoLibre: Auto Push Prices (120 min) | 120 minutes | No |
| mercadolibre: Sync Questions | 30 minutes | Yes |
| MercadoLibre: Sync Shipment Statuses (30 min) | 30 minutes | No |
| MercadoLibre: Sync Claims (v2) | 1 hours | Yes |
| MercadoLibre: Sync Returns | 1 hours | Yes |
| MercadoLibre: Sync Settlements (Daily) | 1 days | Yes |
| MercadoLibre: Sync Balance (6h) | 6 hours | Yes |
| MercadoLibre: Sync Promotions | 2 hours | Yes |
| MercadoLibre: Sync Reviews (Daily) | 1 days | Yes |
| MercadoLibre: Sync Analytics (12h) | 12 hours | Yes |
| MercadoLibre: Sync Ad Campaigns (2.1.9 only) | 1 days | Yes |
| MercadoLibre: Sync Ad Metrics (2.1.9 only) | 6 hours | Yes |
The jobs marked No above are installed but inactive. Enable them only if you actually use that capability, and read the note in the module-specific notes section first.
Intervals above are the shipped defaults. Adjust them to your volume — but be aware that the platform, not Odoo, sets the API rate limits, and shortening a sync interval is the usual cause of throttling errors in the logs.
Webhook and API endpoints your server exposes
These are the HTTP routes this module adds to your Odoo instance. Only the public ones are reachable without an Odoo login.
| Endpoint | Auth | Purpose |
|---|---|---|
/meli_notify | public | MercadoLibre push notifications. POST accepts MELI's plain-JSON notification (resource, topic, user_id, application_id…), answers HTTP 200 immediately and queues it for a cron to process — MELI auto-disables a topic that does not answer within 500 ms, so the acknowledgement deliberately comes before the work. GET answers ok for MELI's health check and browser probes |
/meli_login | logged-in user | OAuth redirect target. After you authorise in the MercadoLibre popup, MELI redirects to /meli_login?code=…&state=<configuration id>; the module exchanges the code for tokens and returns you to the configuration form |
/mercadolibre/api/status | logged-in user | connection and sync status read by the dashboard |
/mercadolibre/api/sync | logged-in user | triggers a sync from the dashboard |
/mercadolibre/dashboard/data | logged-in user | dashboard KPI data |
Both URLs are configured in your application at developers.mercadolibre.com: set the Redirect URI to https://<your-odoo-host>/meli_login and the Notifications callback URL to https://<your-odoo-host>/meli_notify, then subscribe the topics you want. Both must be HTTPS and must resolve publicly — a redirect URI that does not match the one configured in MercadoLibre, character for character, fails the OAuth exchange. Because /meli_notify acknowledges first and processes on a cron, a notification shows up in Odoo on the queue's next run rather than instantly.
Using the module
The MercadoLibre menu is laid out as:
- MercadoLibre → Dashboard
- MercadoLibre → Catalog — Products, Postings, Categories, Size Charts
- MercadoLibre → Sales — Orders, MELI Orders, Customers, Buyers
- MercadoLibre → Fulfillment — Shipments, Claims / Returns
- MercadoLibre → Communication — Questions, Reviews, Notifications
- MercadoLibre → Marketing — Advertising, Promotions
- MercadoLibre → Finance — Settlements, Billing Position
- MercadoLibre → Analytics — Margin Analysis, Stock Forecast, Reports, Analytics Snapshots
- MercadoLibre → Operations — Import Wizard, Export Wizard, Mapping Wizard, Bulk Price Update, Test Connection, Data Repair, Sync Logs
- MercadoLibre → Configuration — Settings, Accounts, SKU Rules, Currency Mapping, Description Templates, Category Import Wizard
A normal first run is:
- Test Connection until the instance reads connected.
- Review the mapping records (categories, order statuses, payment and shipping methods) so imported data lands on the right Odoo records.
- Run a small import first — restrict it by date or by a handful of products — and check the results before letting the scheduled actions take over.
- Watch the Logs view during the first full sync. Every sync writes a log line; failures are recorded there rather than raised at the user.
Module-specific notes
- Four scheduled actions ship disabled: real-time stock push, auto push products, auto push prices, and shipment-status sync. Three of them push data to Mercado Libre, so they are off by default to prevent an unreviewed catalogue from going live. Enable them once your mapping is correct.
- Use Login with MercadoLibre on the settings record to complete OAuth. The redirect URI configured in MercadoLibre must point back at your Odoo domain.
- Order Confirmation and Delivery Processing control how far Odoo automates a synced order (
manual,on_payment/on_shipped, oralways). Leave both onmanualuntil you trust the mapping. - Add Product Sales Taxes on Export changes the price every listing priced from a price list or the sales price is published at; check it before the first price push (see Prices sent to Mercado Libre). New installs: tax-included prices on. Upgraded stores: unchanged until you turn it on.
- Webhooks are managed from the settings form; Notifications under the Communication menu shows what arrived.
New in 2.2.6
Prices worked out by Odoo reach Mercado Libre with their sales tax (IVA). When the export takes a price from your price list or from the product's sales price, it now adds the product's Customer Taxes. Before 2.2.6 such a price went out net, so with IVA 19 % not included in the price a listing was published 19 % too low. A tax set as "Included in price" is not added again, and the Price Override and MELI Price are still sent exactly as typed. The new Add Product Sales Taxes on Export option works this way: New installs: tax-included prices on. Upgraded stores: unchanged until you turn it on. A store that existed before 2.2.6 keeps sending the prices it sent before; turn the option on under Mercado Libre → Configuration → Settings → your store → Commerce Settings → Pricing once your Odoo prices are tax-excluded. Leave it off if you already priced tax-included in Odoo, or the tax is added twice. An optional Fiscal Position on Export maps the taxes first. The price push now also sends whole units in COP, CLP and PYG, as the product export already did.
Dates from Mercado Libre are stored in UTC. Mercado Libre sends dates in
the selling site's time zone: -04:00 in Chile, -03:00 in Argentina and
Brazil, -05:00 in Colombia, +02:00 in Spain. The connector dropped the
offset, so an order placed at 09:00 in Santiago was recorded as 09:00 instead
of 13:00 UTC. On a day or month boundary that put the order in the wrong
period. This affected order dates, shipment and delivery dates, tracking
events, questions, reviews and promotion dates. Dates are now converted to UTC
before they are stored. Records imported before 2.2.6 keep their old times.
"Last Sync" only moves after a sync that finished cleanly. The Last Product Sync, Last Order Sync and Last Customer Sync timestamps used to advance after a manual run that reported nothing about what it did. They now advance only for a run that reports its outcome with no failures or errors. Any other run shows a warning, and the date stays at the last clean run.
Validating a delivery never fails because of Mercado Libre. A warehouse user without a Mercado Libre role who validated a delivery of a listed product got an access error, and the whole delivery was rolled back, even with every Mercado Libre store archived. The stock update after a validated move now reads the listings with the access it needs and runs in its own savepoint. If it fails, the failure is logged and the delivery is still completed.
The guides inside the module describe this connector. The README, User Guide, Quick Reference and Spanish guides that ship in the module contained setup steps from another connector (Consumer Key/Secret, "WC v3"). They now describe the Mercado Libre OAuth setup.
Each store keeps its own reviews, questions and promotions. Reviews, buyer questions and seller promotions are matched by the id Mercado Libre gives them. With two stores in one Odoo database, the store that imported second matched the other store's row and wrote its own values onto it, and deleting a coupon on one store could remove the other store's copy of the same promotion. Each lookup is now limited to the store the sync runs for.
Odoo 20: the dashboard opens. The 20.0 dashboard used component APIs that Odoo 20 no longer accepts, so it never rendered. It renders on 20.0 now.
New in 2.2.5 (included in 2.2.6; 2.2.5 itself was never shipped)
Stock follows the warehouse you configured, in both directions. The scheduled stock update and the instant update after a stock move publish the sellable quantity of the store's configured warehouse — never the company-wide total — and quantities read back from Mercado Libre land in that same warehouse, with a Full listing adjusted in the store's Fulfillment Warehouse.
The warranty type published for a listing is the one you selected. "Factory warranty" and "Seller's warranty" were swapped in both directions; "No guarantee" is now published without a warranty term, because Mercado Libre offers no value for it. Products already published keep exactly the warranty type their live listing shows.
A listing refresh no longer stops on an empty number. When Mercado Libre returns no value, or a text marker, for a price, a quantity or the listing health, that field is read as zero and the rest of the listing still updates.
Access tokens are renewed on time when Mercado Libre's reply does not state a lifetime: the documented 3 hours is assumed, not 6.
New in 2.2.4 (included in 2.2.6)
Buyer tax data follows Mercado Libre's current billing route. Mercado Libre retired the per-order billing endpoint the connector used to read a buyer's tax details; its developer FAQ states the old endpoint now answers 404. Imported orders now read the buyer's billing reference from the order and fetch the tax id, legal name and fiscal address from the route Mercado Libre documents today, so the customer created in Odoo arrives with its invoicing data filled. A buyer who gave no tax data has no billing reference, and then nothing more is requested.
Every call uses a route an official Mercado Libre page states. A review of
Mercado Libre's official developer pages found calls the connector made to
routes no page documents. Each one now uses its documented form: seller
promotions and deals (a deal is a promotion of type DEAL), adding items to a
promotion (one request per item, and an item Mercado Libre refuses is reported
rather than hidden), item visits, claim messages, payment detail (read from
Mercado Pago, as Mercado Libre's orders documentation directs), Brand Ads
campaign items (which need the Advertiser ID on your configuration), and the
webhook check. Each is covered by a test that names the exact method, host and
route.
New in 2.2.3 (included in 2.2.6)
Stock reaches listings on Mercado Libre's User Product model. Mercado Libre is migrating sellers to User Products, where a listing carries a user-product id and the classic item stock update is refused. The connector detects that refusal and sends stock the way the marketplace now accepts, carrying the version header the call requires. Sellers who are not on User Products keep the existing route unchanged.
A listing whose stock could not be written is held, with its reason. A quantity Mercado Libre refuses, stock Mercado Libre Fulfillment owns, and stock Odoo cannot split across several Mercado Libre warehouses all flag the listing as Stock On Hold with the reason, and are counted on the run. A run that held anything reports a warning rather than a success — so a listing that dropped out of the run can no longer hide behind a green result.
Settlements and the billing position now import. Both screens previously shipped behind a scheduled action that could never fill them. Settlements are now imported from the documented billing periods — each period's charges, bonuses and collections, read field by field from the response rather than guessed from key names — and Billing Position (the screen formerly called Account Balance) shows what Mercado Libre reports it has collected for you and what is still outstanding. It is deliberately not a MercadoPago wallet balance: Mercado Libre publishes no wallet route, so the screen names what it actually reads. A financial sync that fails now records why on the run, instead of leaving the log empty while the import fails in front of you.
The pricelist that prices a listing is the listing's own. When a pricelist has no rule for a product, the connector says so instead of publishing the sales price and reporting it as a pricelist price. With two Mercado Libre accounts on one store, the account that owns the listing prices it, not the alphabetically first one.
Every documented seller operation is implemented, each with a test naming the exact documented route: item visits, search trends, billing periods and per-order billing details, fulfilment stock, item variations, catalogue products, claim detail and refunds, and Product Ads campaigns. The reverse also holds: routes the platform does not serve are not called. Three per-variation write paths, a site-scoped trends path and a promotion-item removal path that all answer 404 were removed rather than left in place behind a screen.
The Odoo 19 package installs on Odoo.sh and Odoo Online. The Odoo 19 build
now declares a series-portable version, so it installs and upgrades on a
saas~19.x server (Odoo.sh, Odoo Online) where the module was previously
rejected as uninstallable.
All three series carry this release. The financial work, the endpoint corrections, the removed scheduled actions and the stock routing above ship on 17.0, 18.0 and 19.0 — not on 19.0 alone.
Two scheduled actions that could only record a refusal — the Product Ads campaign and metrics jobs, which need a Mercado Ads advertiser id that the 2.1.9 build had no field for — are removed on upgrade. The operations stay available from the screens, where they now use the advertiser id on your configuration and name the field to set when it is missing. Ad campaign records you keep locally are untouched.
New in 2.1.8
Prices reach catalogue listings again. A listing that belongs to a Mercado Libre catalogue had its price removed from the update before anything was sent. With Auto Push Prices on, exporting such a product reported "Updated" while the price never left Odoo. The price now travels with the update; only Mercado Libre can refuse it. The title is still left alone, because a catalogue owns it.
An export now tells you what it did not change. Anything Odoo holds back for that kind of listing, and anything Mercado Libre refuses, is named on the product's line in the run and kept on the listing row — instead of a bare "Updated" that covered a value which quietly stayed behind.
Updates survive a listing that refuses one field at a time. After a refusal the connector re-sends everything that was not named, as many times as Mercado Libre needs. A failure that is not a refusal — a server error, a rate limit — is still reported as a failure and never as a success.
Odoo 17 only: updates no longer carry the currency and the listing type. Both are fixed when a listing is published and Mercado Libre rejects the whole update over them, so changing a title used to fail over fields you never touched. Odoo 18 and 19 already behaved this way.
New in 2.1.6
- Shipment, claim, return, review, analytics and advertising syncs no longer fail before their first API call. Logs gained a Shipments filter.
- A stock push that holds listings back is reported as a warning, not a success. The run counts held listings and names the ones that have stock in Odoo, the sync log shows Held (Not Sent), and the dashboard gained a Listings Held (Not Sent) KPI.
- Upgrading releases a held listing only when its quantity on Mercado Libre already matches Odoo's. Anything that differs stays held and is listed in the upgrade log for you to decide. Nothing is written to Mercado Libre during the upgrade.
New in 2.1.5
- Export reaches products you have toggled on that have no listing row yet, matching by internal reference. It links only by default; publishing a new listing stays an explicit choice.
- Updates no longer send fields Mercado Libre will not change.
- A partly successful export shows every failure reason instead of hiding them behind the success count.
New in 2.1.4
- Sales and order-status charts open the exact matching MercadoLibre orders and use the same inclusive date window as the dashboard KPIs.
- Dashboard queries respect the selected marketplace and company, and access follows the MercadoLibre user and manager groups.
- Claims include kanban, pivot, and graph views with count-based analysis partitioned by currency.
- Failed-sync orders are no longer included in cancelled-order counts, and notification or repair failures name the affected record for faster diagnosis.
- Odoo 17, 18, and 19 carry the same dashboard, access-control, company-isolation, and client-regression coverage.
Troubleshooting
Installation
| Symptom | Cause and fix |
|---|---|
| The module is not shown in Apps | Confirm the extracted mercadolibre_store_management/ directory is directly in an active addons path, then use Apps → Update Apps List. |
| Odoo reports a missing dependency | Install the Odoo application named in the message, then update the Apps List. |
| The downloaded ZIP is the wrong version | Use the archive matching the Odoo major version that runs your instance. |
Syncing
| Symptom | Cause and fix |
|---|---|
| Test Connection fails | Re-check every required field in the table above. Most failures are a mistyped secret, or credentials created for the sandbox while the connector points at production (or vice-versa). |
| Nothing syncs even though the connection is fine | The scheduled actions are disabled at the Odoo level, or Odoo's cron worker is not running. Check Settings → Technical → Scheduled Actions and that --max-cron-threads is greater than zero. |
| Sync starts then stops part-way | Read the Logs view for that run. Rate limiting and rejected field values are the two common causes; both are logged with the platform's own error text. |
| The price did not change on Mercado Libre | Read the message on that product's line in the export run. It names anything Odoo held back for that listing and anything Mercado Libre refused; the same text is kept on the listing row. With Auto Push Prices off, no export sends a price for a listing that already exists — use Push Prices or the bulk price wizard. |
| Records import but map to the wrong Odoo values | Fix the mapping records under the module's configuration, then re-run the import. |
| Duplicated products or customers | Run the initial import once. If a first attempt half-finished, check the existing records before re-running rather than importing on top. |
Version history
| Odoo version | Version you download today |
|---|---|
| 17.0 | 17.0.2.2.6 |
| 18.0 | 18.0.2.2.6 |
| 19.0 | 19.0.2.2.6 |
| 20.0 | 20.0.2.2.6 |
ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>, so 19.0.2.2.6 is the Odoo 19 build of module version 2.2.6. Release 2.2.6's Odoo 19 package declares the series-portable version 2.2.6, which Odoo resolves to exactly 19.0.2.2.6; that is what makes the 19.0 build of 2.2.6 installable on Odoo.sh and Odoo Online (saas~19.x) as well as on-premise. Your installed version is shown in Apps.