Mercadolibre Getting Started: Integrate APIs (2026)

Getting started overview

Integrating with Mercadolibre's APIs requires developers to follow a structured process that includes account creation, application registration, and credential management. This enables programmatic access to various services, including marketplace listings, payment processing via Mercado Pago, and logistics solutions through Mercado Envíos. The developer portal provides resources, including SDKs for popular programming languages and a sandbox environment for testing integrations prior to deployment Mercadolibre's developer documentation.

The core steps to get started are:

1. Sign up for a Mercadolibre account.
2. Create a developer account and register an application to obtain client credentials.
3. Implement the OAuth 2.0 flow to authorize access tokens.
4. Make your first authenticated API request.

This guide focuses on these initial steps to establish a functional API integration.

Quick reference table

Create an account and get keys

To begin, you need a Mercadolibre user account. If you do not have one, register on the Mercadolibre homepage. Once you have a user account, proceed to the Mercadolibre Developer site to sign up for the developer program. This step is crucial for gaining access to the developer tools and documentation necessary for API integration Mercadolibre developer portal.

Register your application

After creating or logging into your developer account, you must register an application. This process involves providing details about your integration, such as its name, description, and the redirect URI. The redirect URI is where Mercadolibre will send the user back after they authorize your application, along with an authorization code. Upon successful registration, you will receive a unique client_id and client_secret. These credentials are vital for the OAuth 2.0 authentication flow and should be kept confidential application creation guide.

Implementing OAuth 2.0

Mercadolibre uses OAuth 2.0 for authentication and authorization. This protocol allows your application to access a user's Mercadolibre data without requiring their direct credentials. The general flow is as follows:

1. Request User Authorization: Redirect the user to Mercadolibre's authorization URL. This URL includes your client_id, the desired scope of permissions (e.g., read user data, create listings), and your registered redirect_uri. The user will be prompted to grant your application access.
2. Receive Authorization Code: If the user grants permission, Mercadolibre redirects them back to your redirect_uri with an authorization code appended as a query parameter.
3. Exchange Code for Access Token: Your application then makes a server-side POST request to Mercadolibre's token endpoint. This request includes the authorization code, your client_id, and client_secret. In return, Mercadolibre provides an access_token and a refresh_token. The access_token is a temporary credential used to authenticate subsequent API requests, while the refresh_token can be used to obtain new access tokens once the current one expires Mercadolibre authentication guide.

For security, always handle your client_secret and refresh_token on your backend server and never expose them in client-side code.

Your first request

Once you have obtained an access_token, you can make your first authenticated request to the Mercadolibre API. A common initial request is to retrieve information about the authenticated user.

Example: Retrieving User Data with Python SDK

Mercadolibre provides official SDKs for several languages, including Python. Using an SDK simplifies interaction with the API by handling HTTP requests, JSON parsing, and authentication details.

import mercadolibre

# Replace with your actual client_id, client_secret, and access_token
CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'

# Initialize the Mercadolibre API client
meli = mercadolibre.Api(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

# Set the access token for authenticated requests
meli.access_token = ACCESS_TOKEN

try:
    # Make a GET request to the /users/me endpoint (current user's data)
    user_data = meli.get('/users/me')

    # Print the user data
    print("Successfully retrieved user data:")
    print(user_data)

except mercadolibre.exceptions.MercadolibreException as e:
    print(f"Error retrieving user data: {e.message}")

In this Python example:

1. The mercadolibre SDK is imported.
2. Placeholder variables for CLIENT_ID, CLIENT_SECRET, and ACCESS_TOKEN are defined. You must replace these with your actual credentials.
3. An instance of the Mercadolibre API client is created.
4. The obtained ACCESS_TOKEN is assigned to the client for authentication.
5. A GET request is made to the /users/me endpoint, which returns information about the user associated with the ACCESS_TOKEN.
6. The retrieved JSON data is printed to the console.

Example: Retrieving User Data via cURL (without SDK)

If you prefer to make raw HTTP requests, you can use curl or any HTTP client library.

curl -X GET \
  'https://api.mercadolibre.com/users/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Replace YOUR_ACCESS_TOKEN with the actual access token you obtained through the OAuth 2.0 flow. This command sends a GET request to the user endpoint, including the access token in the Authorization header, which is standard practice for Bearer Token authentication.

Common next steps

After successfully making your first API call, consider these common next steps for further integration:

• Explore Marketplaces: Integrate with the Mercadolibre Marketplace API to manage listings, orders, and products. This includes searching for items, creating new items, or updating existing ones Mercadolibre Marketplace API reference.
• Implement Mercado Pago: If your application involves payments, integrate with Mercado Pago to process transactions, manage refunds, and handle payment notifications. This requires specific permissions and a separate set of API calls Mercado Pago API documentation.
• Utilize Webhooks: Set up webhooks to receive real-time notifications about events in your Mercadolibre account, such as new orders, payment updates, or listing changes. This reduces the need for constant polling and ensures your application stays synchronized with Mercadolibre's data Mercadolibre webhooks guide.
• Error Handling and Logging: Implement robust error handling and logging mechanisms to diagnose issues and ensure the stability of your integration. Review Mercadolibre's specific error codes and responses.
• Sandbox Testing: Thoroughly test all aspects of your integration in the Mercadolibre sandbox environment before deploying to production. This helps identify and resolve potential issues without impacting live operations Mercadolibre sandbox information.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Invalid access_token: Ensure your access_token is current and correctly included in the Authorization: Bearer header. Access tokens have an expiration time (typically a few hours), after which you need to use the refresh_token to obtain a new one.
• Incorrect Permissions (Scopes): Verify that your application has been granted the necessary permissions (scopes) during the OAuth authorization process for the endpoint you are trying to access. An attempt to access a resource without proper scope will result in an authorization error.
• Rate Limiting: Mercadolibre APIs implement rate limits to prevent abuse. If you make too many requests in a short period, your requests might be temporarily blocked. Check the response headers for rate limit information (e.g., X-ML-RateLimit-Limit, X-ML-RateLimit-Remaining, X-ML-RateLimit-Reset) and implement appropriate retry logic with exponential backoff if necessary Mercadolibre rate limit documentation.
• Client ID/Secret Mismatch: Double-check that the client_id and client_secret used during the OAuth token exchange are exactly those provided when you registered your application.
• Redirect URI Mismatch: Ensure the redirect_uri used in your authorization request precisely matches the one registered for your application on the Mercadolibre developer dashboard. Even a slight discrepancy can cause authorization failures.
• Network Issues: Confirm that your application can reach api.mercadolibre.com. Firewall rules or proxy settings might interfere with your connection.
• Review Error Messages: Mercadolibre API responses typically include detailed error messages and codes within the JSON body. Always parse these messages for specific guidance on what went wrong. For example, a 401 Unauthorized might indicate an invalid token, while a 403 Forbidden could point to insufficient permissions Mercadolibre error codes documentation.