MercadoLibre Integration Setup

Connect your MercadoLibre seller account with Odoo to sync products, orders, customers, inventory, shipments, questions, and claims across Latin American markets.

Prerequisites

• Odoo 17, 18, or 19 (Community or Enterprise)
• A MercadoLibre seller account (any supported country)
• An active ECOSIRE license for the MercadoLibre Store Management module

Step 1: Install the Module

1. Download from your ECOSIRE Dashboard
2. Extract and install:

   unzip ecosire-mercadolibre-store-management-*.zip -d /opt/odoo/addons/
   sudo systemctl restart odoo

3. Update Apps List and install "Mercado Libre Store Management"
4. Activate your ECOSIRE license at Settings > ECOSIRE > License Activation

Step 2: Create a MercadoLibre Developer App

1. Go to developers.mercadolibre.com
2. Sign in with your MercadoLibre seller account
3. Click Create Application (or "Crear aplicacion")
4. Fill in the form:
   • App Name: Odoo Integration
   • Description: ERP integration for orders and inventory
   • Redirect URI: https://your-odoo-domain.com/meli_login
   • Scopes: read, write, offline_access
5. Save your Client ID and Client Secret

Redirect URI

The Redirect URI must point to your Odoo instance's /meli_login path. This is the OAuth callback endpoint that the module uses to receive authorization codes. Make sure your Odoo domain is publicly accessible over HTTPS.

Step 3: Authorize Your App (OAuth Login)

The module includes a built-in OAuth flow that handles token exchange automatically.

Option A: One-Click OAuth Login (Recommended)

1. Open the MercadoLibre app from the Odoo home menu
2. Go to Configuration > Settings and click New
3. Enter your Client ID and Client Secret
4. Select your Site / Country (e.g., Argentina MLA)
5. Click Login with MercadoLibre
6. A browser window opens -- sign in to MercadoLibre and click Allow
7. You are redirected back to Odoo. Tokens are saved automatically and the Seller ID is populated.

tip

The "Login with MercadoLibre" button constructs the correct country-specific auth URL, opens it in a new window, and the /meli_login callback handles the code exchange and token storage. You never need to copy/paste tokens manually.

Option B: Manual Token Flow (Fallback)

If your Odoo instance is not publicly accessible (e.g., localhost, VPN-only), use the manual flow:

3a. Get the Authorization Code

Open this URL in your browser, replacing the placeholders:

https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

note

Use the correct auth domain for your country:

• Argentina: auth.mercadolibre.com.ar
• Brazil: auth.mercadolivre.com.br
• Mexico: auth.mercadolibre.com.mx
• Colombia: auth.mercadolibre.com.co
• Chile: auth.mercadolibre.cl
• Peru: auth.mercadolibre.com.pe

Sign in and click Allow. You'll be redirected to your URI with a code parameter:

https://your-redirect-uri.com?code=TG-XXXXXX-XXXXXXXX

3b. Exchange Code for Tokens

Run this command (or use Postman):

curl -X POST https://api.mercadolibre.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=TG-XXXXXX-XXXXXXXX" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Response:

{
  "access_token": "APP_USR-1234...",
  "expires_in": 21600,
  "refresh_token": "TG-YYYY-...",
  "user_id": 123456789
}

3c. Enter Tokens in Odoo

Go to MercadoLibre > Configuration > Settings, open your configuration, and enter the Access Token and Refresh Token in the credential fields.

info

You only need to do this once. The module automatically refreshes expired tokens every 6 hours.

Step 4: Configure in Odoo

1. Open the MercadoLibre app from the Odoo home menu
2. Go to Configuration > Settings
3. Open your configuration (created in Step 3) and verify:

Field	What to Enter
Name	A friendly name (e.g., "ML Argentina")
Client ID	Your App ID from Step 2
Client Secret	Your App Secret from Step 2
Site / Country	Select your marketplace (e.g., Argentina MLA)
Redirect URI	https://your-odoo-domain.com/meli_login

4. Click Test Connection -- you should see "Connection successful!"
5. In the Synchronization tab, enable the data types you want to sync
6. Click Save

Step 5: Configure Commerce Settings

Set up pricing, warehousing, and tax handling for your MELI integration:

Field	Description	Recommended
Pricelist	Odoo pricelist for MELI price exports. Leave empty to use product list price.	Set if you have MELI-specific pricing
Warehouse	Default warehouse for stock sync	Your primary warehouse
Warehouses (Multi-Location)	Select multiple warehouses to sum stock from	Use if stock is spread across locations
MELI Currency	Currency on MercadoLibre. Auto-converts from Odoo company currency.	Set if your Odoo company currency differs from MELI
Tax Handling	How to handle taxes when pushing prices	auto for most cases; tax_included for Argentina/Brazil
Generic VAT Numbers	Non-fiscal VATs to ignore (comma-separated)	XAXX010101000,XEXX010101000 for Mexico

Tax Handling Modes

• Auto: Uses product tax configuration to calculate MELI prices
• Tax Included: Odoo prices already include tax, send as-is to MELI
• Tax Excluded: Odoo prices exclude tax, module adds tax before sending to MELI
• No Tax: Send Odoo prices directly without any tax adjustment

Step 6: Configure Order Processing

