Receive notifications

Some events occur on Global Selling’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
→Events trigger notifications
→Considerations
→Get the details
    ↳items
    ↳marketplace_items
    ↳marketplace_orders
    ↳marketplace_questions
    ↳ marketplace_messages
    ↳marketplace_claims
→Test your notifications
→Feed historial
    ↳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.


Available topics

items: notified of any changes on a parent item you have published.

marketplace_items: notified of any changes to any of your marketplace items.

marketplace_orders: notified of your recently created sales orders.

marketplace_questions: notified of all questions asked or answered.

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

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


Events trigger notifications

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/CBT123456789",
   "user_id": 123456789,
   "topic": "items",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2020-01-09T13:44:33.006Z",
   "received": "2020-01-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

marketplace_items

Notification response:

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

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

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

marketplace_orders

Notification response:

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

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

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

marketplace_questions

Notification response:

{
   "resource": "/marketplace/questions/5036111111",
   "user_id": "123456789",
   "topic": "marketplace_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/marketplace/questions/$QUESTION_ID?access_token=$ACCESS_TOKEN

marketplace_messages

Notification response:

{
  "resource": "/marketplace/messages/3f6da1e35ac84f70a24af7360d24c7bc",
  "user_id": "268897726",
  "topic": "marketplace_messages",
  "application_id": 2219612378080430,
  "attempts": 1,
  "sent": "2020-03-17T12:59:44.164Z",
  "received": "2020-03-17T12:59:44.131Z"
 }

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

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

marketplace_claims

Notification response:

{
  "resource":"/marketplace/claims/1041417027",
  "user_id":"465432224",
  "topic":"marketplace_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/marketplace/claims/$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

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


Request:

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": "/marketplace/messages/5da8a1b24be30a49eb66c52a",
           "resource": "a35cf79864a845ca9a3bf6aee59bb4d7",
           "user_id": "465432224",
           "topic": "marketplace_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\":\"/marketplace/messages/a35cf79864a845ca9a3bf6aee59bb4d7\",\"user_id\":\"465432224\",\"topic\":\"marketplace_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": "/items/CBT123456789",
           "resource": "/items/CBT123456789",
           "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/CBT123456789\",\"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.

Request:

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=items&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