.png)
Mercado Libre Integration Guide
Connect Mercado Libre seller and buyer resources with enterprise applications through OAuth 2.0-secured REST APIs and selected notification callbacks.
Mercado Libre integration options at a glance
Mercado Libre primarily integrates through REST APIs for Users, Items, Orders, Payments, Shipments, Questions, Categories, Searches, and related resources. OAuth 2.0 authorizes access to private seller and buyer data, while selected resource topics can generate notification callbacks. Martini can consume the REST APIs, expose an API to receive notifications, retrieve the current resource after a callback, and map Mercado Libre JSON into downstream systems. Pagination, checkpoints, controlled concurrency, and scheduled reconciliation support reliable synchronization. Picture and item-media operations are available for listings, but a universal attachment API and general-purpose asynchronous bulk API were not confirmed.
| Integration point | Supported by Mercado Libre? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Mercado Libre’s primary mechanism for Users, Items, Orders, Payments, Shipments, Questions, Claims, Categories, searches, and related resources. | Martini can consume REST endpoints from workflows, handle JSON responses, transform fields, apply business rules, and expose normalized APIs to downstream systems. |
| Webhooks / outbound callbacks | Limited | Notification callbacks signal changes for selected topics such as Items, Orders, Questions, Payments, Shipments, Claims, and Messages. | Martini can expose an API to receive callbacks, validate and record notifications, retrieve the current resource, and process the result idempotently. |
| OAuth 2.0 authentication | Yes | OAuth 2.0 authorizes applications to access private seller, buyer, order, payment, shipment, and other user-scoped resources. | Martini can store client credentials and refresh tokens securely, obtain or refresh bearer tokens, and apply authorization to API requests. |
| Bulk / batch access | Limited | Some multi-resource and query-oriented REST operations can support more efficient retrieval, but a universal asynchronous bulk API was not confirmed. | Martini can use supported multi-resource operations with pagination, checkpointing, throttling, and controlled concurrency rather than assuming universal bulk processing. |
| File / media APIs | Limited | Picture and item-media operations support product listing content; a general-purpose attachment API for all business objects was not confirmed. | Martini can retrieve or send supported media resource data through REST workflows and associate it with Item processing. |
| Scheduled synchronization | Yes | Scheduled pagination and reconciliation can recover missed notifications, synchronize Items and inventory, and compare current Orders, Payments, or Shipments. | Martini can schedule workflows, maintain timestamps or cursors, checkpoint progress, and resume after failures. |
| GraphQL APIs | Not confirmed | No official Mercado Libre GraphQL API was confirmed in the reviewed documentation. | Martini should use the confirmed Mercado Libre REST APIs instead of assuming GraphQL availability. |
| SOAP APIs | No | Mercado Libre integrations are documented around REST APIs and notification mechanisms rather than SOAP. | Martini can consume SOAP generally, but a Mercado Libre SOAP integration should not be planned without separate vendor confirmation. |
How Mercado Libre exposes data and business events
Mercado Libre REST APIs
Mercado Libre’s REST API is the primary integration mechanism for Users, Items, Orders, Payments, Shipments, Questions, Claims, Categories, searches, and related resources. Private resources require OAuth 2.0 authorization, while some public operations may be available without user authorization.
Martini implementation pattern
Martini implementation pattern: a workflow obtains or refreshes an OAuth access token, calls the required Mercado Libre endpoint, handles pagination and JSON responses, maps the result to a canonical or target model, applies business rules, and records correlation and checkpoint information.
Implementation sequence
Mercado Libre notification callbacks
Mercado Libre supports notification callbacks for selected resource topics, including possible notifications for Items, Orders, Questions, Payments, Shipments, Claims, and Messages. Coverage is selective and topic-dependent; notifications generally identify a changed resource rather than providing a complete business payload.
Martini implementation pattern
Martini implementation pattern: expose a Martini API for the callback, validate and record the notification, use its resource type and identifier to retrieve current state through the REST API, then process the resource idempotently. The callback can be acknowledged quickly and handed to asynchronous workflow processing where appropriate.
Implementation sequence
Scheduled reconciliation
Scheduled synchronization complements notifications by retrieving paginated collections, checking timestamps or status fields, and recovering from missed callbacks or failed processing. This is important because notification coverage is not universal and a notification may not contain the complete resource.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow loads the last successful checkpoint, requests the next page or changed-resource set, processes each resource with controlled concurrency, persists progress, and resumes from the checkpoint after an interruption.
Implementation sequence
Common Mercado Libre integration patterns
Pattern 1: Synchronize orders to ERP and fulfillment
When to use this pattern
Use this pattern when Mercado Libre orders must become sales, payment, and fulfillment transactions in an ERP or warehouse platform. Notification callbacks provide near-real-time triggers for supported topics, while scheduled reconciliation detects missed notifications and incomplete processing.
Integration direction
Example Mapping
| Mercado Libre Field | Canonical Field | Target Field |
|---|---|---|
| id | externalOrderId | externalId |
| date_created | orderCreatedAt | transactionDate |
| order_items | lineItems | itemLines |
| total_amount | orderTotal | totalAmount |
Martini implementation pattern
Martini receives or discovers an Order, retrieves related Order Items, Buyer, Payment, and Shipment data, and maps them into the ERP model. The workflow checks the Mercado Libre order ID before creating a transaction, applies currency and status rules, and separates validation failures from transient API or target-system failures. Retries use bounded backoff and correlation IDs.
Martini capabilities used
- workflows
- API consumption
- OAuth 2.0 configuration
- data mapping
- business rules
- idempotency
- error handling
Pattern 2: Synchronize catalog and inventory
When to use this pattern
Use this pattern when an ERP, commerce platform, or product system is the source of truth for product quantity, price, and listing information and Mercado Libre must reflect approved changes.
Integration direction
Example Mapping
| Mercado Libre Field | Canonical Field | Target Field |
|---|---|---|
| id | listingId | itemId |
| price | salePrice | price |
| available_quantity | availableQuantity | availableQuantity |
| pictures | productImages | pictures |
Martini implementation pattern
A scheduled or source-system-triggered workflow reads product changes, normalizes SKU and variation structures, applies site-specific pricing and inventory rules, and calls the relevant Item REST operations. Martini records the Mercado Libre item ID and result, preserves variation and picture relationships, and retries rate-limit responses without duplicating updates.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- JSON handling
- business rules
- controlled retries
Pattern 3: Normalize payment and shipment status
When to use this pattern
Use this pattern when finance, customer service, or fulfillment applications need a consistent status view across Mercado Libre and other sales channels.
Integration direction
Example Mapping
| Mercado Libre Field | Canonical Field | Target Field |
|---|---|---|
| status | paymentStatus | Payment_Status__c |
| transaction_amount | paidAmount | Paid_Amount__c |
| shipping.status | shipmentStatus | Shipment_Status__c |
| id | externalReference | Mercado_Libre_Reference__c |
Martini implementation pattern
Martini receives supported payment or shipment notifications or retrieves changes during reconciliation, then fetches the current Payment or Shipment representation. It maps vendor status values to a canonical status while retaining the original value, updates the target by external reference, and routes permission or validation errors separately from temporary failures.
Martini capabilities used
- API consumption
- workflow orchestration
- data mapping
- status normalization
- business rules
- error handling
Pattern 4: Route buyer questions to customer service
When to use this pattern
Use this pattern when sellers need questions and related item context in a customer-service application, with approved responses optionally returned to Mercado Libre.
Integration direction
Example Mapping
| Mercado Libre Field | Canonical Field | Target Field |
|---|---|---|
| text | customerQuestion | description |
| item_id | listingId | customItemId |
| from.id | buyerId | requesterExternalId |
| id | questionId | externalTicketId |
Martini implementation pattern
A Martini API receives a supported Questions notification or a scheduled workflow retrieves new questions. Martini fetches the current question and item context, creates or updates a Zendesk ticket using the question ID as the idempotency key, and applies approval rules before sending any response through the relevant Mercado Libre API. Audit fields preserve seller, item, and response status.
Martini capabilities used
- API exposure
- workflow orchestration
- data enrichment
- mapping
- business rules
- audit logging
- idempotency
Applications commonly integrated with Mercado Libre
Mercado Libre can be integrated with commerce, ERP, customer-service, and fulfillment applications using its REST resources and selected notification topics. The following are practical enterprise architecture targets rather than claims of dedicated native pairings.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Mercado Libre buyers, orders, questions, claims, and shipment updates with sales and customer-service processes. | Mercado Libre → Martini → Salesforce | Receive supported notifications or run scheduled REST synchronizations, retrieve the current Mercado Libre resource, map it to Salesforce objects, apply duplicate and ownership rules, and retry transient API or Salesforce failures. |
| Shopify | Coordinate catalog, inventory, pricing, and orders between a direct-to-consumer store and Mercado Libre. | Shopify → Martini → Mercado Libre | Use Shopify events or schedules as triggers, normalize product and inventory data, apply site and seller rules, update Mercado Libre Items through REST APIs, and checkpoint results for safe replay. |
| NetSuite | Post Mercado Libre orders, payment information, and fulfillment status into ERP processes while synchronizing inventory and listing updates. | Mercado Libre → Martini → NetSuite | Retrieve Orders, Payments, and Shipments after notifications or during reconciliation, transform them into NetSuite sales and fulfillment structures, preserve external IDs, and route validation failures for review. |
| SAP S/4HANA | Connect marketplace sales, inventory, delivery, and finance processes with enterprise ERP operations. | SAP S/4HANA → Martini → Mercado Libre | Orchestrate bidirectional API workflows, map SAP product and inventory models to Mercado Libre Items, enforce regional and currency rules, and use retries and correlation IDs across both systems. |
| VTEX | Synchronize catalog, inventory, orders, and fulfillment between Mercado Libre and a commerce platform. | VTEX → Martini → Mercado Libre | Use scheduled or event-driven workflows to normalize catalog and order payloads, update the appropriate Mercado Libre resources, and prevent duplicate updates with item and order keys. |
| BigCommerce | Consolidate product, inventory, pricing, and order data across ecommerce channels. | BigCommerce → Martini → Mercado Libre | Use a canonical product and order model in Martini, transform channel-specific fields, apply quantity and listing-status rules, and retry rate-limited or temporarily unavailable requests. |
| Zendesk | Create or update support tickets from Mercado Libre Questions, Claims, order issues, and shipment problems. | Mercado Libre → Martini → Zendesk | Retrieve the complete question or issue resource, enrich it with item and order context, create or update a Zendesk ticket using the Mercado Libre ID as a correlation key, and optionally send approved responses back through the relevant API. |
| Microsoft Dynamics 365 | Synchronize marketplace orders, customers, products, inventory, and fulfillment with CRM and ERP processes. | Mercado Libre → Martini → Microsoft Dynamics 365 | Combine Mercado Libre notifications with scheduled reconciliation, map resource and status values to Dynamics entities, retain original vendor statuses, and handle permission, validation, and throttling errors separately. |
How to build a Mercado Libre integration in Martini
Objective
Establish OAuth 2.0 access to the appropriate Mercado Libre user and configure target-system credentials without embedding secrets in workflow definitions.
Instructions in Martini
- Configure the Mercado Libre client ID, client secret, redirect URI, access token, and refresh token through protected configuration.
- Define environment-specific target-system credentials and permissions.
- Implement token refresh handling before private API calls.
Objective
Select the event or schedule that matches the required freshness and the resource topics available to the Mercado Libre application.
Instructions in Martini
- Use a Martini API or webhook workflow for supported Mercado Libre notification callbacks.
- Use a scheduler for catalog synchronization, reconciliation, and resources without notification coverage.
- Combine notifications with scheduled recovery where missed callbacks would affect business operations.
Objective
Treat notifications as change signals and retrieve the current Mercado Libre representation before applying business logic.
Instructions in Martini
- Validate and record callback resource type and identifier.
- Call the relevant REST endpoint for Orders, Items, Payments, Shipments, Questions, or another supported resource.
- Handle pagination, timestamps, cursors, and site or seller context explicitly.
Objective
Coordinate retrieval, enrichment, transformation, target writes, checkpoints, and operational decisions in a maintainable Martini workflow.
Instructions in Martini
- Load related resources such as Order Items, Buyer, Payment, and Shipment when required.
- Use correlation IDs and external resource identifiers throughout the workflow.
- Persist checkpoints and processing state at appropriate transaction boundaries.
Objective
Convert Mercado Libre JSON and status values into the canonical or target-system model without losing marketplace-specific information.
Instructions in Martini
- Map vendor fields to canonical fields and preserve original IDs and status values.
- Handle item variations, pictures, currencies, locales, and regional context.
- Apply explicit transformations for amounts, dates, quantities, and nested collections.
Objective
Control duplicate processing, permissions, marketplace differences, and downstream actions before writing data.
Instructions in Martini
- Check notification or resource-processing keys before creating downstream transactions.
- Apply seller, site, inventory, pricing, approval, and status rules.
- Distinguish permanent validation or authorization failures from transient failures.
Common Mercado Libre data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Users | Identify buyer and seller accounts, authenticated application users, and marketplace context. | Salesforce, NetSuite, Microsoft Dynamics 365, customer-service platforms | Martini retrieves authorized user data, maps site and seller identifiers, and protects personal data and tokens from logs. |
| Items | Represent product listings, prices, quantities, listing status, variations, attributes, and pictures. | Shopify, VTEX, BigCommerce, SAP S/4HANA, NetSuite | Martini maps item and variation structures, preserves item IDs, applies inventory and pricing rules, and processes supported picture resources. |
| Orders | Represent purchases, order lines, buyers, totals, and order status. | NetSuite, SAP S/4HANA, Salesforce, Microsoft Dynamics 365, fulfillment platforms | Martini retrieves the current Order after notification, enriches it with Order Items, Buyer, Payment, and Shipment data, and uses the order ID for idempotency. |
| Payments | Track payment transactions, amounts, payment status, and transaction context associated with orders. | NetSuite, SAP S/4HANA, finance platforms, Salesforce | Martini maps payment status and amounts explicitly, supports reconciliation, and separates transient API failures from authorization or validation errors. |
| Shipments | Track delivery information, logistics status, and shipment references. | NetSuite, SAP S/4HANA, warehouse and fulfillment applications, Salesforce | Martini retrieves shipment state, maps vendor statuses to a canonical model, retains the original value, and triggers downstream fulfillment updates. |
| Questions | Manage buyer questions about Items and seller responses. | Zendesk, Salesforce, customer-service applications | Martini routes questions with item and seller context, stores question IDs and response status, and sends approved responses through relevant REST endpoints where permitted. |
Authentication and security considerations
OAuth 2.0 and token lifecycle
Mercado Libre uses OAuth 2.0 for applications accessing authorized seller, buyer, order, payment, shipment, and other private resources. Martini workflows should refresh expired access tokens and keep client secrets, access tokens, and refresh tokens outside workflow definitions.
Secrets and access control
- Store credentials and environment-specific configuration in protected secrets or configuration.
- Grant only the Mercado Libre permissions required by the integration.
- Do not place tokens, client secrets, buyer personal data, or payment-sensitive information in logs or payloads.
- Validate notification requests and restrict exposed callback APIs according to the deployment security model.
Operational considerations for Mercado Libre integrations
Throttling and pagination
Mercado Libre applies API usage limits. Use bounded retries with exponential backoff, concurrency controls, and monitoring for HTTP 429 responses. Collection and search endpoints should be processed page by page with durable checkpoints.
Notifications and idempotency
Notifications are selective and may be retried or delivered more than once. Treat them as signals to retrieve current state, store a resource-processing key, and avoid creating duplicate orders or tickets.
Marketplace context and schemas
Store site, seller, item, order, currency, locale, and regional tax context. Explicitly map status values and retain the original Mercado Libre value because fields and statuses can vary by resource or marketplace site.
Testing and monitoring
Test OAuth renewal, callback handling, pagination, variations, picture resources, validation failures, permission errors, rate limits, downstream outages, and replay scenarios. Monitor correlation IDs, resource IDs, retry counts, checkpoints, and target references.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a managed workflow structure for combining Mercado Libre callbacks, REST retrieval, related-resource enrichment, transformations, target writes, checkpoints, and error handling. This avoids duplicating token, pagination, retry, and idempotency logic across separate scripts.
Reusable integration assets
Teams can expose normalized APIs, reuse mappings and workflow services, and apply consistent business rules across Mercado Libre, ERP, commerce, finance, and customer-service applications.
Operational control
- Centralize secure configuration and OAuth token handling.
- Implement bounded retries and route permanent failures for review.
- Preserve vendor identifiers and correlation data for reconciliation.
- Support event-driven processing together with scheduled recovery workflows.
Frequently asked questions
Mercado Libre can be integrated primarily through its OAuth 2.0-secured REST APIs for Users, Items, Orders, Payments, Shipments, Questions, and related resources. Selected notification callbacks can signal resource changes, after which the receiving system retrieves the current resource through the REST API. Scheduled pagination and reconciliation can supplement notifications.
Yes. Martini can consume Mercado Libre REST APIs, manage OAuth 2.0 authentication, expose an API to receive selected Mercado Libre notification callbacks, orchestrate retrieval and downstream updates, and map Mercado Libre JSON into enterprise applications.
No. A dedicated Mercado Libre connector is not required. Martini can integrate using Mercado Libre’s confirmed native REST APIs, OAuth 2.0 authentication, notification callbacks, JSON resources, and supported picture or item-media operations.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Mercado Libre. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Mercado Libre, cloud infrastructure, or other third-party systems based on subscription, API usage, and deployment model.
New integrations should use Mercado Libre REST APIs with OAuth 2.0 for private resources. Use notification callbacks for supported topics and scheduled, paginated reconciliation for recovery or resources without suitable notifications. No official GraphQL or SOAP mechanism was confirmed.
Martini can receive Mercado Libre notification callbacks through an exposed API or webhook workflow. Coverage is selective and topic-dependent, so the implementation must confirm that the required resource topic is available. The callback should generally trigger retrieval of the current resource rather than be treated as a complete payload.
A robust design combines notification processing with scheduled reconciliation. Martini stores notification or resource-processing keys, such as resource type and ID, to prevent duplicate downstream transactions. Checkpoints, pagination, timestamps, and bounded retries help recover from missed callbacks and interrupted workflows.
Yes. Martini can expose controlled REST APIs that normalize Mercado Libre resources for internal applications, hide OAuth and vendor-specific details, apply business rules, and orchestrate calls to Mercado Libre. The façade can also provide a controlled receiving endpoint for selected notification callbacks.
Related Martini documentation
Martini APIs
Data and security
Integrate Mercado Libre with Martini
Use Martini to connect Mercado Libre REST APIs and selected notification callbacks with the enterprise systems that manage orders, products, payments, fulfillment, and customer service.