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
• Considerations
• What events trigger notifications?
• Get the details
• Feed History API

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.
– Callback URL de Notificaciones: Configure the public URL of your domain where you want to receive notifications for the different topics. E.g.: “http://myshoes-app.com/callbacks”. – Topics: Select among different topics to receive their notifications. Explanatory note: Topics orders, created_orders and payments 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.
Explanatory 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.

Considerations

• Messages will be sent out and retried for a period of 12 hours. After that period, if not accepted by the app, they will be discarded.
• Since we will send a POST to your URL, your application must acknowledge the reception with an HTTP status code 200, otherwise the message will be considered undelivered and it will be retried.
• Your application must send a response within 20 seconds, otherwise it will timeout and be considered undelivered and will retry.

What events trigger notifications?

items

• Changes on any of the attributes.
• Changes on the status: The listing has to be reviewed by an operator and the status is changed to “under_review” or it is paused and the status is changed to “paused”.

orders

• Stock decrement: Somebody purchases one of your items and the stock is decremented. A new order is created.
• Pago: The buyer adds a payment order.
• Shipping: There is new shipping information associated with the order or the shipping status which changes to: pending, ready to print, in transit, delivered, not delivered.
• Feedback: The buyer rates you as a seller or you send feedback to the buyer. A feed is received on the order.
Explanatory note: while "orders" is made up of blocks of other APIs, not every data is displayed, as not all of them are required. These separate blocks may have changes, which triggers events and subsequent notifications related to the order, though sometimes there is no evident change from the previous JSON.

created_orders

• A created_orders notification will be received when an order entered through the mandatory Mercado Pago flow is created. This is only to reserve stock.
• Once the order is “paid,” all notifications are the same as those in the “orders” topic. If both topics are selected, you will receive notifications from both of them.

questions

• You receive a new question.
• You answer a question.
• You delete a question that you considered inappropriate.

payments

• A payment is generated.
• Payment status changes.

pictures

• When an image failed to be displayed due to errors.

Explanatory Note: In case you receive duplicate notifications, bear in mind that there are internal events that are not visible to the integrator, but 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/MLB139876",
  "user_id": 1234,
  "topic": "items",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

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

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID

orders and created_orders

Notification response:

{
    "resource": "/orders/139876",
    "user_id": 1234,
    "topic": "orders",
    "received": "2011-10-19T16:38:34.425Z",
    "sent" : "2011-10-19T16:40:34.425Z",
}

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

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

questions

Notification response:

{
  "resource": "/questions/139876",
  "user_id": 1234,
  "topic": "questions",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

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

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/questions/$QUESTION_ID

payments

Notification response:

{
  "resource": "/collections/1780558484",
  "user_id": 149218964,
  "topic": "payments",
  "application_id": 2470,
  "attempts": 1,
  "sent": "2016 - 01 - 15 T18: 12: 31.313 Z ",
  "received": "2016 - 01 - 15 T18: 12: 31.299 Z "
}

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

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/collections/$PAYMENT_ID

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 picture resource:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/pictures/$PICTURE_ID/errors

You should identify why the image failed to be correctly processed. See “considerations and best practices working with pictures”.

Feed History API

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

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/myfeeds?app_id=$APP_ID

Response:

{
  "messages": [
  {
    "_id": "123aaa456bbb789ccc",
    "application_id": "1234",
    "user_id": "123456789",
    "resource": "/orders/12345678",
    "topic": "orders",
    "sent": "2014-10-24T11:00:00.836Z",
    "received": "2014-10-24T11:00:00.836Z",
    "attempts": "2",
    "http_code": "400",
    "created_at": "2014-10-24T11:00:00.836Z"
  }
}
}

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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/myfeeds?app_id=$APP_ID&offset=1&limit=5

Next topic: Searches and advanced features.