MercadoLibre Store Management
Connect your MercadoLibre seller account to Odoo through the official MercadoLibre API with OAuth 2.0 authentication. This module communicates with api.mercadolibre.com to synchronize product listings, import orders with automatic customer creation, manage inventory, process shipments, handle buyer questions and claims, track advertising campaigns, forecast stock levels, and automate accounting -- all across 18 Latin American markets. With 50+ models, 133 API methods, 79 Python files, 41 XML views, 3 translation files, 194 automated tests, and 80+ features, this is the most comprehensive MercadoLibre integration available for Odoo.
Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: Up to 3 domain activations
Understanding Import vs Export (Start Here)
The two core operations are frequently confused. They move data in opposite directions:
| I want to... | Use this | Button |
|---|---|---|
| Pull my MercadoLibre listings, orders, customers, and stock INTO Odoo | Import Wizard (Operations > Import Wizard) | Start Import |
| Push Odoo products UP TO MercadoLibre, publish new listings, push stock | Export Wizard (Operations > Export Wizard) | Start Export |
Import is always FROM MercadoLibre. Export is always TO MercadoLibre. The wizards are independent -- running one does not affect the other.
If you are setting up for the first time, run Import first to bring your existing MercadoLibre data into Odoo, then use Export to publish or update listings from Odoo going forward.
Key Features
Product Management
- Product import from MELI by ID, SKU, or name match with configurable overwrite rules (name, description, price)
- Product export/publish to MELI with images, category, description, and listing type selection
- Variant/attribute publishing -- group Odoo variants as MercadoLibre variations
- Category tree model with hierarchy and auto-predictor from product title via MELI API
- Description banner templates -- wrap product descriptions with header/footer HTML branding
- Image upload with 4-tier priority system and blake2b hash deduplication
- Product lifecycle management -- pause, activate, or close listings directly from Odoo
- Block stock updates per product to prevent overwrites on specific items
- Warranty management -- seller warranty, factory warranty, or none with Spanish-localized duration (dias/meses/anos) via MELI sale_terms API
- Installments configuration -- no-fee, 3/6/9/12 month promotional installment plans
- Pack quantity -- units per listing for multi-pack products
- Catalog listing detection -- automatically detects catalog-locked listings and skips locked fields (price, quantity, title) during updates
- Batch publish wizard -- select multiple products and mass-publish to MELI in one operation
- Batch update wizard -- mass-refresh product data from MELI
- Listing types: free, bronze, silver, gold, gold_special, gold_pro
- Website category mapping -- optionally create Odoo eCommerce categories from MELI categories during import
- Product reviews import -- sync buyer reviews from the MELI Reviews API including rating (1-5 stars), review content, reviewer info, and helpful/not helpful vote counts
- Seller response tracking -- track and manage your responses to buyer reviews
- Product postings model -- track individual MELI listings with health scores, status, and metadata
- Product tags -- organize and filter products with custom tags
- Product attribute mapping -- sync MELI attributes and attribute terms to Odoo product attributes
Order Processing
- Order import with configurable date range filters (
order_date_from/order_date_to) - Dedicated MELI Orders model (
mercadolibre.order) separate fromsale.orderfor detailed tracking -- items, payments, buyers, amounts, dates - Auto-confirm orders when paid (configurable: manual, on payment, or always)
- Auto-create delivery when MELI shipment is marked shipped (configurable: manual, on shipped, or always)
- Auto-create invoice on order confirmation
- Fulfillment (Full) vs standard warehouse routing -- separate warehouse for MELI Fulfillment orders
- Pack order handling -- cart orders (multiple items) merged into a single sale order
- Order cancel with detail -- creates return pickings and credit notes
- Order total validation -- MELI paid amount vs Odoo order total
- Shipping product auto-added to order lines
- Delivery carrier auto-creation from MELI shipping method
- Tracking number sync to
stock.picking - Sales team and salesperson defaults for all imported orders
Buyer/Customer Management
- Full buyer billing info from MELI API including fiscal data
- Document type/number -- DNI, CUIT, RUT, RFC, CPF, and other LATAM document types
- Business name (razon social) and tax status
- Similar address deduplication -- fuzzy 82% match to avoid duplicate contacts
- Fiscal field protection -- prevent commercial sync from overwriting fiscal data
- Generic VAT handling -- configurable list of non-fiscal VAT numbers to ignore (e.g., XAXX010101000 for Mexico)
- Nickname and billing name imported from MELI
Inventory and Pricing
- Multi-warehouse stock sum -- select multiple warehouses to sum stock from when pushing to MELI
- Auto stock push on
stock.movevalidation -- every warehouse operation triggers a MELI update - Push Stock to MELI button on the configuration form
- Push Prices to MELI button on the configuration form
- Pricelist configuration -- use any Odoo pricelist for MELI pricing
- Tax-adjusted pricing -- auto, tax included, tax excluded, or no tax adjustment modes
- Multi-currency conversion -- Odoo company currency to MELI currency automatic conversion
- Real-time stock push cron -- 5-minute interval (disabled by default, enable when needed)
- Bulk price updater wizard -- percentage, fixed, or cost+markup adjustments with rounding to .99, .90, or integer
- Stock forecasting -- sales velocity calculation from past order history with days-until-out-of-stock prediction per product
- Reorder urgency color-coding -- critical (< 7 days), warning (< 14 days), healthy (14+ days) indicators
- Configurable forecast parameters -- lookback period and forecast horizon settings
Shipments
- Full shipment model (
mercadolibre.shipment) with receiver/sender addresses - PDF label download from MELI
- ZPL label download for thermal printers
- Print labels from shipment record, sale order, or stock picking
- Shipment auto-creation when importing orders
- Logistic type tracking -- drop_off, fulfillment, cross_docking, custom
- Shipping costs, delivery estimates, and handling limits
- Mercado Shops (Tiendas) channel tracking -- distinguish orders from the marketplace vs your Mercado Shop
- Flex delivery support with promise tracking for same-day/next-day delivery
- Channel field on shipments to identify source (marketplace vs mshops)
Communication
- Question/Answer management -- view and answer buyer questions directly from Odoo
- Webhook
/meli_notifyendpoint for real-time push notifications from MELI - Notification queue with state machine (received, processing, success, failed)
- Retry failed notifications -- up to 3 attempts with error tracking
- Invoice sending via MELI messaging API
- Buyer messaging support
Accounting
- MercadoLibre sales journal configuration
- MercadoPago payment journal for payment registration
- Fee expense account for MELI commission tracking
- Shipping expense account for delivery cost tracking
- Auto payment registration and reconciliation when invoices are confirmed
Claims and Returns
- Claims/returns model (
mercadolibre.claim) with type tracking - Create return picking from claim
- Create credit note from claim
- Buyer, amount, and resolution tracking
Advertising / Ads Integration
- Ad campaign management -- import and track MELI advertising campaigns with performance metrics
- Campaign types: Product Ads, Display Ads, Brand Ads
- Performance metrics -- impressions, clicks, CTR, ACOS (advertising cost of sales), CPC (cost per click)
- Per-product ad performance tracking -- link ad spend and results to individual Odoo products
- Sync campaign data from the MELI Ads API via scheduled cron job
Promotions and Coupons
- Promotion management -- create and track MELI promotions, discounts, and special offers
- Coupon system with discount types: percentage, fixed amount, free shipping, and campaign-linked coupons
- Coupon usage tracking -- monitor coupon redemptions and sync status (pending, synced, failed, updated)
Margin Analysis
- Per-product margin calculator accessible from Operations menu
- Sale price vs cost vs MELI fee vs shipping breakdown
- Color-coded margins -- danger (< 0%), warning (< 10%), success (> 20%)
Multi-Account Support
- Multiple MELI accounts per company -- connect Argentina, Brazil, Mexico, etc. simultaneously
- Per-account pricelist and warehouse overrides
- Product-account bindings with status tracking
- SKU mapping rules -- exact, prefix, suffix, regex, or formula match modes
- Pack/kit component rules for bundled products
Advanced Features
- Size guide charts from MELI API
- API benchmarking -- timing and slow call detection
- MELI multi-warehouse API support (for sellers with multiple MELI warehouses)
- OAuth browser login flow -- click "Login with MercadoLibre" and the module handles the entire OAuth flow automatically (no manual token paste needed)
- Currency mapping model -- map store currencies to MELI platform currencies with automatic conversion
- Coupon model with usage tracking
- Process history model for full audit trail of all operations
- Payment gateway model for payment method tracking and MercadoPago integration
Infrastructure
- OWL 2 Dashboard with 9+ KPI cards (revenue, orders, customers, products, shipments pending, questions unanswered, notifications failed)
- 13 automated cron jobs -- products (1h), orders (30m), customers (6h), inventory (15m), real-time stock push (5m), push products (30m), push prices (2h), questions (30m), notifications (5m), reviews (6h), ad campaigns (6h), connection test (daily), log cleanup (daily)
- Translations -- es_AR (Argentine Spanish, 100+ strings), es (Generic Spanish, 100+ strings), pt_BR (Brazilian Portuguese, 178 strings)
- 50+ models, 79 Python files, 41 XML views, 3 translation files
- 194 automated tests across 22 test files covering all models (shipments, notifications, questions, categories, orders, SKU rules, claims, margins, accounts, stock push, security, cron, webhooks, wizards, workflows, performance) -- all API calls mocked
- Multi-company support with record rules and
company_idisolation - Priority queue system with batch processing and retry logic
- Comprehensive sync logging -- full audit trail of every operation
Import Wizard: What Each Option Does
Open the wizard at Operations > Import Wizard. The wizard always pulls data FROM MercadoLibre INTO Odoo.
Choosing what to import
Tick any combination of:
| Checkbox | What it pulls |
|---|---|
| Import Products | Your MercadoLibre listings -- title, price, stock, images, category |
| Import Orders | Paid and confirmed orders with buyer info and payment details |
| Import Customers | Buyer profiles extracted from recent orders |
| Import Inventory | Stock quantities from MercadoLibre adjusted back into Odoo |
Order Date Range (filtering by date)
When Import Orders is ticked, an Order Date Range section appears with two date fields:
- Orders From -- only import orders created on or after this date
- Orders To -- only import orders created on or before this date (the "To" day is included)
Leave both empty to import a recent batch (the module fetches the latest orders up to the Import Limit). Set a range to import only orders from a specific period. This is the correct tool when you have already entered some orders manually and want to avoid duplicates from an earlier date range.
Validation: "Orders From" must be on or before "Orders To". The wizard raises a clear error if the range is inverted.
Import Limit
The Import Limit field (default 100) caps how many records are pulled per type in one wizard run. Raise it if you need a larger batch; the cron jobs have no per-run limit.
Product matching and the "Map Existing Only" option
The Import Wizard matches an incoming MercadoLibre item to an existing Odoo product by:
mercadolibre_product_id(the MELI item ID, already stored from a prior import)- Internal Reference (SKU /
default_code) -- exact match - Product name -- exact match
When a match is found, the module links and updates the existing product rather than creating a duplicate.
Map Existing Only (No Create): tick this option to prevent any new Odoo products from being created. Only products that already exist in Odoo will be linked or updated; unmatched MELI items are skipped. Use this when you want to link a batch of MELI listings to products you have already set up in Odoo by SKU, without letting the import create new product records.
Preview before committing
Click Preview before clicking Start Import to see exactly what will happen to each product and customer:
- create -- a new Odoo record will be created
- map -- an existing record will be linked by SKU/email/name (no data overwrite)
- update -- an existing record will be linked and its data refreshed
- skip -- the record will not be touched (Map Existing Only mode, or no match found)
The preview does not make any changes; it is read-only.
Reading the import result
After the import runs, the result message shows a per-type summary:
Products: 12 created, 5 updated, 3 linked, 0 skipped, 0 failed.
Orders: 0 created, 0 updated, 0 linked, 2 skipped, 1 failed.
Customers: nothing found on MercadoLibre to import.
If nothing changed at all and there were errors, a sticky warning lists the first five error reasons and points you to the Sync Logs for the full list.
Export Wizard: Publishing Products to MercadoLibre
Open the wizard at Operations > Export Wizard. The wizard pushes data FROM Odoo TO MercadoLibre.
The "Publish to MercadoLibre" toggle
Only products with the "Publish to MercadoLibre" toggle turned ON are ever sent to MercadoLibre. Products without the toggle are completely ignored by the Export Wizard and by the auto-push cron jobs.
To turn on the toggle for a product:
- Go to Products (in the MercadoLibre app) or open a product form from the regular Odoo products menu
- Open the MercadoLibre tab
- Switch on Publish to MercadoLibre (
meli_pub) - Fill in the required fields (category, price, at least one image -- see requirements below)
- Save
If no products have the toggle on and you run the Export Wizard, you will see a clear "Nothing to Export" warning explaining exactly what to do.
SKU-based deduplication (avoiding duplicate listings)
When exporting a product that is not yet linked to a MercadoLibre item, the module first searches MercadoLibre for an existing listing with the same Internal Reference (SKU):
- If found: the module links the Odoo product to that existing MELI listing instead of creating a new one. The counter shows "linked by SKU".
- If not found: the module creates a new listing on MercadoLibre.
This prevents duplicate listings when you already sell the same product on MercadoLibre and are importing/linking for the first time.
MercadoLibre publish requirements
A product that fails any of these requirements is skipped (not failed) with an explanation in the result message:
| Requirement | Detail |
|---|---|
| Price > 0 | The listing price (from MELI Price field, pricelist, or product list price) must be greater than zero |
| Valid leaf category | The product must have a MELI Category assigned that is a leaf (non-parent) in the MercadoLibre category tree |
| At least one image | MercadoLibre rejects listings without at least one product image |
| Required category attributes | Some categories require specific attributes (e.g. Brand, Model, size). Load them with "Load MELI Category Attributes" and fill the values |
| Package weight in grams | For MELI Fulfillment (Full) and Flex sellers: Package Weight (g) must be a positive integer (whole grams, not kg). Package dimensions (Height, Width, Length) must also be in whole centimetres |
| Title length | The MELI title must be at least 4 characters. If the MELI Title override field is empty, the product name is used |
Reading the export result
The export result is always honest. You will see one of three outcomes:
Nothing to Export (sticky warning): no products have the "Publish to MercadoLibre" toggle on. Turn on the toggle and try again.
Nothing Exported -- skipped/failed (sticky warning): products with the toggle on were found but every one was blocked. The message names the reasons (e.g. "price must be > 0", "MELI Category not set"). Review the per-product errors in Sync Logs.
Export Finished (success): a summary shows how many products were created, updated, linked by SKU, skipped, or failed.
Prerequisites
Before you begin, make sure you have:
- Odoo 17, 18, or 19 (Community or Enterprise edition)
- An active ECOSIRE license for the MercadoLibre Store Management module
- A MercadoLibre seller account in one of the 18 supported countries
- MercadoLibre Developer App credentials -- see Setup Guide for step-by-step instructions
Installation
Option A: Upload via Odoo UI
- Download the module ZIP from your ECOSIRE Dashboard
- In Odoo, go to Settings > Developer Tools > Activate Developer Mode
- Go to Apps > Upload Module and upload the ZIP file
- Click Install
Option B: Manual Installation (Server)
# 1. Download and extract to your Odoo addons directory
unzip ecosire-mercadolibre-store-management-*.zip -d /opt/odoo/addons/
# 2. Restart the Odoo service
sudo systemctl restart odoo
# 3. In Odoo: Apps > Update Apps List > Search "MercadoLibre" > Install
Option C: Install via CLI
# Install directly via Odoo CLI
python odoo-bin -c /etc/odoo.conf -d your_database -i mercadolibre_store_management --stop-after-init
After installation, activate your ECOSIRE license at Settings > ECOSIRE > License Activation.
Configuration
Step 1: Create a MercadoLibre Developer App
- Go to developers.mercadolibre.com and sign in with your MercadoLibre seller account
- Click Create Application (or "Crear aplicacion")
- Fill in the application details:
- Application Name: e.g., "My Odoo Integration"
- Short Description: e.g., "Odoo ERP integration for order and inventory management"
- Redirect URI:
https://your-odoo-domain.com/meli_login - Scopes: Select
read,write, andoffline_access
- After creation, note these credentials:
- Client ID (App ID) -- a numeric ID like
1234567890123456 - Client Secret -- a string like
AbCdEf1234567890AbCdEf1234567890
- Client ID (App ID) -- a numeric ID like
The Client ID is public (shown in API URLs), but the Client Secret must be kept confidential.
Step 2: Connect via OAuth (Recommended)
The module includes a built-in OAuth login flow that handles token exchange automatically:
- Navigate to MercadoLibre app > Configuration > Settings
- Click New to create a configuration
- Enter your Client ID and Client Secret from Step 1
- Select your Site / Country (e.g., Argentina MLA)
- Set the Redirect URI to
https://your-odoo-domain.com/meli_login - Click Login with MercadoLibre -- a browser window opens for authorization
- Sign in to MercadoLibre and click Allow
- You are redirected back to Odoo with tokens automatically saved
If the OAuth login button does not work (e.g., Odoo behind a reverse proxy without public access), see the manual token setup in the integration guide.
Step 3: Configure Commerce Settings
In the configuration form, set up your commerce preferences:
| Field | Description |
|---|---|
| Pricelist | Odoo pricelist to use for MELI price exports. Leave empty for product list price. |
| Warehouse | Default warehouse for stock sync. Uses company default if empty. |
| Warehouses (Multi-Location) | Select multiple warehouses to sum stock from when pushing to MELI. |
| MELI Currency | Currency used on MercadoLibre. Prices auto-convert from Odoo company currency. |
| Tax Handling | Auto (use product taxes), tax included, tax excluded, or no tax adjustment. |
| Generic VAT Numbers | Comma-separated non-fiscal VAT numbers to ignore (e.g., XAXX010101000 for Mexico). |
Step 4: Configure Order Processing
In the Order Processing section:
| Field | Options | Description |
|---|---|---|
| Order Confirmation | Manual / Auto on Payment / Always | When to auto-confirm imported sale orders |
| Delivery Processing | Manual / Auto on Shipped / Always | When to auto-validate delivery orders |
| Auto Create Invoice | On/Off | Create invoice automatically on order confirmation |
| Fulfillment Warehouse | Warehouse | Separate warehouse for MELI Fulfillment (Full) orders |
| Sales Team | CRM Team | Default sales team for imported orders |
| Salesperson | User | Default salesperson for imported orders |
| Import Orders From/Until | Date range | Filter orders by creation date |
Step 5: Configure Accounting
In the Accounting section:
| Field | Description |
|---|---|
| MercadoLibre Sales Journal | Sale-type journal for MELI invoices |
| MercadoPago Payment Journal | Bank/cash journal for payment registration |
| MELI Fee Expense Account | Expense account for MELI commission fees |
| Shipping Expense Account | Expense account for delivery costs |
| Auto Register Payment | Automatically register MercadoPago payment when invoice is confirmed |
Step 6: Run Initial Sync
- Click Test Connection to verify your credentials
- Click Sync Products to import your MercadoLibre listings
- Click Sync Orders to import recent orders (buyers are automatically created as customers)
- Go to Dashboard to see your KPIs populate
To sell on multiple MercadoLibre sites (e.g., Argentina AND Brazil), create a separate configuration for each site with its own credentials. The module supports unlimited configurations.
Navigation Guide
After installation, the MercadoLibre app appears in your Odoo home menu with these sections:
| Menu | Description |
|---|---|
| Dashboard | Real-time KPIs (9+ cards), sales trend chart, order status doughnut, activity feed, quick actions |
| MELI Orders | Dedicated MercadoLibre order model with items, payments, buyers, amounts, and status tracking |
| Orders | Odoo sale orders created from MELI imports |
| Products | Imported product listings from MercadoLibre |
| Customers | Buyer profiles extracted from orders with fiscal data |
| Shipments | Shipment tracking with labels (PDF/ZPL), addresses, logistic types |
| Questions | Buyer questions with inline answer capability |
| Reviews | Imported buyer reviews with ratings, content, vote counts, and seller responses |
| Claims / Returns | Claims and returns with return picking and credit note creation |
| Advertising | Ad campaigns with performance metrics (impressions, clicks, CTR, ACOS, CPC) |
| Operations | Import Wizard, Export Wizard, Mapping Wizard, Test Connection, Margin Analysis, Bulk Price Update, Stock Forecast, Logs, Reports, Notifications |
| Configuration | Settings, Buyers, Categories, Category Import Wizard, Description Templates, Accounts, SKU Rules, Size Charts |
Form View Integration
The module adds a MercadoLibre tab to existing Odoo forms:
| Form | Tab Contents |
|---|---|
| Product Template | Publishing fields, lifecycle buttons (pause/activate/close), category, banner template, listing type, MELI item ID |
| Sale Order | MELI amounts (total, paid, coupon), shipping info, label download buttons, cancel with detail |
| Contact (Partner) | Fiscal data: document type, document number, business name, tax status, MELI nickname |
Sync Details
How Product Sync Works
Import (MercadoLibre to Odoo):
- The module calls
/users/{user_id}/items/searchto get all your item IDs - Items are fetched in batches of 20 via
/items?ids=... - Each item is matched to an Odoo product by
mercadolibre_product_id, then by SKU, then by exact name - New products are created as
product.templaterecords; existing ones are updated - Price, stock, title, description, images, and category are synchronized
- Configurable overwrite rules control whether name, description, and price are updated on existing products
Export (Odoo to MercadoLibre):
- Select products in Odoo and use the Export Wizard or Batch Publish Wizard
- The module creates MercadoLibre listings via
POST /items - Category is auto-predicted from the product title using MELI's category predictor API
- Images are uploaded with blake2b deduplication (avoids re-uploading unchanged images)
- Variants are published as MELI variations
How Order Sync Works
- The module calls
/orders/searchwith your seller ID and optional date range filters - Each order is stored in both the dedicated
mercadolibre.ordermodel and as an Odoosale.order - For each order, the buyer is resolved:
- First lookup by MercadoLibre buyer ID
- Then by email address
- If not found, a new
res.partneris created with full fiscal data (name, email, phone, document type/number, business name)
- A
sale.orderis created with:- Order lines matching each MELI item (linked to Odoo products by MELI item ID or SKU)
- Shipping product auto-added as an order line
- MercadoLibre order status (paid, confirmed, cancelled, etc.)
- Payment information from MercadoPago
- Based on configuration, orders are auto-confirmed, deliveries auto-created, and invoices auto-generated
How Inventory Sync Works
Pull (MELI to Odoo):
- The module fetches all active items with quantities
- For each item, it finds the matching Odoo product
- Compares MELI
available_quantitywith Odoo's on-hand stock - Creates
stock.quantadjustments for any differences
Push (Odoo to MELI):
- Stock levels are summed across configured warehouses (multi-warehouse support)
- Stock is pushed to MELI via
PUT /items/{id}with theavailable_quantityfield - Auto-push triggers on every
stock.movevalidation - Real-time stock push cron runs every 5 minutes (when enabled)
How Customer Sync Works
MercadoLibre does not have a standalone customer listing API. Instead:
- The module fetches recent orders (up to 500)
- Unique buyers are extracted by their MercadoLibre user ID
- Each buyer is created/updated as a
res.partnerwith full data: name, email, nickname, phone, document type, document number, business name (razon social), tax status - Similar address deduplication (82% fuzzy match) prevents duplicate contacts
Cron Jobs
The module installs 13 automated scheduled actions:
| Cron Job | Interval | Default State | Description |
|---|---|---|---|
| Sync Products | 1 hour | Active | Import product updates from MELI |
| Sync Orders | 30 minutes | Active | Import new and updated orders |
| Sync Customers | 6 hours | Active | Extract buyers from recent orders |
| Sync Inventory | 15 minutes | Active | Pull stock levels from MELI |
| Real-time Stock Push | 5 minutes | Inactive | Push Odoo stock to MELI in near real-time |
| Auto Push Products | 30 minutes | Inactive | Push product changes to MELI |
| Auto Push Prices | 2 hours | Inactive | Push price changes to MELI |
| Sync Questions | 30 minutes | Active | Import buyer questions |
| Process Notifications | 5 minutes | Active | Process queued webhook notifications |
| Sync Reviews | 6 hours | Active | Import buyer reviews and ratings from MELI |
| Sync Ad Campaigns | 6 hours | Active | Import advertising campaign performance data |
| Test Connection | 1 day | Active | Verify API connectivity |
| Cleanup Old Logs | 1 day | Active | Remove old sync log entries |
Real-time stock push, auto push products, and auto push prices are disabled by default. Enable them in Settings > Technical > Scheduled Actions when you are ready for bidirectional sync.
API Reference
| Field | Value |
|---|---|
| Auth Method | OAuth 2.0 (Authorization Code + Refresh Token) |
| Base URL | https://api.mercadolibre.com |
| Token URL | https://api.mercadolibre.com/oauth/token |
| Rate Limits | Per-app limits; module handles 429 with exponential backoff (max 3 retries) |
| Token Expiry | 6 hours (auto-refreshed by the module with 5-minute buffer) |
| Webhook Endpoint | /meli_notify (POST for notifications, GET for health check) |
| OAuth Callback | /meli_login (handles authorization code exchange) |
Changelog
v1.1.0 (2026-03-26) -- Deep Fix + New Features
- 133 API methods (up from ~80) -- most comprehensive MELI-Odoo integration available
- Fixed: OWL dashboard crash from duplicate XML IDs on Orders page
- Fixed: Category prediction using new domain_discovery/search endpoint (old category_predictor/predict deprecated)
- Fixed: Product export 400 errors -- 5 root causes resolved:
- Warranty field migrated to sale_terms API with WARRANTY_TYPE value_ids
- Description updates via separate PUT endpoint
- Paused items auto-activated before updates
- Catalog-locked listings detected and locked fields skipped
- Required category attributes auto-included
- New: Warranty management (seller/factory/none with Spanish duration)
- New: Installments configuration (no-fee, 3/6/9/12 month promo plans)
- New: Pack quantity (units per listing)
- New: Claims API (get, respond, upload evidence)
- New: Returns API (get, accept, reject, shipping labels)
- New: Financial APIs (settlements, billing, account balance, movements)
- New: Review management (reply, report)
- New: Seller metrics and item health scores
- All fixes E2E tested with real MELI API (12 endpoints verified live)
v1.0.0 (2026-03-24) -- Initial Release
- 80+ features across products, orders, inventory, shipments, Q and A, ads, accounting
- 50+ models, 79 Python files, 194 automated tests
- OWL 2 dashboard, 13 cron jobs, 3 translations (es_AR, es, pt_BR)
- OAuth 2.0 browser login flow
- 18 Latin American country support
Supported API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/users/me | GET | Get authenticated user info |
/users/{id}/items/search | GET | List seller's items (paginated) |
/items/{id} | GET | Get item details |
/items | POST | Create new listing |
/items/{id} | PUT | Update/pause/activate/close item |
/items?ids=... | GET | Multi-get items (batches of 20) |
/orders/search | GET | Search orders (paginated) |
/orders/{id} | GET | Get order details |
/shipments/{id} | GET/PUT | Get/update shipment |
/shipment_labels | GET | Generate shipping label (PDF/ZPL) |
/questions/search | GET | Get buyer questions |
/answers | POST | Answer a question |
/messages/packs/{id}/sellers/{id} | GET/POST | Buyer messaging |
/sites/{id}/categories | GET | Get category tree |
/sites/{id}/category_predictor/predict | GET | Auto-predict category from title |
/sites/{id}/size_charts | GET | Get size guide charts |
/reviews/item/{id} | GET | Get buyer reviews for a listing |
/advertising/campaigns | GET | Get ad campaigns and performance metrics |
/oauth/token | POST | Token exchange and refresh |
Changelog
v1.1.0 (2026-03-26) -- Deep Fix + New Features
- 133 API methods (up from ~80) -- most comprehensive MELI-Odoo integration available
- Fixed: OWL dashboard crash from duplicate XML IDs on Orders page
- Fixed: Category prediction using new domain_discovery/search endpoint (old category_predictor/predict deprecated)
- Fixed: Product export 400 errors -- 5 root causes resolved:
- Warranty field migrated to sale_terms API with WARRANTY_TYPE value_ids
- Description updates via separate PUT endpoint
- Paused items auto-activated before updates
- Catalog-locked listings detected and locked fields skipped
- Required category attributes auto-included
- New: Warranty management (seller/factory/none with Spanish duration)
- New: Installments configuration (no-fee, 3/6/9/12 month promo plans)
- New: Pack quantity (units per listing)
- New: Claims API (get, respond, upload evidence)
- New: Returns API (get, accept, reject, shipping labels)
- New: Financial APIs (settlements, billing, account balance, movements)
- New: Review management (reply, report)
- New: Seller metrics and item health scores
- All fixes E2E tested with real MELI API (12 endpoints verified live)
v1.0.0 (2026-03-24) -- Initial Release
- 80+ features across products, orders, inventory, shipments, Q and A, ads, accounting
- 50+ models, 79 Python files, 194 automated tests
- OWL 2 dashboard, 13 cron jobs, 3 translations (es_AR, es, pt_BR)
- OAuth 2.0 browser login flow
- 18 Latin American country support
Supported Countries
| Code | Country | Currency |
|---|---|---|
| MLA | Argentina | ARS |
| MLB | Brazil | BRL |
| MLC | Chile | CLP |
| MCO | Colombia | COP |
| MLM | Mexico | MXN |
| MLU | Uruguay | UYU |
| MPE | Peru | PEN |
| MEC | Ecuador | USD |
| MCR | Costa Rica | CRC |
| MRD | Dominican Republic | DOP |
| MPA | Panama | USD |
| MHN | Honduras | HNL |
| MNI | Nicaragua | NIO |
| MSV | El Salvador | USD |
| MGT | Guatemala | GTQ |
| MBO | Bolivia | BOB |
| MPY | Paraguay | PYG |
| MLV | Venezuela | VES |
Dashboard
The built-in OWL 2 dashboard provides real-time visibility into your MercadoLibre integration:
- 9+ KPI cards -- Revenue, Orders, Customers, Products, Avg Order Value, Sync Health, Shipments Pending, Questions Unanswered, Notifications Failed -- each with period-over-period delta indicators (up/down arrows with percentage change)
- Sales Trend chart (Chart.js line chart) with interactive date filtering
- Order Status breakdown (doughnut chart) showing distribution across Completed, Pending, Failed, and Cancelled
- Period filters -- Today, 7 Days, 30 Days, 90 Days, Year, or Custom date range
- Recent Activity feed showing sync log entries with type indicators (success/error/warning)
- Quick action buttons for Products, Orders, Customers, Queue, Logs, and Settings
- Status footer with Queue Jobs, Errors, Out of Stock, and Sync Rate
- Auto-refresh every 60 seconds
- Dark mode support (automatic via CSS custom properties)
- Responsive design for mobile, tablet, and desktop
Webhook Setup
For real-time updates instead of polling, configure MercadoLibre webhooks:
- In your MercadoLibre Developer Portal, go to your app's Webhooks section
- Add a callback URL:
https://your-odoo-domain.com/meli_notify - Subscribe to these topics:
| Topic | Description |
|---|---|
orders_v2 | New orders and order status changes |
items | Product listing updates |
questions | New buyer questions |
payments | Payment status changes |
shipments | Shipping status updates |
claims | Dispute/claim notifications |
messages | Buyer messages |
- The module's
/meli_notifyendpoint receives notifications, queues them in the notification model, and processes them via a 5-minute cron job - Failed notifications are retried up to 3 times
The /meli_notify endpoint supports both POST (notifications) and GET (health checks). MELI sends plain JSON -- the module handles parsing automatically.
Wizards
| Wizard | Menu Location | Direction | Description |
|---|---|---|---|
| Import Wizard | Operations > Import Wizard | MELI → Odoo | Pull products, orders, customers, inventory. Supports date-range filtering for orders and a Map Existing Only mode. Click Preview before Start Import to review planned actions. |
| Import Preview Wizard | (via Import Wizard > Preview button) | Read-only | Shows each incoming record's planned action: create / map / update / skip |
| Export Wizard | Operations > Export Wizard | Odoo → MELI | Publish/update listings and push stock. Only processes products with the "Publish to MercadoLibre" toggle on. Provides honest skip/fail detail when nothing was sent. |
| Batch Publish Wizard | (via product list action) | Odoo → MELI | Mass-publish multiple products at once |
| Batch Update Wizard | (via product list action) | MELI → Odoo | Mass-refresh product data from MELI |
| Mapping Wizard | Operations > Mapping Wizard | -- | Map MELI categories, payment methods, and fields to Odoo equivalents |
| Bulk Price Update | Operations > Bulk Price Update | Odoo → MELI | Apply percentage, fixed, or cost+markup price adjustments with rounding options (.99, .90, integer) |
| Category Import Wizard | Configuration > Category Import | MELI → Odoo | Import MELI category tree for a specific site |
| Test Connection Wizard | Operations > Test Connection | -- | Verify API credentials and connectivity |
Troubleshooting
| Issue | Solution |
|---|---|
| "Connection failed" | Verify Client ID and Secret are correct; ensure your app is approved in the Developer Portal |
| "Token refresh failed" | Re-do the OAuth flow by clicking "Login with MercadoLibre". Tokens may be revoked if you change your password |
| "Rate limit exceeded" | The module handles this automatically with exponential backoff. If persistent, reduce sync frequency in cron settings |
| Sync not running | Check Settings > Technical > Scheduled Actions -- ensure MercadoLibre crons are enabled and not paused |
| Duplicate products on import | The module matches by MELI Item ID first, then SKU (Internal Reference), then exact name. If duplicates were created before SKU matching was set up, use the Mapping Wizard or merge via Odoo's standard duplicate-merge feature |
| Export shows "Nothing to Export" | No products have the "Publish to MercadoLibre" toggle on. Open each product's MercadoLibre tab and switch on the Publish to MercadoLibre field, then re-run the export |
| Export ran but nothing appeared on MELI | Open the result message or Sync Logs -- the product was likely skipped. Check: price > 0, MELI Category set, at least one image attached, required category attributes filled, package weight and dimensions set (for Flex/Full sellers) |
| "I clicked Export and nothing happened" | The wizard previously showed a silent success toast. It now shows a sticky warning with the skip reason. Check the Result Message in the wizard and the Sync Logs at Operations > Logs |
| Import brought in all historical orders | Use the Order Date Range in the Import Wizard: set "Orders From" to the first date you want and "Orders To" to the last date. Only orders in that window are imported |
| Orders not importing | Verify your seller ID matches the authenticated user; use the Import Wizard date range fields to narrow the window; check Operations > Logs for error detail |
| Wrong country/site | Update the Site / Country field in Configuration to match your ML seller account |
| "License required" | Activate your ECOSIRE license at Settings > ECOSIRE > License Activation |
| Products showing 0 stock | Check warehouse configuration; run Push Stock manually from Configuration; verify multi-warehouse selection |
| Shipping labels not downloading | Verify MercadoEnvios is enabled on your ML seller account. Labels require the shipment to be in "ready_to_ship" status |
| MercadoPago mismatch | Map MercadoPago payment methods to Odoo journals using the Mapping Wizard |
| Webhook notifications not processing | Verify the /meli_notify URL is publicly accessible; check Operations > Notifications for failed entries |
| Duplicate customers | Adjust the generic VAT list or merge duplicates via Odoo's partner merge wizard |
| Prices not updating on MELI | Check pricelist, currency, and tax handling configuration; verify the product is not paused/closed on MELI |
| OAuth login not redirecting | Ensure the Redirect URI in the Developer Portal matches exactly: https://your-odoo-domain.com/meli_login |
| Export skips with "price must be > 0" | The product's effective MELI price (MELI Price override, or pricelist, or list price) is zero or negative. Set a price before publishing |
| Export skips with "category missing" | Assign a leaf-level MELI Category in the product's MercadoLibre tab. Use Configuration > Category Import Wizard to load the category tree first |
Common Tasks
Import only orders from a date range
- Go to Operations > Import Wizard
- Untick Import Products, Import Customers, and Import Inventory -- leave only Import Orders ticked
- Set Orders From to the first date you want (e.g.
2025-01-01) - Set Orders To to the last date you want (e.g.
2025-01-31) - Adjust Import Limit if you expect more than 100 orders in that range
- Click Start Import
The result message confirms how many orders were created, updated, linked, skipped, or failed.
Link products I already have in both Odoo and MercadoLibre (no duplicates)
Via Import (MELI to Odoo):
- Go to Operations > Import Wizard
- Tick Import Products and tick Map Existing Only (No Create)
- Click Preview to confirm which products will be linked vs skipped
- Click Start Import
The import matches each MELI listing to an Odoo product by MELI item ID, then by Internal Reference (SKU), then by name. Matched products are linked; unmatched ones are skipped (not created).
Via Export (Odoo to MELI):
- Open the product in Odoo, go to its MercadoLibre tab, and switch on Publish to MercadoLibre
- Make sure the product's Internal Reference (SKU) matches the SKU on the MercadoLibre listing
- Go to Operations > Export Wizard and click Start Export
The export searches MercadoLibre for a listing with the same SKU. If found, it links to that listing instead of creating a duplicate. The result shows "linked by SKU" for these products.
Publish an Odoo product to MercadoLibre
- Open the product and go to its MercadoLibre tab
- Switch on Publish to MercadoLibre
- Verify the required fields are filled:
- MELI Category (a leaf category -- use Configuration > Category Import Wizard if the list is empty)
- Price greater than zero (use the MELI Price field for an override, or leave it blank to use the pricelist/list price)
- At least one product image
- Required category attributes (click "Load MELI Category Attributes" to fetch them, then fill the values)
- For Flex/Full: Package Weight (g) and dimensions in whole centimetres
- Go to Operations > Export Wizard and click Start Export
- Read the result message. If the product was skipped, the message explains why.
I clicked Export and nothing happened
Before v19.0.2.0.15 the Export Wizard showed a silent "success" toast even when no products were sent. This is now fixed. You will always see one of:
- "Nothing to Export" (sticky warning) -- no products have the toggle on. Turn on Publish to MercadoLibre on the products you want to publish.
- "Nothing Exported -- N skipped, N failed" (sticky warning) -- products with the toggle on were found but every one was blocked. Read the reasons listed (price, category, images, attributes) and fix each product.
- "Export Finished: N created, N updated, N linked" -- success.
Avoid duplicate listings
- On import: the module matches by MELI item ID then SKU then name and links rather than duplicates. Use "Map Existing Only (No Create)" to be safe on first import.
- On export: the module checks whether a MELI listing with the same SKU already exists before creating a new one. If you have products with no Internal Reference set, assign one before running Export.
Frequently Asked Questions
Q: Do I need a MercadoLibre Pro account? A: You need an active seller account. Both free and premium seller accounts are supported.
Q: Can I connect multiple MercadoLibre sites? A: Yes. Create a separate configuration for each country site (e.g., one for Argentina MLA, another for Brazil MLB). The module supports unlimited configurations.
Q: Does the module support Mercado Shops (Mercado Shops / Tiendas)? A: Yes. The module tracks the sales channel (marketplace vs mshops) on each shipment and order. Orders from your Mercado Shop and from the marketplace are both imported and can be filtered by channel. Flex delivery promises are also tracked for Mercado Shops orders.
Q: How often are tokens refreshed? A: Automatically every 6 hours. The module checks token expiry before each API call and refreshes proactively with a 5-minute buffer.
Q: What happens if the API is down? A: Sync operations are logged with error status. Failed items are retried in the next sync cycle. The dashboard shows sync health percentage.
Q: Can I sync historical orders? A: Yes. Use the Order Date Range fields (Orders From / Orders To) in the Import Wizard. Set both dates to define the exact window. The Import Limit caps how many records are pulled per run.
Q: How does the bulk price updater work? A: Go to Operations > Bulk Price Update. Select products, choose an adjustment method (percentage, fixed amount, or cost + markup), set rounding rules (.99, .90, or integer), and apply. Prices are updated in Odoo and pushed to MELI.
Q: Can I prevent stock from being pushed for certain products? A: Yes. Enable the "Block Stock Updates" flag on specific product templates in the MercadoLibre tab. Those products will be skipped during stock push operations.
Q: Why does the import show "nothing found on MercadoLibre to import" for orders? A: Either your date range returned no orders, you reached the Import Limit with no matching results, or your seller account has no orders in the queried window. Try widening the date range or removing the range entirely. Check Operations > Logs for the raw API response.
Q: The import result says products were "linked" -- what does that mean? A: "Linked" means an existing Odoo product was matched and connected to a MercadoLibre listing (by MELI item ID, SKU, or name) but its data was not overwritten. Subsequent syncs and cron jobs will keep it updated.
Q: How do claims/returns work? A: Claims imported from MELI appear in the Claims/Returns menu. From each claim, you can create a return picking (reverse stock movement) and/or a credit note for refund processing.
Q: Does the module support MercadoLibre Fulfillment (Full)? A: Yes. Configure a separate Fulfillment Warehouse in the settings. Orders shipped via MELI Fulfillment are routed to that warehouse automatically.
Changelog
v1.1.0 (2026-03-26) -- Deep Fix + New Features
- 133 API methods (up from ~80) -- most comprehensive MELI-Odoo integration available
- Fixed: OWL dashboard crash from duplicate XML IDs on Orders page
- Fixed: Category prediction using new domain_discovery/search endpoint (old category_predictor/predict deprecated)
- Fixed: Product export 400 errors -- 5 root causes resolved:
- Warranty field migrated to sale_terms API with WARRANTY_TYPE value_ids
- Description updates via separate PUT endpoint
- Paused items auto-activated before updates
- Catalog-locked listings detected and locked fields skipped
- Required category attributes auto-included
- New: Warranty management (seller/factory/none with Spanish duration)
- New: Installments configuration (no-fee, 3/6/9/12 month promo plans)
- New: Pack quantity (units per listing)
- New: Claims API (get, respond, upload evidence)
- New: Returns API (get, accept, reject, shipping labels)
- New: Financial APIs (settlements, billing, account balance, movements)
- New: Review management (reply, report)
- New: Seller metrics and item health scores
- All fixes E2E tested with real MELI API (12 endpoints verified live)
v1.0.0 (2026-03-24) -- Initial Release
- 80+ features across products, orders, inventory, shipments, Q and A, ads, accounting
- 50+ models, 79 Python files, 194 automated tests
- OWL 2 dashboard, 13 cron jobs, 3 translations (es_AR, es, pt_BR)
- OAuth 2.0 browser login flow
- 18 Latin American country support