Receive notifications

Some events occur on MercadoLibre's side and notifications are the only way to become aware of them. Receiving notifications enables you to have a real-time feed of the changes that occur on the different resources of our API. For example, if you listed an item that was then paused, if someone asked a question, if they bought an item, or even if they paid it and/or requested shipment. An efficient way with no need to continuously query our API!

Contents

→Subscribe to notifications
→Available topics
→What events trigger notifications?
→Considerations
→Get the details
    ↳items
    ↳orders
    ↳created_orders
    ↳questions
    ↳payments
    ↳pictures
    ↳messaging
    ↳orders_v2
    ↳quotations
    ↳invoices
    ↳claims
→Test your notifications
→Feed historial API
    ↳Campos del recurso
    ↳Filter by topic


Subscribe to notifications

If you want to start receiving notifications you need to go to our application manager, where you first created your app, and edit the details and specify the topics you will listen to.

Note:
If you haven’t created your App yet, go to the Creating your app section.

Notifications Callback URL : configure the public URL of your domain where you want to receive notifications for the different topics. For example: “http://myshoes-app.com/callbacks”.

Topics: select among different topics to receive their notifications.

Nota:
topics orders, created_orders, payments and messaging are not user for real state, vehicles and services.


Available topics

items: to get notified of any changes on an item you have published.

orders: to get notified of any changes to any of our confirmed sales.

created_orders: to get notified of your recently created sales when they are entered through the mandatory Mercado Pago flow. You will only get product data and number of units, since the purchase has not been confirmed yet. You should not take any action until it changes to “paid.” This is only to reserve stock, because if the buyer pays but the item is out of stock, the payment is automatically returned and the sale is canceled.

Note:
Once the order is paid, notifications are sent just like in “orders;” thus, we suggest choosing only one of the topics to avoid duplicated events.

questions: to get notified of all questions asked or answered.

payments: to get notified when a payment is created on an order, or when its status changes.

pictures: to get notified only of images which cannot be displayed due to errors.

Note:
Meanwhile, an automatic e-mail grouping the faulty images will be sent to the seller.

messages: the topic will inform the subscriber of new messages created with his/her user_id as receiver.

orders_v2: you will receive notifications after the creation and changes to any your of confirmed sales (recommended).

shipments: you will receive notifications after the creation and shipping changes to your confirmed sales.

quotations: you will receive notifications related to listing quotations (applicable to real estate integration only in Mercado Libre Chile)

invoices: you will receive notifications related to invoices (sales receipts) generated via Mercado Libre automatic billing applicable if working with Mercado Envíos Full biller only. It is available only in Brazil

claims: you will receive notifications related to sales claims (work with claims).

Note:
Once the order is paid, notifications will begin to be sent as from “orders”, so we suggest choosing only one of the topics to avoid duplicate events.
  • questions: you will receive notifications of all questions asked or answered.
  • payments: you will receive notifications when a payment is created in an order or its status changes.
  • pictures: you will receive notifications only of the images that for some error will not be able to be downloaded.
Note:
At the same time, an automatic email will be sent to the seller, collecting the problem images.


What events trigger notifications?

Bear in mind that any change to any topic of the Json will trigger the relevant notifications. You should always see the notifications and immediately query the relevant resource to check whether there is a change with its application. These changes may come from other sources, such as action via front, Seller Central, or other applications, etc.


Considerations

We will send a POST in the URL; so, your application should confirm -as soon as possible- if the HTTP 200 status code was received. Otherwise, the message will be considered “not sent” and new attempts will be made. Messages will be sent and attempts will be made at 12-hour intervals. After this period, messages that have not been accepted will be excluded.
Taking into account that you may get a large number of notifications, it is advisable to work with rows, in which the server should immediately confirm notification receipt (HTTP 200) and query the topic in the API to avoid new notification attempts and duplicated notifications.
Bear in mind that some events are not visible for integrators that trigger notifications.


Get the details

After receiving a notification of one topic, you’ll need to make a GET to the resource to get the details and then, if you stored the previous Json, compare both.


items

Notification response:

{
   "resource": "/items/MLA686791111",
   "user_id": 123456789,
   "topic": "items",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:44:33.006Z",
   "received": "2017-10-09T13:44:32.984Z"
}

