Connect your Mercado Libre seller account to EcomCentral using OAuth 2.0 Bearer token authentication.
Mercado Libre (MELI) is Latin America's largest e-commerce marketplace, operating in 18 countries including Argentina, Brazil, Mexico, Colombia, Chile, and Peru. This integration targets the standard Marketplace API using OAuth 2.0 Bearer tokens, giving EcomCentral access to orders, items, stock management, and shipment tracking for ME1 (self-managed) logistics.
https://api.mercadolibre.com and
authenticates every request with Authorization: Bearer {access_token}.
Access tokens expire — implement the refresh token flow before deploying to production.
GET /users/me)https://auth.mercadolibre.com/authorization?response_type=code&client_id={APP_ID}&redirect_uri={REDIRECT_URI}.
Exchange the returned code for an access_token and refresh_token
via POST https://api.mercadolibre.com/oauth/token.
GET https://api.mercadolibre.com/users/me
with the Bearer token. The response contains id — that is your numeric seller_id.
access_token and seller_id, then click ⚡ Test.
refresh_token and implement the refresh flow
(POST /oauth/token with grant_type=refresh_token) to obtain a new
access token automatically before expiry.
| Key | Required | Description | Example |
|---|---|---|---|
access_token |
Required | OAuth 2.0 Bearer token obtained via the authorization code flow. Expires — refresh regularly. | APP_USR-12345… |
seller_id |
Required | Numeric MELI user / seller ID. Retrieved from GET /users/me → id field. |
123456789 |
token for the access token;
sellerId (camelCase) for the seller ID.
| Operation | Method | Endpoint |
|---|---|---|
| Test connection / get seller info | GET | /users/me |
| List orders | GET | /orders/search?seller={id}&sort=date_desc&offset=N&limit=N |
| Order detail | GET | /orders/{id} |
| List item IDs | GET | /users/{id}/items/search?offset=N&limit=N |
| Item detail | GET | /items/{id} |
| Update stock | PUT | /items/{id} with { "available_quantity": N } |
| Add shipment tracking | POST | /shipments/{shipment_id}/tracking with { "tracking_number":"…", "carrier":"…", "tracking_url":"…" } |
/users/{id}/items/search and hydrates each item individually with /items/{id}.
This is the standard pattern documented by MELI for seller catalog access.
MELI order statuses are lowercase English strings. EcomCentral colour-codes them as follows:
| Status | Badge colour | Meaning |
|---|---|---|
| paid | Green | Payment confirmed; ready to fulfil |
| shipped / delivered / closed | Green | Order is shipped, delivered, or fully completed |
| payment_required | Blue | Awaiting buyer payment |
| payment_in_process | Blue | Payment is being processed |
| confirmed / in_process | Blue | Order confirmed or being processed |
| mediation | Amber | Dispute or mediation open |
| cancelled | Red | Order was cancelled |
| invalid / chargedback / refunded | Red | Order is invalid or a chargeback / refund has been raised |
MELI has two shipping modes and only one accepts seller-supplied tracking numbers:
| Shipping mode | Tracking | Notes |
|---|---|---|
| ME1 / Mercado Envíos Flex (self-managed) | ✅ Seller-supplied | Use POST /shipments/{id}/tracking with tracking_number, carrier, and optionally tracking_url. |
| ME2 / Standard Mercado Envíos (MELI-managed) | ❌ Automatic | MELI handles the entire logistics chain. Seller-supplied tracking is rejected with a 400 error. |
| Feature | Supported | Notes |
|---|---|---|
| View orders (paginated) | ✅ | Order ID, date, status, total + currency. Sorted most-recent-first. |
| View order detail | ✅ | Buyer nickname, status, payment type, shipment ID, line items with SKU and unit price. Buyer address requires a separate /shipments/{id} call (not performed automatically). |
| Add tracking number | ✅ | ME1 (own-logistics) shipments only. EcomCentral resolves the shipment ID from the order automatically. |
| View products (paginated) | ✅ | Item ID, seller SKU (seller_custom_field), title, price, available quantity. Hydrated individually via /items/{id}. |
| View product detail | ✅ | Full item with condition, listing type, thumbnail, permalink, and up to 6 attributes. |
| Update stock quantity | ✅ | By MELI item ID (e.g. MLA1234567) via PUT /items/{id}. Uses item ID, not seller SKU. |
| Test connection | ✅ | Calls GET /users/me — confirms the token is valid and returns seller nickname, site, and country. |
The access token has expired or is invalid. MELI tokens typically expire after 6 hours.
Refresh the token using POST /oauth/token with
grant_type=refresh_token and your stored refresh_token,
then update the connection in EcomCentral with the new access_token.
The application is missing a required OAuth scope. Review the scopes granted during
authorization at the Mercado Libre Developers portal and ensure the following are included:
read, write, offline_access.
The requested item ID does not exist or does not belong to this seller account.
Verify the item ID format (e.g. MLA1234567) and that it is active in the seller's catalog.
Attempting to set tracking on a standard Mercado Envíos (ME2) shipment returns a 400 error. Only ME1 / Mercado Envíos Flex (own-logistics) shipments accept seller-supplied tracking numbers. Check the order's shipment mode in the MELI seller portal before submitting tracking.
curl -H "Authorization: Bearer {token}" https://api.mercadolibre.com/users/me
in a terminal. A 200 response with your seller data confirms the token and
credentials are correct. A 401 means the token is expired or invalid.