Control how imported MELI orders are handled in Odoo:

Setting	Options	When to Use
Order Confirmation	Manual / Auto on Payment / Always	Use "Auto on Payment" for hands-off order processing
Delivery Processing	Manual / Auto on Shipped / Always	Use "Auto on Shipped" to create deliveries when MELI marks orders shipped
Auto Create Invoice	On / Off	Enable if you want invoices created automatically on confirmation
Fulfillment Warehouse	Select a warehouse	Set this if you use MercadoLibre Fulfillment (Full) -- orders route to this warehouse
Sales Team	Select a CRM team	Assigns all MELI orders to this team for reporting
Salesperson	Select a user	Assigns all MELI orders to this salesperson
Import Orders From	Date	Only import orders after this date (useful for initial setup to avoid importing old orders)
Import Orders Until	Date	Only import orders before this date (useful for migration windows)

Initial Order Import

When first connecting, leave "Import Orders From" empty or set it to a recent date (e.g., 30 days ago). Importing years of historical orders can take a long time and create thousands of sale orders in Odoo.

Step 7: Configure Accounting

Set up journal mapping for automated financial tracking:

Field	Type	Description
MercadoLibre Sales Journal	Sale journal	Used for invoices created from MELI orders
MercadoPago Payment Journal	Bank or cash journal	Used to register payments received via MercadoPago
MELI Fee Expense Account	Expense account	Tracks MercadoLibre commission and marketplace fees
Shipping Expense Account	Expense account	Tracks shipping costs
Auto Register Payment	Toggle	When enabled, automatically registers payment against the invoice when it is confirmed

note

If you leave the accounting fields empty, the module still imports orders and creates sale orders -- but you will need to handle invoicing and payment registration manually.

Step 8: Set Up Webhooks

For real-time order and product updates instead of relying on polling crons:

1. In the MercadoLibre Developer Portal, open your app
2. Go to the Webhooks (or "Notificaciones") section
3. Set the Callback URL to: https://your-odoo-domain.com/meli_notify
4. Subscribe to these topics:

Topic	What It Triggers
orders_v2	New orders and order status changes (payment, cancellation)
items	Product listing updates (price, stock, status)
questions	New buyer questions on your listings
payments	Payment status changes from MercadoPago
shipments	Shipping status updates (shipped, delivered, returned)
claims	Dispute and claim notifications
messages	Buyer messages in the order conversation

5. Save your webhook configuration in the Developer Portal

The module's /meli_notify endpoint receives incoming notifications and queues them for processing. A cron job processes the queue every 5 minutes. Failed notifications are retried up to 3 times.

tip

You can monitor the notification queue at MercadoLibre > Operations > Notifications. Each notification shows its state (received, processing, success, failed), topic, resource URL, and retry count.

Step 9: Run Your First Sync

From the configuration form:

1. Click Sync Products to import your MercadoLibre listings into Odoo
2. Click Sync Orders to import recent orders (buyers are auto-created as customers)
3. Go to Dashboard to see your data

The module will now automatically sync based on your configured cron frequencies.

Step 10: Verify Everything Works

Check each section:

Section	What to Verify
Dashboard	KPIs show your product count, order count, revenue
MELI Orders	MELI orders appear with items, payments, and buyer info
Orders	Recent ML orders appear as Odoo sale orders
Products	Your ML listings appear with prices and stock levels
Customers	Buyers from orders appear as contacts with fiscal data
Shipments	Shipment records created for shipped orders
Operations > Logs	Sync logs show "success" status

What's Next?

• Enable push crons -- Activate real-time stock push (5 min), auto push products (30 min), and auto push prices (2 hr) in Scheduled Actions when ready for bidirectional sync
• Set up SKU rules -- Configure SKU mapping rules at Configuration > SKU Rules for exact, prefix, suffix, regex, or formula matching
• Import categories -- Use Configuration > Category Import Wizard to import the MELI category tree for better product categorization
• Create description templates -- Set up header/footer HTML banners at Configuration > Description Templates for branded product descriptions
• Configure size charts -- Import size guide charts for apparel/shoes at Configuration > Size Charts
• Use margin analysis -- Monitor profitability at Operations > Margin Analysis with per-product breakdown of price, cost, fees, and shipping

Common Issues

Problem	Solution
"Connection failed"	Double-check Client ID and Secret; make sure the app is approved
"Token expired"	Click "Login with MercadoLibre" to re-authorize, or re-do the manual token flow if OAuth redirect is not available
No products syncing	Click "Sync Products" manually first; check sync logs for errors
No orders appearing	Verify your seller ID matches; check date range filters; ensure you have recent orders
License error	Go to Settings > ECOSIRE > License Activation and enter your key
Webhook notifications not arriving	Verify the /meli_notify URL is publicly accessible over HTTPS; check the Developer Portal webhook status
OAuth login opens but does not redirect back	Ensure the Redirect URI in your Developer Portal matches exactly: https://your-odoo-domain.com/meli_login
Duplicate customers created	Check the generic VAT configuration; merge duplicates via Odoo's partner merge wizard
Stock not pushing to MELI	Enable the real-time stock push cron; verify warehouse selection in configuration

Need Help?

• Full documentation: MercadoLibre Module Docs
• Email: [email protected]
• Support Portal