This information will help you make a GET to the items resource:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ID?access_token=$ACCESS_TOKEN

orders

Notification response:

{
   "resource": "/orders/1499111111",
   "user_id": 123456789,
   "topic": "orders",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:58:23.347Z",
   "received": "2017-10-09T13:58:23.329Z"
}

This information will help you make a GET to the orders resource:

curl -X GET https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

created_orders

Notification response:

{
   "resource": "/orders/1499111111",
   "user_id": 123456789,
   "topic": "created_orders",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:49:46.519Z",
   "received": "2017-10-09T13:49:46.531Z"
}


questions

Notification response:

{
   "resource": "/questions/5036111111",
   "user_id": "123456789",
   "topic": "questions",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:51:05.464Z",
   "received": "2017-10-09T13:51:05.438Z"
}

This information will help you make a GET to the questions resource:

curl -X GET https://api.mercadolibre.com/questions/$QUESTION_ID?access_token=$ACCESS_TOKEN

payments

Notification response:

{
   "resource": "/collections/3043111111",
   "user_id": 123456789,
   "topic": "payments",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:58:22.081Z",
   "received": "2017-10-09T13:58:22.061Z"
}

This information will help you make a GET to the questions resource:

curl -X GET https://api.mercadolibre.com/collections/$PAYMENT_ID?access_token=$ACCESS_TOKEN

pictures

Notification response:

{
  "messages": [
    {
      "_id": "123aaa456bbb789ccc",
      "application_id": "1234",
      "user_id": "123456789",
      "resource": "/pictures/12345-MLA1234567-20160729/errors",
      "topic": "pictures",
      "sent": "2016-07-24T11:00:00.836Z",
      "received": "2016-07-24T11:00:00.836Z",
      "attempts": "2",
      "created_at": "2016-07-24T11:00:00.836Z"
    }
  ]
}

This information will help you make a GET to the pictures resource:

curl -X GET https://api.mercadolibre.com/pictures/$PICTURE_ID/errors?access_token=$ACCESS_TOKEN

Você terá que identificar por que a imagem não foi corretamente processada.
Veja mais considerações e melhores práticas para trabalhar com imagéns.


messages

Notification response:

<{
  "resource": "3f6da1e35ac84f70a24af7360d24c7bc",
  "user_id": "268897726",
  "topic": "messages",
  "application_id": 2219612378080430,
  "attempts": 1,
  "sent": "2017-08-17T12:59:44.164Z",
  "received": "2017-08-17T12:59:44.131Z"
 }

This information will help you make a GET to the messages resource:

< curl -X GET https://api.mercadolibre.com/messages/$RESOURCE?access_token=$ACCESS_TOKEN

orders_v2

Notification response:

{
  "resource":"/orders/2195160686",
  "user_id": 468424240,
  "topic":"orders_v2",
  "application_id": 5503910054141466,
  "attempts":1,
  "sent":"2019-10-30T16:19:20.129Z",
  "received":"2019-10-30T16:19:20.106Z"
}

This information will help you make a GET to the messages resource:

curl -X GET https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

quotations

Notification response:

{
    "resource":"/quotations/5013267",
    "user_id": 484630370,
    "topic":"quotations",
    "application_id": 5503910054141466,
    "attempts":1,
    "sent":"2019-10-30T14:04:14.584Z",
    "received":"2019-10-30T14:04:14.553Z"
}
Note:
Notifications regarding quotes are only available for Mercado Libre Chile.

This information will help you make a GET to the orders resource:

curl -X GET https://api.mercadolibre.com/quotations/$QUOTATION_ID?caller.type=seller&access_token=$ACCESS_TOKEN

Where caller.type is to identify who is the generator of the action. It can be a seller or a user. Generally, for launch applications it will be that of the seller.


invoices

Notification response:

{
    "resource": "/users/123456789/invoices/$INVOICE_ID",
    "user_id": 123456789,
    "topic": "invoices",
    "application_id": 5503910054141466,
    "attempts": 1,
    "sent": "2018-03-21T20:51:11.906Z",
    "received": "2018-03-21T20:51:11.884Z"
}

This information will help you make a GET to the orders resource:

