Authentication Flow

Authorization URL

Construct the authorization URL to initiate the OAuth process:

https://global-selling.mercadolibre.com/authorization?response_type=code&client_id=APP_ID&redirect_uri=REDIRECT_URI

Replace APP_ID with your application identifier and REDIRECT_URI with your callback endpoint.

Token Acquisition

After receiving the authorization code, exchange it for an access token using a POST request:

curl -X POST \
  -H 'accept: application/json' \
  -H 'content-type: application/x-www-form-urlencoded' \
  'https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=APP_ID&client_secret=CLIENT_SECRET&code=AUTH_CODE&redirect_uri=REDIRECT_URI'

The response includes an access token, refresh token, and metadata:

{
  "access_token": "APP_USR-5387223166827464-090515-8cc4448aac10d5105474e135355a8321-8035443",
  "token_type": "bearer",
  "expires_in": 10800,
  "scope": "offline_access read write",
  "user_id": 8035443,
  "refresh_token": "TG-5b9032b4e4b0714aed1f959f-8035443"
}

Token Refresh

To renew an expired access token, use the refresh token:

curl -X POST \
  'https://api.mercadolibre.com/oauth/token?grant_type=refresh_token&client_id=APP_ID&client_secret=SECRET_KEY&refresh_token=REFRESH_TOKEN'

Order Retrieval

Fetch order details by sending a GET request to the orders endpoint:

curl -H 'Authorization: Bearer ACCESS_TOKEN' \
  -X GET 'https://api.mercadolibre.com/marketplace/orders/ORDER_ID'

The response provides comprehensive order data, including items, payments, and shipping information. Key fields include id, status, order_items, and payments.

Messaging Operations

Sending Messages

Send a message to a buyer associated with an order using a POST request:

curl -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'content-type: application/json' \
  -X POST 'https://api.mercadolibre.com/marketplace/messages/packs/ORDER_ID' \
  -d '{
    "text": "Your order has been shipped.",
    "text_translated": "",
    "attachments": [
      "file1.png",
      "file2.png"
    ]
  }'

Fetching Messages

Retrieve message history for an order with a GET request, supporting pagination via limit and offset parameters:

curl -H 'Authorization: Bearer ACCESS_TOKEN' \
  -X GET 'https://api.mercadolibre.com/marketplace/messages/packs/ORDER_ID?limit=10&offset=0'

The response includes message details such as sender, recipient, text, and attachments. Important parameters:

• from: Sender information with user_id.
• to: Recipient information with user_id.
• text: Message content.
• attachments: List of atatched files.
• site_id: Identifier for the Mercado Libre site (e.g., MLM for Mexico).

Shipment Information

Obtain shipping details by querying the shipments endpoint:

curl -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'x-format-new: true' \
  -X GET 'https://api.mercadolibre.com/marketplace/shipments/SHIPMENT_ID'

The response contains shipment status, tracking data, origin, destination, and dimensions.