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

---

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 from sale.order for 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.move validation -- 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_notify endpoint 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_id isolation
• Priority queue system with batch processing and retry logic
• Comprehensive sync logging -- full audit trail of every operation

---

Prerequisites

Before you begin, make sure you have:

1. Odoo 17, 18, or 19 (Community or Enterprise edition)
2. An active ECOSIRE license for the MercadoLibre Store Management module
3. A MercadoLibre seller account in one of the 18 supported countries
4. MercadoLibre Developer App credentials -- see Setup Guide for step-by-step instructions

---

Installation

Option A: Upload via Odoo UI

1. Download the module ZIP from your ECOSIRE Dashboard
2. In Odoo, go to Settings > Developer Tools > Activate Developer Mode
3. Go to Apps > Upload Module and upload the ZIP file
4. 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

1. Go to developers.mercadolibre.com and sign in with your MercadoLibre seller account
2. Click Create Application (or "Crear aplicacion")
3. 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, and offline_access
4. After creation, note these credentials:
   • Client ID (App ID) -- a numeric ID like 1234567890123456
   • Client Secret -- a string like AbCdEf1234567890AbCdEf1234567890

tip

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:

1. Navigate to MercadoLibre app > Configuration > Settings
2. Click New to create a configuration
3. Enter your Client ID and Client Secret from Step 1
4. Select your Site / Country (e.g., Argentina MLA)
5. Set the Redirect URI to https://your-odoo-domain.com/meli_login
6. Click Login with MercadoLibre -- a browser window opens for authorization
7. Sign in to MercadoLibre and click Allow
8. You are redirected back to Odoo with tokens automatically saved

Manual Token Flow (Fallback)

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

1. Click Test Connection to verify your credentials
2. Click Sync Products to import your MercadoLibre listings
3. Click Sync Orders to import recent orders (buyers are automatically created as customers)
4. Go to Dashboard to see your KPIs populate

Multi-Site Setup

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):

1. The module calls /users/{user_id}/items/search to get all your item IDs
2. Items are fetched in batches of 20 via /items?ids=...
3. Each item is matched to an Odoo product by mercadolibre_product_id, then by SKU, then by exact name
4. New products are created as product.template records; existing ones are updated
5. Price, stock, title, description, images, and category are synchronized
6. Configurable overwrite rules control whether name, description, and price are updated on existing products

Export (Odoo to MercadoLibre):

1. Select products in Odoo and use the Export Wizard or Batch Publish Wizard
2. The module creates MercadoLibre listings via POST /items
3. Category is auto-predicted from the product title using MELI's category predictor API
4. Images are uploaded with blake2b deduplication (avoids re-uploading unchanged images)
5. Variants are published as MELI variations

How Order Sync Works

1. The module calls /orders/search with your seller ID and optional date range filters
2. Each order is stored in both the dedicated mercadolibre.order model and as an Odoo sale.order
3. For each order, the buyer is resolved:
   • First lookup by MercadoLibre buyer ID
   • Then by email address
   • If not found, a new res.partner is created with full fiscal data (name, email, phone, document type/number, business name)
4. A sale.order is 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
5. Based on configuration, orders are auto-confirmed, deliveries auto-created, and invoices auto-generated

How Inventory Sync Works

Pull (MELI to Odoo):

1. The module fetches all active items with quantities
2. For each item, it finds the matching Odoo product
3. Compares MELI available_quantity with Odoo's on-hand stock
4. Creates stock.quant adjustments for any differences

Push (Odoo to MELI):

1. Stock levels are summed across configured warehouses (multi-warehouse support)
2. Stock is pushed to MELI via PUT /items/{id} with the available_quantity field
3. Auto-push triggers on every stock.move validation
4. 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:

1. The module fetches recent orders (up to 500)
2. Unique buyers are extracted by their MercadoLibre user ID
3. Each buyer is created/updated as a res.partner with full data: name, email, nickname, phone, document type, document number, business name (razon social), tax status
4. 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

note

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:

1. In your MercadoLibre Developer Portal, go to your app's Webhooks section
2. Add a callback URL: https://your-odoo-domain.com/meli_notify
3. 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

4. The module's /meli_notify endpoint receives notifications, queues them in the notification model, and processes them via a 5-minute cron job
5. Failed notifications are retried up to 3 times

tip

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	Description
Import Wizard	Operations > Import Wizard	Import products, orders, or customers with filters and preview
Import Preview Wizard	(via Import Wizard)	Preview imported data before committing
Export Wizard	Operations > Export Wizard	Export/publish products to MercadoLibre
Batch Publish Wizard	(via product list action)	Mass-publish multiple products at once
Batch Update Wizard	(via product list action)	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	Apply percentage, fixed, or cost+markup price adjustments with rounding options (.99, .90, integer)
Category Import Wizard	Configuration > Category Import	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	Check product matching: the module matches by MELI Item ID first, then SKU, then exact name. Use SKU Rules for custom mapping
Orders not importing	Verify your seller ID matches the authenticated user; check the date range filters in configuration
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; 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 the Notifications queue for failed entries
Duplicate customers	Adjust the fuzzy matching threshold 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

---

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 date range filters (Import Orders From / Import Orders Until) in the configuration or the Import Wizard to import past orders.

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: 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

---

Support

• General Troubleshooting
• MercadoLibre Integration Setup Guide
• Email: [email protected]
• Support Portal