curl -X GET https://api.mercadolibre.com/$RESOURCE?access_token=$ACCESS_TOKEN

claims

Notification response:

{
  "resource":"/v1/claims/1041417027",
  "user_id":"465432224",
  "topic":"claims",
  "application_id":5503910054141466,
  "attempts":1,
  "sent":"2019-10-29T17:46:24.606Z",
  "received":"2019-10-29T17:46:24.616Z"
}

This information will help you make a GET to the orders resource:

curl -X GET https://api.mercadolibre.com/$RESOURCE?access_token=$ACCESS_TOKEN


Test your notifications

You can validate if you are receiving notices in your integration importing the following link in Postman. If your URL works well, you will be receiving code 200 status ok as an answer as shown in the following image.


Feed historial API

We keep a track of your notifications history and you can get it anytime by calling our feeds resource.


Call:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id=$APP_ID&access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id=3486171129139063&access_token=$ACCESS_TOKEN

Response:

{
   "messages": [
       {
           "_id": "5da8a1b24be30a49eb66c52a",
           "resource": "a35cf79864a845ca9a3bf6aee59bb4d7",
           "user_id": "465432224",
           "topic": "messages",
           "application_id": 3486171129139063,
           "attempts": 1,
           "sent": "2019-10-17T17:15:30.279Z",
           "received": "2019-10-17T17:15:30.259Z",
           "request": {
               "url": "https://YOUR_URL",
               "headers": {
                   "accept": "application/json",
                   "content-type": "application/json",
                   "content-length": 207
               },
               "data": "{\"resource\":\"a35cf79864a845ca9a3bf6aee59bb4d7\",\"user_id\":\"465432224\",\"topic\":\"messages\",\"application_id\":3486171129139063,\"attempts\":1,\"sent\":\"2019-10-17T17:15:30.279Z\",\"received\":\"2019-10-17T17:15:30.259Z\"}"
           },
           "response": {
               "req_time": 260,
               "http_code": 400,
               "body": "[object Object]",
               "headers": {
                   "date": "Thu, 17 Oct 2019 17:15:30 GMT",
                   "content-length": "141",
                   "content-type": "text/plain; charset=utf-8",
                   "connection": "close"
               }
           }
       },
       {
           "_id": "5da87eea5b35b865994cfd7d",
           "resource": "/items/MLA820048955",
           "user_id": 468424240,
           "topic": "items",
           "application_id": 3486171129139063,
           "attempts": 1,
           "sent": "2019-10-17T14:47:06.414Z",
           "received": "2019-10-17T14:47:06.375Z",
           "request": {
               "url": "https://YOUR_URL",
               "headers": {
                   "accept": "application/json",
                   "content-type": "application/json",
                   "content-length": 189
               },
               "data": "{\"resource\":\"/items/MLA820048955\",\"user_id\":468424240,\"topic\":\"items\",\"application_id\":3486171129139063,\"attempts\":1,\"sent\":\"2019-10-17T14:47:06.414Z\",\"received\":\"2019-10-17T14:47:06.375Z\"}"
           },
           "response": {
               "req_time": 498,
               "http_code": 200,
               "body": "[object Object]",
               "headers": {
                   "content-type": "application/json; charset=utf-8",
                   "date": "Thu, 17 Oct 2019 14:47:06 GMT",
                   "content-length": "190",
                   "connection": "close"
               }
           }
       }

}

Resource fields

resource: full resource, with topic by which the notification was generated.

user_id: user who generated it.

topic: reference issue of the notification.

request: query made to the URL of notifications, along with their respective url, header and data.

response: response from the server receiving the notification.

http_code: HTTP code returned by that server, so that it does not retry, you must send a 200.


Filter by topic

There is the possibility of filtering by topic, it is very useful for when you have a large number of notifications.

Call:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id=$APP_ID&topic=$TOPIC&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id=3486171129139063&topic=payments&access_token=$ACCESS_TOKEN
Note:
Bear in mind that 10 notices will be displayed by default, but you can use LIMIT and OFFSET to change the number that you want to receive, as shown below:
curl -X GET https://api.mercadolibre.com/myfeeds?app_id=$APP_ID&offset=1&limit=5&access_token=$ACCESS_TOKEN

Be part of our community