Messaging after sale

The messing API resource will enable you to get messages from a specific order, create new messages in the system, and send or receive attachments.
Let’s see how you can use it!

Contents:

Parameters description

message_id Message id
date_created Date of creation
date Date a message is saved
date_received Date a message is received
date_availableDate a message went through moderation
date_notified Date a message was notified to counterparty
date_read Date a message was read by counterparty

from A message sender
user_id Id of user who sent message
email Email of user who sent message (order secure email)
name Name of user who sent message

to A message recipient
user_id Id of user who received message
email Email of user who received message (order secure email)

subject Email subject
text Message text
plain Message plain text

attachments Attached files
attachments_validations Attachment validation
invalid_size If attachment size is invalid
invalid_extension Invalid attachment extension
internal_error Internal error

site_id Mercado Libre (MLA, MLB, etc.) site
resource Corresponding to order it pertains to (orders)
resource_id Order ID
status Message status
moderation_status Message moderation status

Get messages

To get messages from a specific order, you should associate the order_id with this resource via GET.

Call:

GET ".../messages/orders/$order_id"

Example:

 curl -X GET “https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN”

Possible extra parameters:

These parameters can be used to determine the number of messages recovered by GET.

&limit={límite} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10”

&offset={compensación} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10&offset=1”

Response:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 270
    },
    "results": [
        {
            "_id": "43b450d6bd3f47fb94394041b26c519f",
            "message_id": "43b450d6bd3f47fb94394041b26c519f",
            "date_received": "2016-11-07T15:03:14.978Z",
            "date": "2016-11-07T15:03:14.978Z",
            "date_available": "2016-11-07T15:03:14.978Z",
            "date_notified": "2016-11-07T15:05:50.179Z",
            "date_read": "2016-11-08T22:43:17.767Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        },
        {
            "_id": "37befd545a2d436f89e672b33990ef8b",
            "message_id": "37befd545a2d436f89e672b33990ef8b",
            "date_received": "2016-11-07T14:56:02.500Z",
            "date": "2016-11-07T14:56:02.500Z",
            "date_available": "2016-11-07T14:56:02.500Z",
            "date_notified": "2016-11-07T14:57:46.659Z",
            "date_read": "2016-11-07T15:19:08.967Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        }
    ]
}

Notes:

  • Per each sale from a buyer you will get a different masked email. That is, if the same buyer purchases you two different products at different times, each sale will generate an email.
  • The buyer’s contact mails will be viewed masked so the number of characters (between 55 and 60) will increase.

Get messages by ID

Request:

GET “https://api.mercadolibre.com/messages/{message_id}?access_token=$ACCESS_TOKEN”

Response Example:

{
  "message_id": "0033b582a1474fa98c02d229abcec43c",
  "date_received": "2016-09-01T05:15:25.821Z",
  "date": "2016-09-01T05:15:25.821Z",
  "date_available": "2016-09-01T05:15:25.821Z",
  "date_notified": "2016-09-01T05:17:42.945Z",
  "date_read": "2016-09-01T21:31:19.606Z",
  "from": {
    "user_id": "123456789",
    "email": "userfrom.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
    "name": "User from"
  },
  "to": [
    {
      "user_id": "123456780",
      "email": "userto.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
    }
  ],
  "subject": "Test Item subject",
  "text": {
    "plain": "Ejemplo de texto"
  },
  "attachments": [
    {}
  ],
  "attachments_validations": {
    "invalid_size": [
    ],
    "invalid_extension": [
    ],
    "forbidden": [
    ],
    "internal_error": [
    ]
  },
  "site_id": "MLA",
  "resource": "orders",
  "resource_id": "1234567871",
  "status": "available",
  "moderation": {
    "status": "non_moderated"
  }
}

Create messages

In case of from seller, order seller.id will go in from.user_id.

Call:

POST “https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID” 

Note: The “application_id” is only required when the Access Token does not have the APP ID embedded.

Example:

curl -i -X POST -H "Content-Type: application/json" -H “X-Client-Id: {application id}” -d
'{
    "from": {
        "user_id": 123435,
    },
    "to": [
        {
            "user_id": 9191923,
            "resource": "orders",
            "resource_id": 2223213,
            "site_id": "MLA"
        }
    ],
    "text": {
        "plain": "Plain text message here"
    }
}’ https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID

Note: The attachments attribute is obtained from the attachment POST response. (See attachments section).

Send attachment

To attach a file in the message, you need to save it first.
Then, when the attachment is sent, the file id is returned as response.

Call:

POST “https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN”

Notes:

  • The POST needs to be made form.data with key: value > file = reference to file (that is, the file itself).
  • The file needs to have a maximum 25 MB size.
  • You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 25 MB in JPG, PNG, PDF and TXT format.

Example:

curl-i-XPOST-H"Content-Type: multipart/form-data"-F"file=@/home/user/file""https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN"

In this case, the server will respond with a JSON containing file id in case of a successful request.

Note: The response obtained should be attached to the intended message.

Response:

{
  "id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}

Get attachment

To get an attached message, you need to make a GET.

Call:

GET “https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN” 

Example:

https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?access_token=$ACCESS_TOKEN

Response:
If the request is successful, the call will return the requested file.

In case the file cannot be accessed, the server response will be the following:

{
    "message": "File can not be accessed, try it later",
    "error": null,
    "status": 500,
    "cause": []
}



In case the access token is not sent, the message will be:

{
    "message": "Access token is required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}



To conclude, following all these steps, the POST will be like this…

Example:

{
    "from": {
      "user_id": 123455677
    },
    "to": [
        {
            "user_id": 72345286,
            "resource": "orders",
            "resource_id": 1234567671,
            "site_id": "MLA"
        }
    ],
    "text": {
      "plain" : "Mensaje de pruebas"
    },
  	"attachments" : ["76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png" ]


}

Response:

[
    {
        "message_id": "d2345e6e7bb844469ae79623018223af",
        "date_received": "2016-11-14T20:46:49.678Z",
        "date": "2016-11-14T20:46:49.678Z",
        "date_available": "2016-11-14T20:46:49.678Z",
        "date_notified": null,
        "date_read": null,
        "from": {
            "user_id": "123455677",
            "email": "userseller.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
            "name": null
        },
        "to": [
            {
                "user_id": "72345286",
                "email": "userbuyer.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
            }
        ],
        "subject": null,
        "text": {
            "plain": "Mensaje de pruebas"
        },
        "attachments": [
            {
                "size": "103584",
                "type": "image/png",
                "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                "filename": "76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png",
                "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
            }
        ],
        "attachments_validations": null,
        "site_id": "MLA",
        "resource": "orders",
        "resource_id": "1125027671",
        "status": "available",
        "moderation": {
            "status": "non_moderated"
        }
    }
]

Messages pending reading

This option will let you get in Mercado Libre messages pending reading from all the existing orders or just specific orders.

You can also define the user role in each case, whether buyer or seller.

To obtain the above mentioned information, make a GET as shown below.

Call:

GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

(Optional) Parameters:

To receive a list of specific orders, send comma separated IDs (…&orders_id=id1,id2,…,):
orders_id=$ORDERS_ID

In turn, to receive the user role in an order, Buyer example: …&role=buyer – Seller example: …&role=seller), you will need to do it with the following parameter: role=$ROLE

Use mode

If you want to get all the orders with messages pending reading as seller, you will need to make this call:

No role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

Clarification: If no role is specified or if it is invalid (other than “buyer” or “seller”), the resource will take the “seller” role by default.

With role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=seller

To get all the orders with messages pending reading as buyer, you will need to make this call:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=buyer

If you want to get the number of messages pending reading for the orders, you will need to do this:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&orders_id=123,124,125

Response:
If the API response is satisfactory, you will get a JSON like this:

{
    "user_id": "1234512314",
    "results": [
        {
            "order_id": "19912312312”
            "count": 1
        }
    ]
}

In this response, you will see:

  • ID of user who made request (“user_id”).
  • Messages pending reading (“count”).
  • Each available order (“order_id”).

Finally, if there are no messages pending reading for all the user’s orders or specific user’s orders, or if the user specifies within the “orders_id” parameter those orders that are not part of it, the response will be like this:

{
    "user_id": "1234512314",
    "results": []
}

Note: This is a private resource, so if you make a call without access_token, you will get error 400.

Request without access token:

{
    "message": "Access token required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Mark messages as read

With this PUT call, you can mark messages as read in Mercado Libre providing the IDs you want to read in the URL.

Note: Messages should be separated by comma (,); otherwise, they will not be recognized as different messages.

Call:

PUT /messages/mark_as_read/:messages_id

Example:

https://api.mercadolibre.com/messages/mark_as_read/id1,id2,id3?access_token=$ACCESS_TOKEN

Response:

{
    "message": "Messages marked as read successfully",
    "status": 200
}

Review blocked messages

In order to reduce spam and unnecessary messages, messages can be blocked within post sale messaging because:

  • The buyer has blocked message delivery.
  • After a period of time, message delivery is automatically blocked.

Via API you can find them under the “Blocked” status in a new section called “conversation”:

Call:

https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN

Response:

{
  "paging": {...},
  "results": [{...},{...}],
  "conversation": {
"status": "blocked",
"substatus": "blocked_by_buyer",
      "status_date": "2017-05-26T13:17:23.511-04:00"
   }
}

status: This field allows two values:

  • active: conversation is open for sending/receiving messages
  • – substatus: null

  • blocked: conversation is closed to sending/receiving messages
  • – substatus: Blocked_by_time: Conversation has been blocked automatically after a period of time.
    – substatus: Blocked_by_buyer: Conversation has been blocked due to buyer request.

status_date: Represents the date when conversation status was recorded.

Possible errors

Common errors

Request without access token:

{
  "message": "Access token is required",
  "error": "bad_request",
  "status": 400,
  "cause": [ ]
}

Errors to get message by id

User is denied access to a certain message:

{
  "message": "Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4",
  "error": "forbidden",
  "status": 403,
  "cause": [ ]
}

Requested message does not exist:

{
    "message": "The specified message id does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Post errors

Message without receiver (“to” is missing):
400: The field ‘to.user_id’ is required

User id “to” invalid:
400: Invalid ‘to’ user id

User “from” and “to” are the same:
400: Sender and received must not be equals

User “from” is denied access to order:
403: Access denied for user {from.user_id} to order {to.resource_id}

If user_id is 0 and email is not a secure_email:
400: The field ‘to.email’ must be a secure email

Message receiver does not belong to order:
403: Receiver does not belong to order {to.resource_id}

“Resource” attribute is not found:
400: The field ‘to.resource’ is required

Resource attribute is invalid:
400: Invalid field ‘to.resource’

Request without site_id:
400:The field ‘to.site_id’ is required

site_id attribute is invalid:
400: The field ‘to.site_id’ has an invalid value

Post without Json body:
400: A JSON body is required

Message without ‘from’:
400: The field ‘from’ is required

Request without access token:
400: Access token is required

Access Token without application_id:
400: Application id is required

Messaging is blocked:
403: You can not send the message because the conversation is blocked by buyer.

403: You can not send the message because the conversation has been blocked by time.

GET messages by order Errors

User with no access to order:
403: User access token invalid for resource {resource_id}”

Request “limit” param must be greater than 0:
400: The limit param must be greater than 0

“Offset” param is invalid:
400: Invalid offset param

“Limit” param is invalid:
400: Invalid limit param

GET attachments Errors

Requested file could not be obtained:
500: File can not be accessed, try it later

Post attachments Errors

Problems when saving file:
500: File can not be saved, try it later

Attachment empty or null:
400: File attached is empty

File name cannot include characters such as: /, \
400: File name cannot include characters like /, \

File size exceeds 25 Mb. File size: x
400: File attachment is bigger than 25 Mb.

Message exceeds allowed number of attachments: 25
400: The message exceeds the allowed number of attachments: 25

PUT errors messages marked as unread

Invalid or empty message IDs

{
    "message": "Messages id empty or invalid.",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Ineffective message IDs

{
    "message": "The specified message id: a does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Message IDs that correspond to different orders

{
    "message": "Not allowed messages from multiple orders",
    "error": "bad_request",
    "status": 400,
    "cause": []
}



To get more information about how to use this service without logging out Mercado Libre, click here.


Next topic:
Subscribe to our feeds.

Please rate this

Deals

Sellers who receive advice from Mercado Libre’s sales team are regularly invited to participate in different deals campaigns that take place during the year in our website. If you have received an invitation for one of this campaigns and you want to join, follow this tutorial to learn the basic of how to suggest your products.

Deals

Contents:

Important:

  • For testing purposes, a test user must be used. This guarantees that you will always have a deal (campaign) available for proposing ítems.
  • To make a call to this API, you will need an access token.

Obtain the campaigns you were invited to

This resource retrieves the deals campaigns associated to a user_id. There can be more than one per user.

Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/deals/search?access_token=$ACCESS_TOKEN

Response:

{
  "paging": {
    "total": 2,
    "offset": 0,
    "limit": 0
  },
  "filters": {
    "site_id": "MLA"
  },
  "results": [
    {
      "id": "MLA90",
      "name": "pruebaIntegracion",
      "description": "Prueba Integracion",
      "site_id": "MLA",
      "status": "test",
      "offers_reception_deadline": "2016-08-30T23:00:00-04:00",
      "start_time": "2016-08-18T03:00:00.000Z",
      "end_time": "2016-08-19T02:59:00.000Z",
      "requisites": [
        {
          "name": "RequisiteDiscount",
          "criteria": "original_price",
          "categories": [
            "MLA1144"
          ],
          "parameters": {
            "value": "20",
            "type": "gold_special"
          },
          "description": "Items with listing gold_special type must have at least 20% off"
        },
        {
          "name": "RequisiteDiscount",
          "criteria": "original_price",
          "categories": [
            "MLA1144"
          ],
          "parameters": {
            "value": "15",
            "type": "gold_premium"
          },
          "description": "Items with listing type gold_premium must have at least 15% off"
        },
        {
          "name": "CATEGORIES_REQUISITE",
          "criteria": "NA",
          "categories": [
            "MLA5726",
            "MLA1276",
            "MLA1384"
          ],
          "parameters": {
          },
          "description": "Items must belong to the specified categories"
        },
        {
          "name": "RequisiteFreeShipping",
          "criteria": "retail_price",
          "categories": [
            "MLA5725"
          ],
          "parameters": {
            "currency": "ARS",
            "value": "500"
          },
          "description": "Items in the specified categories and with price higher than ARS 500 must have free shipping"
        }
      ]
    }
  ]
}

One important field you should pay attention in this response is the field “dead_line”, which indicates up to when you will be able to suggest your products. After that time, you will not be allowed to suggest items for the campaign.
The field “requisites” contains a set of requisites that your proposed items must meet in order to join the campaign. These requisites are defined by Mercado Libre for each campaign.

Propose a product for a campaign

Once you know you have been invited to a deals campaign, you can select which of your products you want to include in the campaign and propose them. You might have to detail the conditions in which your products will participate in the campaign (i.e. discount price for the campaign, stock for the campaign, etc.).

Request (example):

curl -X POST -d '{"item_id":"MLA632979587","deal_price":149,"regular_price":200,"declared_stock":8,"declared_free_shipping":true, "brand":"brand1","model":"model1","declared_oro_premium_full":true}' 'https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items?access_token=$ACCESS_TOKEN'

Response (example):

{
  "item_id": "MLA633000763",
  "regular_price": 200,
  "deal_price": 149,
  "declared_stock": 8,
  "declared_free_shipping": true,
  "declared_oro_premium_full": true,
  "category_l1": "MLA1953",
  "category_l2": "MLA3530",
  "brand": "brand1",
  "model": "model1",
  "date_created": "2016-08-29T14:08:10.902-04:00",
  "last_updated": "2016-08-29T14:08:10.902-04:00",
  "status": "pending_approval",
  "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
}

Modify a product in a campaign

If the deadline date has not been reached, you are allowed to make modifications to the products you have previously suggested for a campaign.
Request:

curl -X PUT -d '{"deal_price":150}' 'https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items/{Item_id}?access_token=$ACCESS_TOKEN'

Response (example):

{
  "item_id": "MLA633000763",
  "regular_price": 200,
  "deal_price": 152,
  "declared_stock": 8,
  "declared_free_shipping": true,
  "declared_oro_premium_full": true,
  "category_l1": "MLA1953",
  "category_l2": "MLA3530",
  "brand": "brand1",
  "model": "model1",
  "date_created": "2016-08-29T14:08:11.000-04:00",
  "last_updated": "2016-08-29T14:34:53.662-04:00",
  "status": "pending_approval",
  "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
}

Remove a product from a campaign

If the deadline date has not been reached, you are allowed to remove products you have previously suggested for a campaign.
Request:

curl -X DELETE https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items/{Item_id}?access_token=$ACCESS_TOKEN

Response:

{}

Response with status 204.

Obtain my products in a campaign

You can obtain the products you have suggested for a campaign.

Request:

curl -X GET https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items/search?access_token=$ACCESS_TOKEN

Response:

{
  "paging": {
    "total": 2,
    "offset": 0,
    "limit": 50
  },
  "filters": {
    "deal_id": "MLA90",
    "seller_id": "210456151"
  },
  "results": [
    {
      "item_id": "MLA632979587",
      "current_price": 170,
      "regular_price": 200,
      "deal_price": 149,
      "declared_stock": 8,
      "declared_free_shipping": true,
      "declared_oro_premium_full": true,
      "category_l1": "MLA1953",
      "category_l2": "MLA3530",
      "brand": "brand1",
      "model": "model1",
      "date_created": "2016-08-29T11:52:01.000-04:00",
      "last_updated": "2016-08-29T11:52:01.000-04:00",
      "status": "pending_approval",
      "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
      "discount": 26
    },
    {
      "item_id": "MLA632632625",
      "current_price": 200,
      "regular_price": null,
      "deal_price": 100,
      "declared_stock": 50,
      "declared_free_shipping": false,
      "declared_oro_premium_full": false,
      "category_l1": "MLA1953",
      "category_l2": "MLA3530",
      "brand": "Prueba",
      "model": "Cool",
      "date_created": "2016-08-26T10:34:04.000-04:00",
      "last_updated": "2016-08-26T10:34:04.000-04:00",
      "status": "pending_approval",
      "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
      "discount": 50
    }
  ]
}

Please rate this

Intellectual Property Protection Program (IPPP)

Our Program enables intellectual property right owners or agents to report and request removal of postings breaching their rights.

To report postings, you need to adhere to the Program.

Once you become an IPPP member, you should request the report API instructions through the form. You will find all the necessary information on how to integrate there.

In case members need more information on the program, please write to us from this form.

In case you have any problem or doubt on how the API works, you can contact us.

Please rate this

Attributes and Variations

We would like to show you all the options you can include when you list an item so that you can improve its data sheet and description.
Review the following documents to learn how to use them:

Attributes

Click here to learn how to display characteristics.

Product identifiers

If you want to add codes for a product univocal unification, see the next guide to learn how to do it.

Variations

Finally, if in the same listing you need to show the variations of an item, click here.

Please rate this

Product identifiers

Identifiers are codes used to unequivocally locate a product.

Contents:

What is GTIN?

GTIN (Global Trade Item Number) is the global trade item number used to unequivocally identify any product or item about which there is a need to both retrieve specific information and put a price to.
It is a standard that includes codes: EAN, UPC, JAN, ISBN13.

Who can send us this information?

Using API-based resources, every seller from Argentina, Brazil, Chile, Colombia, Mexico, and Uruguay can send product identifiers as attributes in their listings.

Important: We will highlight the listings from sellers who send this information correctly.

In turn, high-level reputation sellers from Brazil and Mexico who send product identifiers will have a chance to be selected and display their items in the Google Shopping catalog.

How can I differentiate them from other attributes?

They read “type”: “product_identifier” and you can find them in the attribute section or variation.
Son aquellos que tienen como “type”: “product_identifier” y los podrás encontrar en la sección de atributos del ítem o de cada variación.

Benefits

  • Future benefit: To automatically categorize items.
  • Future benefit: To complete item attributes and display them in a VIP data sheet.
  • To boost your listings to the top Search results when you load your product identifier code.

How should I send product identifier information?

You can send this information just like you post attributes, with the possibility of sending any category.

Note: If the item has variations, you can specify a attribute product identifier.

Example of item without variations

curl -X POST -d '{
    "listing_type_id":"gold_special",
    "pictures":[ { "id":"553111-MLA20482692355_112015" } ],
    "title":"Item de testeo -- no ofertar --kc:off",
    "available_quantity":4,
    "buying_mode":"buy_it_now",
    "currency_id":"ARS",
    "condition":"not_specified",
    "category_id":"MLA377600",
    "site_id":"MLA",
    "price":100,
    "attributes": [
        { "id": "CARRIER", "value_id": "298335", "value_name":"Desbloqueado" },
        { "id": "EAN", "value_name": "9780471117094" }
    ]
}' 'https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN'

Example of item with variations

curl -X POST -d '{
    "listing_type_id":"gold_special",
    "pictures":[ { "id":"553111-MLA20482692355_112015" } ],
    "title":"Item de testeo -- no ofertar --kc:off",
    "available_quantity":4,
    "buying_mode":"buy_it_now",
    "currency_id":"ARS",
    "condition":"not_specified",
    "category_id":"MLA377600",
    "site_id":"MLA",
    "price":100,
    "variations": [
        { "picture_ids": [ "553111-MLA20482692355_112015" ], "available_quantity": 2, "price": 100, "attribute_combinations": [ { "id": "COLOR", "value_id": "52049" } ], "attributes": [ { "id": "EAN", "value_name": "4006381333931" } ] },
        { "picture_ids": [ "553111-MLA20482692355_112015" ], "available_quantity": 2, "price": 100, "attribute_combinations": [ { "id": "COLOR", "value_id": "52055" } ], "attributes": [ { "id": "EAN", "value_name": "9780471117094" } ] }
    ]
}
' 'https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN'

How can I add information to an existing item?

Example modification of item:

All existing attributes of the item must be sent including the product identifier code.

Without variation

curl -X PUT -d '''{
  "attributes": [
        {
          "id": "EAN",
          "value_name": "9780471117094"
        },
{
          "id": "BRAND",
          "value_name": "Philips"
        }
      ]
}''' 'https://api.mercadolibre.com/items/MLA642016284'

With variation
For items with variations, if you send the previous PUT, the attribute will be replicated for all variations as product identifiers have variation_attributes. To specify a different product identifier for each variation, see the example below:

curl -X PUT -d '{"attributes": [{ "id": "EAN", "value_name": "9780471117094" }]}' https://api.mercadolibre.com/items/{Item_Id}/variations/{Variations_Id}?access_token=$ACCESS_TOKEN

Just as you modify any attribute in a variation, to modify them you should specify the list of variations that should remain in the item (specifying their variation ID), and add the list of attributes that should remain in each variation.

curl -X PUT -d '{
  "variations": [{
    "id": 847326284,
    "attributes": [{
      "id": "EAN",
      "value_name": "9780471117094"
    }]
  }, {
    "id": 847326282,
    "attributes": [{
      "id": "GRILL",
      "value_name": "No"
    }]
  }]
}' 'https://api.mercadolibre.com/items/MLA642016284'

Watch the following video tutorial explaining in detail how to perform the above tasks.

How can I query information about my product identifiers?

To get this information, you should make a GET to the API:
Call:

curl -X GET https://api.mercadolibre.com/items/MLB558871250?include_attributes=all

Note: Remember that if you relist an item, the Product Identifier that you sent for the original listing will automatically remain.

Considerations

  • They are not internal SKUs.
  • The number of characters varies by code type: they can have 8, 10, 12, 13 or 14 characters. You can even rewrite the same code with left zero padding and it will still be valid.
  • The sent GTINs are validated and, if not valid, the API will disregard them.
  • You can send more than one identifier code for the same product. For example, EAN and UPC.
  • It is advisable to include the Brand and, at least, one additional identifier. These are the conditions required to participate in third-party product listings, such as Google Shopping.
  • If you want to waive this benefit, just send an e-mail to the e-mail addresses below:
    Brazilian sellers: gps-optout@mercadolivre.com.br
    Spanish-speaking sellers: gps-optout@mercadolibre.com
    Subject: cancel subscription {SellerId}
    Message: (optional). Reason why you waive the benefit.
    Remember that, if you waive the benefit, none of your products will be displayed on Google Shopping.

Resource Identifier Description

BRAND: Brand
MPN: Manufacturer Part Number.
GTIN: Global Trade Item Number.
ISBN: International Standard Book Number. Unique identifier for books, intended for commercial use.

There are two types:

ISBN-10
Ten-character code, where the first 9 are always digits, but the last one can be either a digit or a letter ‘X’. This version of the code is NOT compliant with the GTIN standard; however, it can be provided if items so require.
ISBN-13
Numeric 13-character code, included in the GTIN standard.

EAN: European Article Number (now renamed International Article Number). Bar code system used by over 100 countries.

UPC: Universal Product Code. Bar code system generally used in the US and Canada.
upc

JAN: Japanese Article Number. Product identification code system used in Japan. It is compliant with EAN-13 code length and validations.

Part Number

The codes used to unequivocally locate an automotive spare part by defining the spare part compatibilities, among others, are referred to as Part Numbers.
Based on a specific part number we can learn the car for which it is used.

Benefits

  • The lists of the people who load them will be indexed by the car part widget.
  • This will result in a more accurate search method.

ejemplo-partnumber

Next:
Variations.

Please rate this

General attributes

Contents:

    How I can get categories attributes?

    The categories attributes may be obtained performing a GET.

    Call:

    curl - x GET https://api.mercadolibre.com/sites/{SITE_ID}/categories_attributes

    What I can make with this information?

    Once you have obtained the attributes categories you will know what attributes through the next call are:

    curl - x GET https://api.mercadolibre.com/categories/{CATEGORY_ID}/attributes

    How I can change general attributes?

    To change an attribute of an item already created you must do the following CALL:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d "
    {
        "attributes": [{
            "id": "MLA1744-COLOREXT",
            "value_id": "MLA1744-COLOREXT-AMARILLO"
        }, {
            "id": "MLA1744-COMBUS"
        }, {
            "id": "MLA1744-KMTS"
        }, {
            "id": "MLA1744-DOOR"
        }, {
            "id": "MLA1744-YEAR"
        }]
    } "https://api.mercadolibre.com/items/MLA621092868?"access_token={YOUR_ACCESS_TOKEN}"

    Notes:

    • When the attributes don´t have “value_id” are they obligatory/required and lest modified is necessary to send.
    • The JSON response is the same item with the new attribute.

    Delete general attributes

    To delete an attribute you must make a similar call to the following example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d "
    {
        "attributes": [{
            "id": "MLA1744-COMBUS"
        }, {
            "id": "MLA1744-KMTS"
        }, {
            "id": "MLA1744-DOOR"
        }, {
            "id": "MLA1744-YEAR"
        }]
    }
    "https://api.mercadolibre.com/items/MLA621092868?access_token={YOUR_ACCESS_TOKEN
    }"



    Next:
    Particular attributes.

    Please rate this

Attributes

Contents

What is an attribute?

An attribute represents a characteristic of your item, such as Microwave Oven Brand and Model. You can add them when listing an item, and you can change them or add new ones later.
Take into account that attributes vary by category, and you can find them at the following url:

curl -X GET https://api.mercadolibre.com/categories/{CATEGORY_ID}/attributes
[
 {
   "id": "HEADPHONE_FORMAT",
   "name": "Formato",
   "tags": {
     "fixed": true
   },
   "value_type": "list",
   "values": [
     {
       "id": "182349",
       "name": "In-Ear"
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "BRAND",
   "name": "Marca",
   "tags": {
     "fixed": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "values": [
     {
       "id": "15438",
       "name": "Shure"
     }
   ],
   "attribute_group_id": "MAIN",
   "attribute_group_name": "Atributos Principales"
 },
 {
   "id": "COLOR",
   "name": "Color",
   "tags": {
     "allow_variations": true,
     "hidden": true
   },
   "type": "color",
   "value_type": "list",
   "values": [
     {
       "id": "52049",
       "name": "Negro",
       "metadata": {
         "rgb": "000000"
       }
     },
     {
       "id": "51993",
       "name": "Rojo",
       "metadata": {
         "rgb": "FF0000"
       }
     },
     {
       "id": "52035",
       "name": "Violeta",
       "metadata": {
         "rgb": "9F00FF"
       }
     },
     {
       "id": "52028",
       "name": "Azul",
       "metadata": {
         "rgb": "1717FF"
       }
     },
     {
       "id": "52005",
       "name": "Marrón",
       "metadata": {
         "rgb": "A0522D"
       }
     },
     {
       "id": "52051",
       "name": "Gris oscuro",
       "metadata": {
         "rgb": "666666"
       }
     },
     {
       "id": "52000",
       "name": "Naranja",
       "metadata": {
         "rgb": "FF8C00"
       }
     },
     {
       "id": "52014",
       "name": "Verde",
       "metadata": {
         "rgb": "0DA600"
       }
     },
     {
       "id": "51994",
       "name": "Rosa",
       "metadata": {
         "rgb": "FCB1BE"
       }
     },
     {
       "id": "283164",
       "name": "Dorado",
       "metadata": {
         "rgb": "FFD700"
       }
     },
     {
       "id": "52007",
       "name": "Amarillo",
       "metadata": {
         "rgb": "FFED00"
       }
     },
     {
       "id": "52053",
       "name": "Plateado",
       "metadata": {
         "rgb": "CBCFD0"
       }
     },
     {
       "id": "283165",
       "name": "Gris claro",
       "metadata": {
         "rgb": "E1E1E1"
       }
     },
     {
       "id": "52021",
       "name": "Celeste",
       "metadata": {
         "rgb": "83DDFF"
       }
     },
     {
       "id": "52055",
       "name": "Blanco",
       "metadata": {
         "rgb": "FFFFFF"
       }
     },
     {
       "id": "51998",
       "name": "Bordó",
       "metadata": {
         "rgb": "830500",
         "parent_id": "51993"
       }
     },
     {
       "id": "51996",
       "name": "Terracota",
       "metadata": {
         "rgb": "C63633",
         "parent_id": "51993"
       }
     },
     {
       "id": "283149",
       "name": "Coral",
       "metadata": {
         "rgb": "FA8072",
         "parent_id": "51993"
       }
     },
     {
       "id": "283148",
       "name": "Coral claro",
       "metadata": {
         "rgb": "F9AC95",
         "parent_id": "51993"
       }
     },
     {
       "id": "52047",
       "name": "Violeta oscuro",
       "metadata": {
         "rgb": "4E0087",
         "parent_id": "52035"
       }
     },
     {
       "id": "283162",
       "name": "Índigo",
       "metadata": {
         "rgb": "7A64C6",
         "parent_id": "52035"
       }
     },
     {
       "id": "52038",
       "name": "Lila",
       "metadata": {
         "rgb": "CC87FF",
         "parent_id": "52035"
       }
     },
     {
       "id": "52036",
       "name": "Lavanda",
       "metadata": {
         "rgb": "D9D2E9",
         "parent_id": "52035"
       }
     },
     {
       "id": "52033",
       "name": "Azul oscuro",
       "metadata": {
         "rgb": "013267",
         "parent_id": "52028"
       }
     },
     {
       "id": "283161",
       "name": "Azul marino",
       "metadata": {
         "rgb": "0F5299",
         "parent_id": "52028"
       }
     },
     {
       "id": "52031",
       "name": "Azul acero",
       "metadata": {
         "rgb": "6FA8DC",
         "parent_id": "52028"
       }
     },
     {
       "id": "52029",
       "name": "Azul claro",
       "metadata": {
         "rgb": "DCECFF",
         "parent_id": "52028"
       }
     },
     {
       "id": "283155",
       "name": "Marrón oscuro",
       "metadata": {
         "rgb": "5D3806",
         "parent_id": "52005"
       }
     },
     {
       "id": "283154",
       "name": "Marrón claro",
       "metadata": {
         "rgb": "AF8650",
         "parent_id": "52005"
       }
     },
     {
       "id": "283153",
       "name": "Suela",
       "metadata": {
         "rgb": "FAEBD7",
         "parent_id": "52005"
       }
     },
     {
       "id": "52001",
       "name": "Beige",
       "metadata": {
         "rgb": "F5F3DC",
         "parent_id": "52005"
       }
     },
     {
       "id": "283152",
       "name": "Chocolate",
       "metadata": {
         "rgb": "9B3F14",
         "parent_id": "52000"
       }
     },
     {
       "id": "283151",
       "name": "Naranja oscuro",
       "metadata": {
         "rgb": "D2691E",
         "parent_id": "52000"
       }
     },
     {
       "id": "283150",
       "name": "Naranja claro",
       "metadata": {
         "rgb": "FDAF20",
         "parent_id": "52000"
       }
     },
     {
       "id": "52003",
       "name": "Piel",
       "metadata": {
         "rgb": "FFE4C4",
         "parent_id": "52000"
       }
     },
     {
       "id": "52019",
       "name": "Verde oscuro",
       "metadata": {
         "rgb": "003D00",
         "parent_id": "52014"
       }
     },
     {
       "id": "283158",
       "name": "Verde musgo",
       "metadata": {
         "rgb": "3F7600",
         "parent_id": "52014"
       }
     },
     {
       "id": "283157",
       "name": "Verde limón",
       "metadata": {
         "rgb": "73E129",
         "parent_id": "52014"
       }
     },
     {
       "id": "52015",
       "name": "Verde claro",
       "metadata": {
         "rgb": "9FF39F",
         "parent_id": "52014"
       }
     },
     {
       "id": "52042",
       "name": "Fucsia",
       "metadata": {
         "rgb": "FF00EC",
         "parent_id": "51994"
       }
     },
     {
       "id": "283163",
       "name": "Rosa chicle",
       "metadata": {
         "rgb": "FF51A8",
         "parent_id": "51994"
       }
     },
     {
       "id": "52045",
       "name": "Rosa pálido",
       "metadata": {
         "rgb": "D06EA8",
         "parent_id": "51994"
       }
     },
     {
       "id": "52043",
       "name": "Rosa claro",
       "metadata": {
         "rgb": "FADBE2",
         "parent_id": "51994"
       }
     },
     {
       "id": "52012",
       "name": "Dorado oscuro",
       "metadata": {
         "rgb": "BF9000",
         "parent_id": "52007"
       }
     },
     {
       "id": "52010",
       "name": "Ocre",
       "metadata": {
         "rgb": "EACB53",
         "parent_id": "52007"
       }
     },
     {
       "id": "283156",
       "name": "Caqui",
       "metadata": {
         "rgb": "F0E68C",
         "parent_id": "52007"
       }
     },
     {
       "id": "52008",
       "name": "Crema",
       "metadata": {
         "rgb": "FFFFE0",
         "parent_id": "52007"
       }
     },
     {
       "id": "52024",
       "name": "Azul petróleo",
       "metadata": {
         "rgb": "1E6E7F",
         "parent_id": "52021"
       }
     },
     {
       "id": "283160",
       "name": "Turquesa",
       "metadata": {
         "rgb": "40E0D0",
         "parent_id": "52021"
       }
     },
     {
       "id": "52022",
       "name": "Agua",
       "metadata": {
         "rgb": "E0FFFF",
         "parent_id": "52021"
       }
     },
     {
       "id": "283159",
       "name": "Cyan",
       "metadata": {
         "rgb": "00FFFF",
         "parent_id": "52021"
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "WIRELESS_RANGE",
   "name": "Alcance Inalámbrico",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "km",
       "name": "km"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     }
   ],
   "default_unit": "cm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_HEIGHT",
   "name": "Altura del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_WIDTH",
   "name": "Ancho del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "BLUETOOTH",
   "name": "Bluetooth",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "BATTERY_LIFE",
   "name": "Duración de la Batería",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "h",
       "name": "h"
     },
     {
       "id": "años",
       "name": "años"
     },
     {
       "id": "d",
       "name": "d"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "meses",
       "name": "meses"
     },
     {
       "id": "ms",
       "name": "ms"
     },
     {
       "id": "s",
       "name": "s"
     }
   ],
   "default_unit": "h",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "EAN",
   "name": "EAN",
   "tags": {
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "GTIN",
   "name": "GTIN",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "IMPEDANCE",
   "name": "Impedancia",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "ω",
       "name": "ω"
     }
   ],
   "default_unit": "ω",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "JAN",
   "name": "JAN",
   "tags": {
     "hidden": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "LINE",
   "name": "Línea",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "CABLE_LENGTH",
   "name": "Longitud del Cable",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "km",
       "name": "km"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     }
   ],
   "default_unit": "cm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_LENGTH",
   "name": "Longitud del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MICROPHONE_INCLUDED",
   "name": "Micrófono Incluido",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MODEL",
   "name": "Modelo",
   "tags": {
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "MAIN",
   "attribute_group_name": "Atributos Principales"
 },
 {
   "id": "ALPHANUMERIC_MODEL",
   "name": "Modelo Alfanumérico",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "DETAILED_MODEL",
   "name": "Modelo Detallado",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MPN",
   "name": "MPN",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_WEIGHT",
   "name": "Peso del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mcg",
       "name": "mcg"
     },
     {
       "id": "mg",
       "name": "mg"
     },
     {
       "id": "g",
       "name": "g"
     },
     {
       "id": "oz",
       "name": "oz"
     },
     {
       "id": "lb",
       "name": "lb"
     },
     {
       "id": "kg",
       "name": "kg"
     }
   ],
   "default_unit": "mcg",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "WIRELESS_CAPABILITY",
   "name": "Recepción Inalámbrica",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "FREQUENCY_RESPONSE",
   "name": "Respuesta en Frecuencia",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "SENSITIVITY",
   "name": "Sensibilidad",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "db",
       "name": "db"
     }
   ],
   "default_unit": "db",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MEMORY_SIZE",
   "name": "Tamaño Efectivo de Memoria",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "gb",
       "name": "gb"
     },
     {
       "id": "gib",
       "name": "gib"
     },
     {
       "id": "kb",
       "name": "kb"
     },
     {
       "id": "kib",
       "name": "kib"
     },
     {
       "id": "mb",
       "name": "mb"
     },
     {
       "id": "mib",
       "name": "mib"
     },
     {
       "id": "tb",
       "name": "tb"
     },
     {
       "id": "tib",
       "name": "tib"
     }
   ],
   "default_unit": "gb",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "HEADPHONES_TYPE",
   "name": "Tipo",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "TYPE_COUPLING",
   "name": "Tipo de Acoplamiento",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "suggested_values": [
     {
       "id": "114209",
       "name": "Supraaural"
     },
     {
       "id": "114210",
       "name": "Intraural"
     },
     {
       "id": "114208",
       "name": "Circumaural"
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "DIAPHRAGM_UNIT",
   "name": "Unidad de Diafragma",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "km",
       "name": "km"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "UPC",
   "name": "UPC",
   "tags": {
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 }
]

Types of possible attributes

There are different types of attributes, so the values to be supported will depend on them. Types of attributes can be viewed by entering the attribute API of the relevant category and querying the value_type field.

The possible types are:

string

You can complete this type of attributes with free text, including letters and numbers indistinctively.
Example

Considerations: for this attributes, there is a list of suggested values, but you can also enter new ones which are not included in such list. For new values, you should only send us the name, but for known values, you can send us the id as the name. We encourage you to see the suggested values in the API!

number

These attributes can be only completed with numeric values.
Example

Considerations: for this attributes, there is a list of suggested values, but you can also enter new ones which are not included in such list. For new values, you should only send us the name, but for known values, you can send us the id as the name. We encourage you to see the suggested values in the API!

number_unit

Attributes made up of a numeric value and a unit. You can view the units available for such attributes in the attribute API.
Example

Notes:

  • He format of these attributes will be validated when making or changing a listing, that is, checking that the above described format is followed.
  • For all the above types of attributes, the value_max_length field shows the maximum number of characters to be uploaded in attribute value.

boolean

It only allows for two values: one corresponding to a positive value and the other corresponding to a negative one.
Example

Considerations: you should send the value id, which you can query in the attribute API.

list

The values property lists the possible values which this attribute may take -there should always be, at least, one.
Example

Considerations: if you want to upload a value that is not on the list, you can send your custom value in value_name, with the value_id of the value that is closest to yours. For example, if you are selling a mobile Air Conditioner, but the PRODUCT_TYPE attribute value does not exactly represent your item, you can use the value_id of the Portable value, but send mobile in value_name.

Special behaviors

The tags property specifies particular attribute behaviors. Find below a list of the possible values that may be included, along with a behavior description.

  • allow_variations: this attribute allows for item variations. To learn more about how to add them, please see the Variations documentation.
  • defines_picture: it shows that the attribute defines the picture. For example, Color for shoes. The use of this tag will show how to display the different components in the flows.
    Take into account that this behavior applies only to attributes that allow for variations.
  • fixed: it shows that there is a fixed value for the category and all the items listed under this section should have such value.
    For example, if you are selling a Microwave Oven in category MLB232411 corresponding to Microwave Ovens -> Other Brands -> 18 Liters, such category includes theVOLUMEN_CAPACITY attribute with values 18 Liters, 20 Liters, etc., but for such category, we already know that 18 Liters is the proper value; so you do not need to send it when listing because we autocomplete it for you.
  • hidden: attributes with this property are not shown in the sell flow, but they can be uploaded via the API.
  • inferred: it shows that there is an inferred value for the attribute. Such value cannot be changed. For example, in iPhone category, under mobile phones, the LINE attribute with iPhone value is fixed, and it is inferred that the brand is Apple.
  • multivalued: attributes can be completed with more than one value, separated by commas.
  • others: this tag is for internal use.
  • product_pk: this tag is used to recognize the attributes that are part of a product pk. From this, you can identify a catalog product univocally.
  • read_only: this tag is for internal use. Attributes with this tag cannot be uploaded or changed by the sellers.
  • required: to list the item, the attribute should be completed.
  • restricted_values: this tag is for internal use.
  • variation_attribute: if the item allows for variations, this attribute can be listed with a different value for each variation. For example, in any electronics listing with variations by color, product identifier codes can be uploaded for each variation. A value for this attribute can also be uploaded if the item does not have any variation.

Exclusions and implications of behaviors

Matrix of exclusions
Required

FixedAllow_variationsVariation_attributeDefines_PictureHidden
Required

X

Fixed

X

X

X

Allow_variations

X

X

Variation_attribute

X

X

X

Defines_Picture

X

X

Hidden

X

Matrix of implications
Required

FixedAllow_variationsVariation_attributeDefines_PictureHidden
Required

Fixed

Allow_variations

Variation_attribute

Defines_Picture

X

Hidden

Attributes by category in each country

When you enter, first choose L1 category, so that you can use the browser to find the category about which you want to query attributes.
We encourage you to do generic searches, such as Mobile Phones and Microwave Ovens, instead of Samsung S7 or Philips.
You will also be able to see both the available attributes and the special behaviors defined for them.

To query the attributes available in each country, visit the links below:

Explanatory Note: Each Mercado Libre website is made up of a large category tree. To refer to a category you can use the L (level) terminology, followed by the tree level where it is, e.g., L1, L2, etc.

Benefit

Item information will be more comprehensive and relevant, with attributes displayed in a VIP data sheet to avoid questions and friction.

To validate which attributes will be displayed in the item technical sheet, you can make a query as follows.

Call

https://api.mercadolibre.com/categories/category_ID/technical_specifications

Example

https://api.mercadolibre.com/categories/MLA321250/technical_specifications

Response

{
  "table": {
    "sections": [
      {
        "name": "Características Principales",
        "attributes": [
          {
            "id": "BRAND"
          },
          {
            "id": "MATERIAL"
          },
          {
            "id": "MODEL"
          },
          {
            "id": "MAXIMUM_POWER"
          },
          {
            "id": "HEATING_TECHNOLOGY"
          },
          {
            "id": "HEATER_MOUNT_TYPE"
          }
        ]
      }
    ]
  }
}

Create an item with attributes

Imagine that you want to sell a Microwave Oven about which you know brand, model, and capacity. First, you should select the category in which you want to list it and, then, you should query the attributes for such category:

https://api.mercadolibre.com/categories/MLA125703/attributes
[
 {
   "id": "BRAND",
   "name": "Marca",
   "tags": {
     "fixed": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "values": [
     {
       "id": "5601",
       "name": "BGH"
     }
   ],
   "attribute_group_id": "MAIN",
   "attribute_group_name": "Atributos Principales"
 },
 {
   "id": "COLOR",
   "name": "Color",
   "tags": {
     "allow_variations": true,
     "hidden": true
   },
   "type": "color",
   "value_type": "list",
   "values": [
     {
       "id": "52049",
       "name": "Negro",
       "metadata": {
         "rgb": "000000"
       }
     },
     {
       "id": "51993",
       "name": "Rojo",
       "metadata": {
         "rgb": "FF0000"
       }
     },
     {
       "id": "52035",
       "name": "Violeta",
       "metadata": {
         "rgb": "9F00FF"
       }
     },
     {
       "id": "52028",
       "name": "Azul",
       "metadata": {
         "rgb": "1717FF"
       }
     },
     {
       "id": "52005",
       "name": "Marrón",
       "metadata": {
         "rgb": "A0522D"
       }
     },
     {
       "id": "52051",
       "name": "Gris oscuro",
       "metadata": {
         "rgb": "666666"
       }
     },
     {
       "id": "52000",
       "name": "Naranja",
       "metadata": {
         "rgb": "FF8C00"
       }
     },
     {
       "id": "52014",
       "name": "Verde",
       "metadata": {
         "rgb": "0DA600"
       }
     },
     {
       "id": "51994",
       "name": "Rosa",
       "metadata": {
         "rgb": "FCB1BE"
       }
     },
     {
       "id": "283164",
       "name": "Dorado",
       "metadata": {
         "rgb": "FFD700"
       }
     },
     {
       "id": "52007",
       "name": "Amarillo",
       "metadata": {
         "rgb": "FFED00"
       }
     },
     {
       "id": "52053",
       "name": "Plateado",
       "metadata": {
         "rgb": "CBCFD0"
       }
     },
     {
       "id": "283165",
       "name": "Gris claro",
       "metadata": {
         "rgb": "E1E1E1"
       }
     },
     {
       "id": "52021",
       "name": "Celeste",
       "metadata": {
         "rgb": "83DDFF"
       }
     },
     {
       "id": "52055",
       "name": "Blanco",
       "metadata": {
         "rgb": "FFFFFF"
       }
     },
     {
       "id": "51998",
       "name": "Bordó",
       "metadata": {
         "rgb": "830500",
         "parent_id": "51993"
       }
     },
     {
       "id": "51996",
       "name": "Terracota",
       "metadata": {
         "rgb": "C63633",
         "parent_id": "51993"
       }
     },
     {
       "id": "283149",
       "name": "Coral",
       "metadata": {
         "rgb": "FA8072",
         "parent_id": "51993"
       }
     },
     {
       "id": "283148",
       "name": "Coral claro",
       "metadata": {
         "rgb": "F9AC95",
         "parent_id": "51993"
       }
     },
     {
       "id": "52047",
       "name": "Violeta oscuro",
       "metadata": {
         "rgb": "4E0087",
         "parent_id": "52035"
       }
     },
     {
       "id": "283162",
       "name": "Índigo",
       "metadata": {
         "rgb": "7A64C6",
         "parent_id": "52035"
       }
     },
     {
       "id": "52038",
       "name": "Lila",
       "metadata": {
         "rgb": "CC87FF",
         "parent_id": "52035"
       }
     },
     {
       "id": "52036",
       "name": "Lavanda",
       "metadata": {
         "rgb": "D9D2E9",
         "parent_id": "52035"
       }
     },
     {
       "id": "52033",
       "name": "Azul oscuro",
       "metadata": {
         "rgb": "013267",
         "parent_id": "52028"
       }
     },
     {
       "id": "283161",
       "name": "Azul marino",
       "metadata": {
         "rgb": "0F5299",
         "parent_id": "52028"
       }
     },
     {
       "id": "52031",
       "name": "Azul acero",
       "metadata": {
         "rgb": "6FA8DC",
         "parent_id": "52028"
       }
     },
     {
       "id": "52029",
       "name": "Azul claro",
       "metadata": {
         "rgb": "DCECFF",
         "parent_id": "52028"
       }
     },
     {
       "id": "283155",
       "name": "Marrón oscuro",
       "metadata": {
         "rgb": "5D3806",
         "parent_id": "52005"
       }
     },
     {
       "id": "283154",
       "name": "Marrón claro",
       "metadata": {
         "rgb": "AF8650",
         "parent_id": "52005"
       }
     },
     {
       "id": "283153",
       "name": "Suela",
       "metadata": {
         "rgb": "FAEBD7",
         "parent_id": "52005"
       }
     },
     {
       "id": "52001",
       "name": "Beige",
       "metadata": {
         "rgb": "F5F3DC",
         "parent_id": "52005"
       }
     },
     {
       "id": "283152",
       "name": "Chocolate",
       "metadata": {
         "rgb": "9B3F14",
         "parent_id": "52000"
       }
     },
     {
       "id": "283151",
       "name": "Naranja oscuro",
       "metadata": {
         "rgb": "D2691E",
         "parent_id": "52000"
       }
     },
     {
       "id": "283150",
       "name": "Naranja claro",
       "metadata": {
         "rgb": "FDAF20",
         "parent_id": "52000"
       }
     },
     {
       "id": "52003",
       "name": "Piel",
       "metadata": {
         "rgb": "FFE4C4",
         "parent_id": "52000"
       }
     },
     {
       "id": "52019",
       "name": "Verde oscuro",
       "metadata": {
         "rgb": "003D00",
         "parent_id": "52014"
       }
     },
     {
       "id": "283158",
       "name": "Verde musgo",
       "metadata": {
         "rgb": "3F7600",
         "parent_id": "52014"
       }
     },
     {
       "id": "283157",
       "name": "Verde limón",
       "metadata": {
         "rgb": "73E129",
         "parent_id": "52014"
       }
     },
     {
       "id": "52015",
       "name": "Verde claro",
       "metadata": {
         "rgb": "9FF39F",
         "parent_id": "52014"
       }
     },
     {
       "id": "52042",
       "name": "Fucsia",
       "metadata": {
         "rgb": "FF00EC",
         "parent_id": "51994"
       }
     },
     {
       "id": "283163",
       "name": "Rosa chicle",
       "metadata": {
         "rgb": "FF51A8",
         "parent_id": "51994"
       }
     },
     {
       "id": "52045",
       "name": "Rosa pálido",
       "metadata": {
         "rgb": "D06EA8",
         "parent_id": "51994"
       }
     },
     {
       "id": "52043",
       "name": "Rosa claro",
       "metadata": {
         "rgb": "FADBE2",
         "parent_id": "51994"
       }
     },
     {
       "id": "52012",
       "name": "Dorado oscuro",
       "metadata": {
         "rgb": "BF9000",
         "parent_id": "52007"
       }
     },
     {
       "id": "52010",
       "name": "Ocre",
       "metadata": {
         "rgb": "EACB53",
         "parent_id": "52007"
       }
     },
     {
       "id": "283156",
       "name": "Caqui",
       "metadata": {
         "rgb": "F0E68C",
         "parent_id": "52007"
       }
     },
     {
       "id": "52008",
       "name": "Crema",
       "metadata": {
         "rgb": "FFFFE0",
         "parent_id": "52007"
       }
     },
     {
       "id": "52024",
       "name": "Azul petróleo",
       "metadata": {
         "rgb": "1E6E7F",
         "parent_id": "52021"
       }
     },
     {
       "id": "283160",
       "name": "Turquesa",
       "metadata": {
         "rgb": "40E0D0",
         "parent_id": "52021"
       }
     },
     {
       "id": "52022",
       "name": "Agua",
       "metadata": {
         "rgb": "E0FFFF",
         "parent_id": "52021"
       }
     },
     {
       "id": "283159",
       "name": "Cyan",
       "metadata": {
         "rgb": "00FFFF",
         "parent_id": "52021"
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_HEIGHT",
   "name": "Altura del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_WIDTH",
   "name": "Ancho del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "TURNTABLE",
   "name": "Bandeja Giratoria",
   "tags": {
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "NUMBER_OF_PROGRAMS",
   "name": "Cantidad de Programas",
   "tags": {
     "hidden": true
   },
   "value_type": "number",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "VOLUME_CAPACITY",
   "name": "Capacidad",
   "tags": {
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "l",
       "name": "l"
     },
     {
       "id": "cc",
       "name": "cc"
     },
     {
       "id": "ft³",
       "name": "ft³"
     },
     {
       "id": "ml",
       "name": "ml"
     },
     {
       "id": "mm³",
       "name": "mm³"
     }
   ],
   "default_unit": "l",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "CONVECTION",
   "name": "Convección",
   "tags": {
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "TURNTABLE_DIAMETER",
   "name": "Diámetro de Bandeja Giratoria",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "km",
       "name": "km"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "EAN",
   "name": "EAN",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "FREQUENCY",
   "name": "Frecuencia",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "hz",
       "name": "hz"
     },
     {
       "id": "ghz",
       "name": "ghz"
     },
     {
       "id": "khz",
       "name": "khz"
     },
     {
       "id": "mhz",
       "name": "mhz"
     },
     {
       "id": "rpm",
       "name": "rpm"
     }
   ],
   "default_unit": "hz",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MICROWAVE_FUNCTIONS",
   "name": "Funciones",
   "tags": {
     "hidden": true,
     "multivalued": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "GRILL",
   "name": "Grill",
   "tags": {
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "GTIN",
   "name": "GTIN",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "JAN",
   "name": "JAN",
   "tags": {
     "hidden": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "LINE",
   "name": "Línea",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_LENGTH",
   "name": "Longitud del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mm",
       "name": "mm"
     },
     {
       "id": "cm",
       "name": "cm"
     },
     {
       "id": "in",
       "name": "in"
     },
     {
       "id": "pulgadas",
       "name": "pulgadas"
     },
     {
       "id": "ft",
       "name": "ft"
     },
     {
       "id": "m",
       "name": "m"
     },
     {
       "id": "km",
       "name": "km"
     }
   ],
   "default_unit": "mm",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "DIMENSIONS",
   "name": "Medidas",
   "tags": {
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MODEL",
   "name": "Modelo",
   "tags": {
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "MAIN",
   "attribute_group_name": "Atributos Principales"
 },
 {
   "id": "ALPHANUMERIC_MODEL",
   "name": "Modelo Alfanumérico",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "DETAILED_MODEL",
   "name": "Modelo Detallado",
   "tags": {
     "hidden": true
   },
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MPN",
   "name": "MPN",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "POWER_LEVELS",
   "name": "Niveles de Potencia",
   "tags": {
     "hidden": true
   },
   "value_type": "number",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PACKAGE_WEIGHT",
   "name": "Peso del paquete",
   "tags": {
     "hidden": true,
     "read_only": true,
     "variation_attribute": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "mcg",
       "name": "mcg"
     },
     {
       "id": "mg",
       "name": "mg"
     },
     {
       "id": "g",
       "name": "g"
     },
     {
       "id": "oz",
       "name": "oz"
     },
     {
       "id": "lb",
       "name": "lb"
     },
     {
       "id": "kg",
       "name": "kg"
     }
   ],
   "default_unit": "mcg",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "POWER",
   "name": "Potencia",
   "tags": {
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "w",
       "name": "w"
     },
     {
       "id": "btu/h",
       "name": "btu/h"
     },
     {
       "id": "cv",
       "name": "cv"
     },
     {
       "id": "fg",
       "name": "fg"
     },
     {
       "id": "hp",
       "name": "hp"
     },
     {
       "id": "kcal/h",
       "name": "kcal/h"
     },
     {
       "id": "kw",
       "name": "kw"
     },
     {
       "id": "mw",
       "name": "mw"
     },
     {
       "id": "tfr",
       "name": "tfr"
     },
     {
       "id": "va",
       "name": "va"
     }
   ],
   "default_unit": "w",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "GRILL_POWER",
   "name": "Potencia de Grill",
   "tags": {
     "hidden": true
   },
   "value_type": "number_unit",
   "value_max_length": 60,
   "allowed_units": [
     {
       "id": "w",
       "name": "w"
     },
     {
       "id": "btu/h",
       "name": "btu/h"
     },
     {
       "id": "cv",
       "name": "cv"
     },
     {
       "id": "fg",
       "name": "fg"
     },
     {
       "id": "hp",
       "name": "hp"
     },
     {
       "id": "kcal/h",
       "name": "kcal/h"
     },
     {
       "id": "kw",
       "name": "kw"
     },
     {
       "id": "mw",
       "name": "mw"
     },
     {
       "id": "tfr",
       "name": "tfr"
     },
     {
       "id": "va",
       "name": "va"
     }
   ],
   "default_unit": "w",
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MIRRORED_DOOR",
   "name": "Puerta Espejada",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "PROGRAMMABLE_KEYS",
   "name": "Teclas Programables",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "MICROWAVE_TYPE",
   "name": "Tipo",
   "tags": {
   },
   "value_type": "list",
   "values": [
     {
       "id": "289784",
       "name": "De Apoyo"
     },
     {
       "id": "289785",
       "name": "De Embutir"
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "CHILD_SAFETY_LOCK",
   "name": "Traba de Seguridad para Niños",
   "tags": {
     "hidden": true
   },
   "value_type": "boolean",
   "values": [
     {
       "id": "242084",
       "name": "No",
       "metadata": {
         "value": false
       }
     },
     {
       "id": "242085",
       "name": "Sí",
       "metadata": {
         "value": true
       }
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "UPC",
   "name": "UPC",
   "tags": {
     "hidden": true,
     "multivalued": true,
     "variation_attribute": true
   },
   "type": "product_identifier",
   "value_type": "string",
   "value_max_length": 60,
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 },
 {
   "id": "VOLTAGE",
   "name": "Voltaje",
   "tags": {
     "hidden": true
   },
   "value_type": "list",
   "values": [
     {
       "id": "198812",
       "name": "110V / 220V"
     },
     {
       "id": "198813",
       "name": "220V"
     },
     {
       "id": "198814",
       "name": "110V"
     }
   ],
   "attribute_group_id": "DFLT",
   "attribute_group_name": "Otros"
 }
]

In this example, you can see that the BRAND attribute has a fixed tag for category. This makes sense because, after navigating the tree to find the category under which to list the microwave oven, you have implicitly chosen its brand.
Then, you just need to analyze the available attributes, their types and suggested values to make the listing JSON, including the attributes section.
Find below how to do it:

curl -X POST -H "Content-Type: application/json" -d '{
 "site_id":"MLA",
 "title":"Item de testeo, por favor no contactar --kc:off",
 "category_id":"MLA125703",
 "price":4000,
 "currency_id":"ARS",
 "buying_mode":"buy_it_now",
 "listing_type_id":"gold_special",
 "condition":"new",
 "available_quantity":10,
 "attributes":[
   {
     "id":"MODEL",
     "value_name":"B228D"
   },
   {
     "id":"VOLUME_CAPACITY",
     "value_name":"28 L"
   }
 ]
}' 'https://api.mercadolibre.com/items?access_token={YOUR_ACCESS_TOKEN}'

Notes:

  • Attributes can be added to items at any time during their life cycle.
  • If the attribute has a suggested_values list, you can send either one of those values or a new one. To send new values, you should only send value_name; however, value_id will be enough for the existing values.
  • For list-type attributes, you should only send values included in such list. value_id will be enough. However, if you want to upload a value that is not on the list, you can send your custom value in value_name , with the value_id of the value that is closest to yours.
  • All main attributes are identified as MAIN in the attribute_group_id field, while secondary attributes will be identified with other values, such as: DELT.
  • Bear in mind that in categories with primary and secondary colors, you will not need to replicate both attributes for every variation, on an exception basis. 

Change and/or add attributes

Once the listing is created, you can add new attributes or change the existing ones.
Imagine that you want to change the Microwave Oven Model and add the Number of Programs: you should make a PUT like the one below:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d "{
   "attributes": [{
       "id": "BRAND"
   },{
       "id": "MODEL",
       "value_name": "B466GT"
   }, {
       "id": "VOLUME_CAPACITY"
   }, {
       "id": "NUMBER_OF_PROGRAMS",
       "value_name": "4"
   }]
} "https://api.mercadolibre.com/items/MLA621092868?"access_token={YOUR_ACCESS_TOKEN}"

Note: if you want to change only one attribute, you should send the existing attribute Ids so that you do not lose them.

Delete attributes

To delete an attribute, you should send the list with the Ids of the attributes that you want to keep for that item. The item will be updated, leaving only those as active attributes and deleting the excluded ones.
To do so, use the example below to make a similar call:

curl -H 'Content-Type: application/json' -X PUT https://api.mercadolibre.com/items/MLA658778048?access_token=$ACCESS_TOKEN  -d '{
"attributes": [
   {
     "id": "FAN_TYPE"
   },
   {
     "id": "HEIGHT_ADJUSTABLE"
   },
   {
     "id": "REMOTE_CONTROL"
   },
   {
     "id": "WITH_LIGHT"
   },
   {
     "id": "BRAND"
   }
 ]
}'



Next:
Product identifiers

Please rate this

Official stores

Some selected users are part of MercadoLibre Official Stores, and have one or more brands under the same user. If you want to become part of MercadoLibre Official Stores, you’ll have to communicate with a commercial adviser. If you’re part of Official Stores already, follow this tutorial to learn the basic of how to work with this user type.

Contents:

Obtain your brands Ids

This resource retrieves brands associated to an user_id. There can be more than one per user. The official_store_id attribute identifies a store.
Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/brands

Response:

{
  "cust_id": 12345678,
  "tags": [
	"large_seller",
	"user_info_verified",
	"brand"
  ],
  "brands": [
	{
  	"tags": [
    	"girls",
    	"female"
  	],
  	"official_store_id": 16,
  	"categories_ids": [
    	"MLA1430"
  	],
  	"fantasy_name": "47 Street",
  	"site_id": "MLA",
  	"status": "active",
  	"name": "47 Street",
  	"pictures": [
    	{
      	"id": 104,
      	"name": "big_logo",
      	"secure_url": null,
      	"url": "http://static.mlstatic.com/org-img/apparel/images/47street/149254178-logo-g2.jpg",
      	"size": "174x164"
    	},
    	{},
    	{},
    	{},
    	{},
    	{}
  	],
  	"relevance_position": 50
	},
	{},
	{},
	{},
	{}
  ],
  "site_id": "MLA",
  "user_type": "brand"
}

Obtain all information about a specific brand

To get information about a specific brand, you can make the call to the brand_id you want to know about like in the example that follows:
Example:

curl -X GET https://api.mercadolibre.com/users/58715193/brands/133

Response:

{
  "tags": [
	"home",
	"standout"
  ],
  "official_store_id": 133,
  "categories_ids": [
	"MLA1403"
  ],
  "fantasy_name": "Bodega Lanzarini",
  "users": [
	{
  	"cust_id": 58715193,
  	"tags": [
    	"eshop",
    	"large_seller",
    	"user_info_verified",
    	"brand"
  	],
  	"site_id": "MLA",
  	"user_type": "brand"
	}
  ],
  "site_id": "MLA",
  "status": "active",
  "name": "Bodega Lanzarini",
  "date_created": "2014-08-04T04:00:00.000Z",
  "pictures": [
	{
  	"id": 632,
  	"name": "big_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-g.jpg",
  	"size": "174x164"
	},
	{
  	"id": 2474,
  	"name": "facebook_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/mla-fb/58715193-logo-fb.jpg",
  	"size": "1600x750"
	},
	{
  	"id": 9428,
      "name": "home_app",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/bkg_apps/58715193-bkg.jpg",
  	"size": "270x155"
	},
	{
  	"id": 634,
  	"name": "logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-home.jpg",
  	"size": "160x80"
	},
	{
      "id": 633,
  	"name": "logo_landing",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-home.jpg",
  	"size": "160x80"
	},
	{
  	"id": 631,
  	"name": "background",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-bkg.jpg",
  	"size": "1600x750"
	},
	{
  	"id": 635,
  	"name": "small_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-ch2.jpg",
  	"size": "96x70"
	}
  ],
  "boost": {
	"is_active": false,
	"last_update": "2015-08-17T20:55:12.000Z"
  },
  "relevance_position": 69
}

Great! You already know the brand_id associated to your user to send every time you want to list an item.

Next topic: Set categories for your products

Please rate this

Application Manager

Get your applications

Call applications resource search with your user_id to get a detail of the applications you own.

Example:


curl -X GET https://api.mercadolibre.com/applications/search?owner_id={Owner_id}?access_token=$ACCESS_TOKEN

Response:

{
    "id": 2342346600929988,
    "site_id": "MLB",
    "name": "ML TEST",
    "description": "ML TEST APP",
    "thumbnail": null,
    "owner_id": 18731523,
    "catalog_product_id": null,
    "item_id": null,
    "price": null,
    "currency_id": null,
    "need_authorization": true,
    "short_name": "polipartes",
    "url": "http://apps.mercadolivre.com.br/polipartes",
    "callback_url": "http://www.vtexml.com.br/",
    "sandbox_mode": true,
    "is_public": true,
    "project_id": null,
    "active": true,
    "max_requests_per_hour": 18000,
    "scopes": [
      "write",
      "read",
      "offline_access"
    ],
    "domains": [
    ]
  }

Get application detail

To get the full detail about one of your apps just include the app_id on the API call.

Example:

curl -X GET https://api.mercadolibre.com/applications/213123928883922

Response:

{
  "id": 213123928883922,
  "site_id": "MLB",
  "name": "ML Test",
  "description": "ML Test APP",
  "thumbnail": null,
  "owner_id": 18731523,
  "catalog_product_id": null,
  "item_id": null,
  "price": null,
  "currency_id": null,
  "need_authorization": true,
  "short_name": "polipartes",
  "url": "http://apps.mercadolivre.com.br/polipartes",
  "callback_url": "http://www.vtexml.com.br/",
  "sandbox_mode": true,
  "is_public": true,
  "project_id": null,
  "active": true,
  "max_requests_per_hour": 18000,
  "scopes": [],
  "domains": [
  ]
}

Get applications authorized by user

To get all the applications authorized by a user just use a GET request with the user_id and the access token.

GET https://api.mercadolibre.com/users/{user_id}/applications?access_token={...}

The response would be an array of applications with the following format:

[
  - {
    "user_id": "26317316",
    "app_id": "13795",
    "date_created": "2012-12-20T15:38:27.000-04:00",
    "scopes": - [
      "read",
      "write",
    ],
   },
]

Fields description

  • user_id – The user identifier.
  • app_id – The application identifier.
  • date_created – Date when the authorization was created.
  • scopes – permissions given to the application: read, write and offline_access.

Revoke user authorization

To remove any application you must specify the application id, the user id, and the access token. Just doing a DELETE request using this query:

DELETE https://api.mercadolibre.com/users/{user_id}/applications/{app_id}?access_token={...}

The response should be:

{
	"user_id":"{user_id}",
	"app_id":"{app_id}",
	"msg":"Autorización eliminada"
}

Please rate this

Free shipping

Sellers using the MercadoEnvíos shipping module, mode 1 or mode 2, are able to list items offering one of the shipping methods for free.
This type of shipping has some benefits: it is a superior shopping experience for the buyer, it is highlighted in the search results, and buyers can filter listings that offer free shipping.
We’ve recently made some changes on the API and the JSON structure of the items adding the possibilities to set ‘Rules’ for the free_shipping option. Brazilian sellers with ME are now able to exclude the North and Northeast regions if they want to when they include free_shipping on their items. This is possible through the ‘exclude_regions’ rule. Other sites can only use the rule ‘country’, which means that if they include free shipping on their items, it applies for the whole country.

Contents:

Shipping modes

curl https://api.mercadolibre.com/users/{user_id}/shipping_modes?category_id={category_id}

This resource will return the shipping configuration available to the seller for a specific category.
Response:

{
"mode": "me2",
 "shipping_attributes": {
   "costs": "not_allowed",
   "dimensions": "clear",
   "free": {
      "methods": "optional",
      "accepted_methods": [100009,182],
      "rules": [{
         "free_mode":"exclude_region",
         "value": [’BR-NO’, ’BR-NE’],
         "default": true,
         "free_shipping_flag": false
      },{
         "free_mode":"country",
         "value": null,
         "default": false,
         "free_shipping_flag": true
      }]
   }
}


Calculate free shipping costs

Sites

Calculate free shipping costs by site & item dimensions
Example:

curl -X GET https://api.mercadolibre.com/sites/MLM/shipping_options/free?dimensions=2x11x25,500

Response:

{
"coverage": {
"all_country": {
"list_cost": 97,
"currency_id": "MXN"
}
}
}


Users & items

On México we offer seller’s a single flat rate option. When dimensions aren’t specified on the item, calculate is done basing on standard category dimensions.

Know standard dimensions for a given category

Example:

curl -X GET https://api.mercadolibre.com/categories/MLM165702/shipping

Response:

{
  "category_id": "MLM1055",
  "height": 10,
  "width": 10,
  "length": 15,
  "weight": 500
}


Calculate free shipping costs by user & item dimensions

Example:

curl -X GET https://api.mercadolibre.com/users/4422224/shipping_options/free?dimensions=10x10x10,500

Response:

{
"coverage": {
"all_country": {
"list_cost": 97,
"currency_id": "MXN"
}
}
}


Calculate free shipping costs by user & item_id

Example:

curl -X GET https://api.mercadolibre.com/users/4422224/shipping_options/free?item_id=MLM531425223
{
"coverage": {
"all_country": {
"list_cost": 97,
"currency_id": "MXN"
}
}
}


Calculate free shipping costs by item

Example:

curl -X GET https://api.mercadolibre.com/items/MLB739217081/shipping_options/free

Response:

{
"coverage": {
"all_country": {
"list_cost": 14.02,
"currency_id": "BRL"
}
}
}

Use multiget to calculate the cost of free shipping up to 50 items on one API call:
Example:

curl -X GET curl -X GET https://api.mercadolibre.com/items/shipping_options/free?ids=MLM531425223,MLM537956425,MLM537955922

Response:

{
"MLM537955922": {
"coverage": {
"all_country": {
"list_cost": 140,
"currency_id": "MXN"
}
}
},
"MLM531425223": {
"coverage": {
"all_country": {
"list_cost": 97,
"currency_id": "MXN"
}
}
},
"MLM537956425": {
"coverage": {
"all_country": {
"list_cost": 105,
"currency_id": "MXN"
}
}
}
}


Products with free shipping

curl https://api.mercadolibre.com/items/{item_id}



On the Item you will see that we’ve replaced the property “methods” for “free_methods” when “free_shipping” is true. Under free_methods you’ll have the method Id and into “rule”.
Under the “rules” section you should specify on “free_mode” whether you want to exclude regions or not. If you set “free_mode”:”exclude_region”, you must send the values, which by now will be ‘BR-NO’ and ‘BR-NE’.
GET Shipping Item

{
   "shipping":{
      "mode":"me2",
      "local_pick_up":true,
      "free_shipping":true,
      "free_methods":[
         {
            "id":182,
            "rule":{
                "free_mode":"exclude_region",
                "value":[’BR-NO’, ’BR-NE’]
             }
         },
      ],
      "dimensions":null
   }
}


Note:Even though the benefit by now it’s for MLB, the structure of the JSON will be updated in every country with MercadoEnvíos. We’ll give two months since the activation date to adapt to this changes, which means that the API will be accepting both JSONs during this period until the deadline – two months counting since June 30th – when the original JSON will be no longer valid. Items with the previous configuration will remain the same except for relistings.

Offer free_shipping “country” mode
Example:

{
"title": "Titulo del item",
...
"shipping": {
    "mode": "me2",
    "local_pick_up": false,
    "free_methods": [
        {
            "id": 100009,
            "rule": {
                "free_mode": "country",
                "value": null
            }
        }
    ]
}
}


Offer free_shipping excluding regions

Example:

{
    "shipping": {
        "free_methods": [
            {
                "id": 182,
                "rule": {
                    "free_mode": "exclude_region",
                    "value": [
                        "BR-NO",
                        "BR-NE"
                    ]
                }
            }
        }
    ],
    
}


Offer free_shipping for custom shipping

For countries where Mercado Envíos is active you can add custom shipping free in categories that do not accept ME.

"shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": true,
        "methods": [],
        "costs": []
    }

Please rate this

Custom shipping

When a buyer chooses shipping preferences and gives his shipping address a shipment is created and associated to the order.

A new order feed will be received when the shipment is created and later, if the tracking is informed, each time the package changes its status until it’s delivered.

Contents:

Get shipment details

You can find some basic information about the shipments on the order, but is better if you work with the shipments resource to get all the details. To do this you need to know the shipment_id.

I don’t know the shipment_id

You can get it from the order, within the basic shipment information.

Example:

curl -X GET https://api.mercadolibre.com/orders/:order_id?access_token=

Response:

{
  "id": 123456789,
  "status": "paid",
  "status_detail": null,
  "date_created": "2012-12-18T09:35:07.000-04:00",
  "date_closed": "2012-12-18T09:35:07.000-04:00",
  "order_items":  [
 	{
  	"item":  {
    	"id": "MLB446311775",
    	"title": "Capa Couro Flip Original Samsung Galaxy S3 Siii  Branca",
    	"variation_id": null,
    	"variation_attributes": [
    	],
  	},
  	"quantity": 1,
  	"unit_price": 99.98,
  	"currency_id": "BRL",
	},
  ],
  "total_amount": 99.98,
  "currency_id": "BRL",
  "buyer":  {
	"id": "123456565",
	"nickname": "BUYER NICKNAME",
	"email": "email@buyer.com",
	"phone":  {
  	"area_code": "11",
  	"number": "55565656",
  	"extension": null,
	},
	"first_name": "Name",
	"last_name": "Last Name",
	"billing_info": - {
  	"doc_type": "CPF",
  	"doc_number": "123456789",
	},
  },
  "seller":  {
	"id": "123456",
	"nickname": "SELLER NICKNAME",
	"email": "email@seller.com",
	"phone": - {
  	"area_code": null,
  	"number": "011 4444 1234",
  	"extension": null,
	},
	"first_name": "Name.",
	"last_name": "Last Name LTDA.",
  },
  "payments":  [
	- {
  	"id": "459656119",
  	"transaction_amount": 99.98,
  	"currency_id": "BRL",
  	"status": "approved",
  	"date_created": null,
  	"date_last_modified": null,
	},
  ],
  "feedback":  {
	"purchase": null,
	"sale": null,
  },
  "shipping":  {
	"id": 20176304039,
	"status": "pending",
	"date_created": "2012-12-18T09:37:35.000-04:00",
	"receiver_address":  {
  	"id": 123456789,
  	"address_line": "Rua Júlio Sérgio de Castro 262 0  ",
  	"zip_code": "223232",
  	"city": - {
    	"id": "BR-SP-44",
    	"name": "São Paulo",
  	},
  	"state":  {
    	"id": "BR-SP",
    	"name": "São Paulo",
  	},
  	"country": - {
    	"id": "BR",
    	"name": "Brasil",
  	},
  	"latitude": null,
  	"longitude": null,
  	"comment": null,
	},
	"currency_id": "BRL",
	"cost": 5.9,
  },
  "tags":  [
	"paid",
	"not_delivered",
  ],
}



To get the complete details of a shipment (status detail, date created, shipping options such as shipping speed and more) just make a mixed call between orders and shipments like this:

Call:

https://api.mercadolibre.com/orders/:order_id/shipments?access_token=


I already know the shipment_id

If you have the id already just call the shipments resources:

curl -X GET https://api.mercadolibre.com/shipments/:shipment_id?access_token=

Example:

{
  "id": 12345678,
  "status": "active",
  "status_history":  {
	"date_shipped": null,
	"date_delivered": null,
  },
  "date_created": "2011-09-07T13:29:42.000-04:00",
  "last_updated": "2011-09-07T13:30:29.000-04:00",
  "tracking_number": null,
  "tracking_method_id":182,
  "tracking_method": null,
  "sender_id": "99580221",
  "receiver_id": "8408542",
  "sender_address":  {
	"id": "53742741",
	"address_line": "Rua X",
	"comment": null,
	"zip_code": "01154020",
	"city":  {
  	"id": "null",
  	"name": "Sao Paulo",
	},
	"state":  {
  	"id": "BR-SP",
  	"name": "Sao Paulo",
	},
    "country":  {
  	"id": "BR",
  	"name": "Brasil",
	},
	"types":  [
      "default_selling_address",
	],
	"latitude": null,
	"longitude": null,
  },
  "receiver_address":  {
	"id": "12181995",
	"address_line": "Estrada Geral Cachoeira de Fátima 77777",
	"comment": null,
	"zip_code": "88990000",
	"city":  {
  	"id": "null",
  	"name": "Praia Grande",
	},
	"state":  {
  	"id": "BR-SC",
  	"name": "Santa Catarina",
	},
	"country":  {
  	"id": "BR",
  	"name": "Brasil",
	},
	"types":  [
  	"default_buying_address",
	],
	"latitude": null,
	"longitude": null,
  },
  "shipping_items":  [
 	{
  	"id": "MLB402220356",
  	"description": "Celular Apple Iphone 4 16gb Libre De Fábrica ",
  	"quantity": 49,
  	"dimensions": “15x15x25,500”,
	},
  ],
  "shipping_option":  {
	"id": 18309457,
	"name": "Express",
	"currency_id": "BRL",
	"cost": 1,
	"speed":{
  	"shipping": 48,
  	"handling": 24
	},
  "comments": "other info shipping",
  }


Offering custom shipping on your products

All you’ll have to do is make a POST with the JSON to the Item’s API. The JSON must include the ‘costs’ for the custom shipping mode with the parameters description and cost specified.

curl -X POST -H "Content-Type: application/json" -d
JSON
{
	"title": "Anteojos Ray Ban Wayfare",
	"category_id": "MLA3636",
	"price": 10,
	"currency_id": "ARS",
	"available_quantity": 1,
	"buying_mode": "buy_it_now",
	"listing_type_id": "bronze",
	"condition": "new",
	"description": "Item:,  Ray-Ban WAYFARER Gloss Black RB2140 901  Model: RB2140. Size: 50mm. Name:	WAYFARER. Color: Gloss Black. Includes Ray-Ban Carrying Case and Cleaning Cloth. New in Box",
	"video_id": "YOUTUBE_ID_HERE",
	"warranty": "12 months by Ray Ban",
	"pictures": [
    	{
        	"source": "http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
    	}
	],
	"shipping": {
    	"mode": "custom",
    	"local_pick_up": false,
    	"free_shipping": false,
    	"methods": [],
    	"costs": [
        	{
            	"description": "TEST1",
            	"cost": "70"
        	},
  	      {
            	"description": "TEST2 ",
            	"cost": "80"
        	}
    	]
	}
}
https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN

Once created a item wiht custom shipping and configured shipping cost table will be see in shipping options.
Call:

https://api.mercadolibre.com/items/item_id/shipping_options



NOTE: For countries where Mercado Envios is active only is possible offer free_shipping custom in categories that do not accept ME.


Adding custom shipping on a listing

You can also add custom shipping mode on an item with not_specified shipping method.
The item shouldn’t have sales in order to be able to modify shipping.
It’s very simple. Make a PUT to the Item’s API including the Item_ID and send a JSON similar to the one below.

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
JSON
{
"shipping": {
	"mode": "custom",
	"methods": [],
	"costs": [
    	{
        	"description": "TEST1",
        	"cost": "70"
    	},
    	{
        	"description": "TEST2 ",
        	"cost": "80"
	    }
	]
}
}

https://api.mercadolibre.com/items/{item_id}?access_token=$ACCESS_TOKEN



This mode also accepts a tracking_number, but the code wont be monitored by us.

Add tracking number

Before including the tracking number you need to know the shipment_id. You can find it by making a call to orders resource like this:
Call:

curl curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d‘{
  "tracking_number": "TR1234567891",
  "status": "shipped"
}’ https://api.mercadolibre.com/shipments/:shipment_id?access_token=


Consideraciones

Product delivery (only available for Mexico and Brasil)

With the following resource, you can inform buyers of their product delivery status when using Mercado Envío.
Begin to use it under the following scenarios:

Scenario 1

When the order has a Custom Shipping created and the status is “pending”:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d 
JSON
{
    "speed"= 120,
    "status"="shipped",
    "tracking_number"=000000001234,
    "receiver_id"=12345678
}
https://api.mercadolibre.com/shipments/{shipping_id}?access_token=$ACCESS_TOKEN

Explanatory Note:

  • The speed field represents the hours it will take for the product to be delivered.
  • The promised delivery date will be the number of hours indicated in the “speed” field, as from the day this value is set.
  • The tracking_number field is mandatory for the API, but no for any sale list and/or description.

Scenario 2

When the order has a Custom Shipping created and the status is “shipped”:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d 
JSON
{
    "speed"= 120,
    "receiver_id"=12345678
}
https://api.mercadolibre.com/shipments/{shipping_id}?access_token=$ACCESS_TOKEN

Explanatory Note:

  • In this case, only the delivery promise is updated, so no tracking_number is required by the API.

Scenario 3

When the order has no shipping:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d 
JSON
{
  "status": "shipped",
  "receiver_id": 12345678,
  "shipping_option": {
      "currency_id": "MXN",
      "cost": 0,
      "speed": 120
  }
}
https://api.mercadolibre.com/orders/{order_id}/shipments?access_token=$ACCESS_TOKEN

Explanatory Note:

  • The speed field should be in the “shipping_options” section. Also, when creating the shipping, a cost should be specified.

Scenario 4

In case it is necessary to inform that it was already delivered:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d 
JSON
{
  "fulfilled": true,
  "rating": positive
}
https://api.mercadolibre.com/orders/{orderId}/feedback?access_token=$ACCESS_TOKEN

Scenario 5

When it is necessary to cancel a sale:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d 
JSON
{
  "fulfilled": false,
  "rating": neutral
}
https://api.mercadolibre.com/orders/{orderId}/feedback?access_token=$ACCESS_TOKEN

Explanatory Note:

  • When canceling the sale through the feedback, the buyer will receive his/her payment back.

Please rate this

Mercado Envios mode 1

This guide explains how to work with all the resources our API provides to successfully list and manage listings with shipping mode me1. It also explains how to post tracking numbers to provide the buyers with the tracking information.

Contents:

Opting in for using ME1

To start using MercadoEnvios mode 1 you have get in touch with your MercadoLibre commercial assessor, since this mode is only available to VIP users and it’s activated by our Shipping developer’s team for each individual case.

Offering ME1 on your products

It’s quite simple to list an item with me1. Post the free shipping options and dimensions of the package whenever they are available.
If sellers do not provide package dimensions on their listing, category standard dimensions will be used.
URL to POST

https://api.mercadolibre.com/items?access_token=

JSON for the body

{
   "title":"Item de teste",
   "category_id":"MLA48786",
   "price":1200,
   "currency_id":"ARS",
   "available_quantity":2,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description":"test",
   "pictures":[
      {
         "source":"http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
      },
      {
         "source":"http://en.wikipedia.org/wiki/File:Teashades.gif"
      }
   ],
   "shipping":{
      "local_pick_up":false,
      "mode": "me1",
      "dimensions":"10x10x20,700"
   }
}

Dimensions

After being marked with me1 mode, you can add dimensions to your existing listings. Altering the dimensions of an item doesn’t affect its relevance in search results and there is no restriction to alter dimensions if the item has sales.
Each category has it’s own standard dimensions, but you can add the values you want, as long as they’re between the range of allowed values. Take a look a this guide to know allowed values for each site.

Know standard dimensions for a given category

Example:

curl -X GET https://api.mercadolibre.com/categories/MLM165702/shipping


Add dimensions

curl -X PUT -H "Content-Type: application/json" -d ‘{
   "shipping":{
      "dimensions":"10x10x20,700",
      "mode": "me1"
   }
}’ https://api.mercadolibre.com/items/:item_id?access_token=

Free shipping

Sellers have the option to list items offering one of the shipping methods for free.
Please check this entry to learn the details and how to list with free shipping.

Shipping Cost Calculator

There’s a resource on our API to calculate shipping costs for a given dimension, category and zip code destination.
There are 2 resources the shipping calculator can choose to better suit your available parameters; both of them return the same result.
URL

https://api.mercadolibre.com/users/:user_id/shipping_options?category_id=:category_id&dimensions=:dim&zip_code=13565905


https://api.mercadolibre.com/items/:item_id/shipping_options?zip_code=13565905

Response:

{
  "destination": - {
    "zip_code": "01001000",
    "city": - {
      "id": "BR-SP-44",
      "name": "São Paulo",
    },
    "state": - {
      "id": "BR-SP",
      "name": "São Paulo",
    },
    "country": - {
      "id": "BR",
      "name": "Brasil",
    },
    "extended_attributes": - {
      "address": "Praça da Sé",
      "owner_name": null,
      "zip_code_type": - {
        "type": "LO",
        "description": "Logradouro",
      },
      "city_type": "CP",
      "city_name": "São Paulo",
      "version": 6,
    },
  },
  "options": - [
    - {
      "id": 18310062,
      "name": "Normal",
      "currency_id": "BRL",
      "list_cost": 13.86,
      "cost": 13.86,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": - {
        "shipping": 72,
        "handling": 24,
      },
    },
    - {
      "id": 18310061,
      "name": "Expresso",
      "currency_id": "BRL",
      "list_cost": 14.88,
      "cost": 14.88,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": - {
        "shipping": 24,
        "handling": 24,
      },
    },
  ],
}


Attribute description

  • currency_id: The currency in which the price is charged.
  • list cost: The cost for this shipping option.
  • cost: The actual cost to be paid, for “free shipping” cost is 0.
  • tracks_shipments_status: Indicates how this method may be tracked.
  • tracks_shipments_status.verified : Can be internally tracked.
  • tracks_shipments_status.not_verified : Tracking information must be provided by seller.
  • tracks_shipments_status.no : Cannot be tracked.
  • speed.shipping: Promise of time to deliver, expressed in hours.
  • speed.handling: Promise of handling time, expressed in hours.

Shipping status

Some configurations of ME1 support automatic tracking, so shipping status will be updated by us. If this is not your case, then you’ll be responsible for sending a tracking number and update the shipping status. This is not mandatory but we suggest you to do it so you improve your chances of getting better feedback from the buyers.
Status:
pending
Shipment is created with this state.
handling
Payment has been received for this shipment.
shipped
Carrier has informed shipment departure.

Add tracking number

Is essential that sellers provide tracking number for their shipments, allowing the buyers to be aware of the status of their packages and estimated delivery time.
All you have to do is a PUT to the shipment with the service_id and tracking_number attributes.

curl -X PUT -H "Content-Type: application/json" -d  ‘{
  "tracking_number": "TR1234567891",
  "service_id": 1
}’  https://api.mercadolibre.com/shipments/:shipment_id?access_token=&ACCESS_TOKEN

Update shipping status

To update the shipping status on the order you need to make a PUT to the shipment.
To know the shipment_id you can make a call to orders, like this example:
Example:

curl -X GET https://api.mercadolibre.com/orders/{Order_id}/shipments



Initial shipping status is “pending”. Once you identify the shipping_id, you can update to another status.

Update status to handling

Example:

curl -X PUT -H "Content-Type: application/json" -d '{"status": "handling"}' https://api.mercadolibre.com/shipments/{Shipment_id}

Update status to shipped

Example:

curl -X PUT -H "Content-Type: application/json" -d '{shipping_option: {id:27569508},receiver_address: {"contact":"Roberto Gomez Bolaño","phone":"12345", address_line:"Avenida siempre viva updated", comment:"Casa azul.",zip_code:"90040060", "city": {"id": "TUxCQ1BPUjgwZTJl","name": "Porto Alegre"}, "state": {"id": "BR-RS","name": "Rio Grande do Sul"}, country: {id:"BR", name:"Argentina"}}}' https://api.mercadolibre.com/shipments/{Shipment_id}


Please rate this

Mercado Envios mode 2

You already know some of the particularities of opting for Mercado Envios 2. This tutorial will help you list a product with this mode and manage the whole shipping process using the resources of our API.

Contents:

Opting in for using ME2

If you want to use Mercado Envios mode 2, you may opt-in. Please check these links:
Argentina: http://envios.mercadolibre.com.ar/
Brasil: http://envios.mercadolivre.com.br/
Colombia: http://envios.mercadolibre.com.co/
México: http://envios.mercadolibre.com.mx/
Chile: http://envios.mercadolibre.cl/

Offering ME2 on your products

Once you opt-in to work with ME you can add the option to your items. When a buyer buys your product he will need to introduce an address at checkout and pay for the product with the shipping costs included.
We will follow the package and make sure it gets to the right place.
The money for the payment will be available on your account two days after the delivery is successful.
You will be able to add free shipping on your items and this will boost your listings on the search.

Listing a product with ME2 is very simple, just list an item as usual, including me2 in the shipping array.
Example:

curl -X POST -H "Content-Type: application/json" -d '{
    "title": "Item de teste",
    "category_id": "MLA91727",
    "price": 1200,
    "currency_id": "ARS",
    "available_quantity": 2,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "condition": "new",
    "description": "test",
    "pictures": [
        {
            "source": "http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
        },
        {
            "source": "http://en.wikipedia.org/wiki/File:Teashades.gif"
        }
    ],
   "shipping": {
   "mode": "me2",
   "local_pick_up": false,
   "free_shipping": false,
   "free_methods": []
 }
}' https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN


Free shipping

Sellers can list their products offering one of the shipping methods for free and Mercadolibre charges the seller for the shipping cost. Know the details and learn how to list with free shipping.

Shipping costs & handling time calculator

On our Marketplace sellers will have a shipping calculator on the item description page so buyers will know the cost for the shipping and estimated handling time.
You can use our resources to calculate this basing on the information you have .

A prepaid label is a PDF file that can be spent on the delivery of your product. It was already paid by the buyer, when he went through the checkout. Once you have an order paid by the buyer, you’ll need to print the prepaid label.
The shipments have to be in status ready_to_ship to be able to get a label (see later on how to check the shipment status). That means that the payment has been processed and the prepaid label is available for the seller.
The API to obtain a label, or a set of labels, receives a list of shipment IDs and an access token and returns the labels on the format of your choice. The options are PDF or ZPL.
To get the shipping label on PDF format make the following call:
Call:

https://api.mercadolibre.com/shipment_labels?shipment_ids=20178600648,20182100995&response_type=pdf&access_token=



The response will be a PDF file containing one or more prepaid shipping labels ready to print.

If you want the shipping labels on ZPL format you need to change the response_type=pdf to response_type=zpl2 on the GET you make to the API.

Example:

https://api.mercadolibre.com/shipment_labels?shipment_ids={shipping_id}&response_type=zpl2&access_token={access_token}


This resource returns a ZIP file. This ZIP includes a PDF with the PLP and a TXT file. Now you can print the TXT file from your Zebra printer.

Zebra thermal printer (Only for Mercadolibre Colombia)

If you work on Mercadolibre Colombia (MCO), there is another print format available, the thermal for Zebra printers. You can perform that by the next call:
Call:

/shipment_labels?shipment_ids={shipping_id}&response_type=thermal_pdf&access_token={access_token}



autorizacao
Paper configuration must be 100 x 213 millimeters
Note: If your operating system is Microsoft Windows use the driver: Generic Text Only Driver.

Considerations on label types by site

Printing typePrinterAvailables sitesResponse typeOutput
PDFCommon printer
  • Argentina (MLA)
  • México (MLM)
  • Brasil (MLB)
  • Colombia (MCO)
  • Chile (MLC)
  • response_type=pdfpdf label
    ZPL2Thermal printer
  • Argentina (MLA)
  • México (MLM)
  • Brasil (MLB)
  • Chile (MLC)
  • response_type=zpl2zip file containing the label on txt format and print summary in pdf format
    Thermal PDFThermal printer
  • Colombia (MCO)
  • response_type=thermal_pdfpdf label

    Shipping status

    Shipping status may vary on the order depending the shipping mode selected for the product. For modes that support automatic tracking and tracking numbers are monitored, the shipping status will be updated by us, while for other shipping modes, you’ll be responsible for sending a tracking number and update the shipping status. This is not mandatory but we suggest you to do it so you improve your chances of getting better feedback from the buyers.
    Status:
    pending
    Shipment is created with this state.
    handling
    Payment has been received for this shipment.
    ready_to_ship
    Authorization code has been received from carrier.
    shipped
    Carrier has informed shipment departure.
    delivered
    Carrier has informed shipment arrival.
    not_delivered
    Carrier was unable to deliver package.
    cancelled
    Shipment has been cancelled.

    Considerations

    Mercado Envíos BRASIL
    Mercado Envíos shipments come by default in publications from R $ 30 categories where the service is available.
    In all cases, the seller may add to the publication the possibility to deliver the product in person.
    There will be no changes in publication of less than R $ 30 or categories where the service is not enabled.

    Please rate this

    Listing types and item upgrades tutorial

    According to the level of exposition you want your items to have, you can choose between different kinds of listing types. Each listing type has it’s own characteristics and feeds, let’s take a look of how to work with them properly.

    Contents:

    Listings types by site

    First of all, you must know each site has his own listing types. To see all available listing types on a site, you should make a GET to listing_types resources with the Site_id:
    Example:

    https://api.mercadolibre.com/sites/MLC/listing_types

    Response:

    [
      {
        "site_id": "MLC",
        "id": "gold_pro",
        "name": "Premium"
      },
      {
        "site_id": "MLC",
        "id": "gold_premium",
        "name": "Oro Premium"
      },
      {
        "site_id": "MLC",
        "id": "gold_special",
        "name": "Clásica"
      },
      {
        "site_id": "MLC",
        "id": "gold",
        "name": "Oro"
      },
      {
        "site_id": "MLC",
        "id": "silver",
        "name": "Plata"
      },
      {
        "site_id": "MLC",
        "id": "bronze",
        "name": "Bronce"
      },
      {
        "site_id": "MLC",
        "id": "free",
        "name": "Gratuita"
      }
    ]
    

    In some sites, certain listing types underwent these changes.
    Anyway, the API continues listing history packages, which are automatically mapped to avoid integration errors.
    We suggest posting only under the following listing types, which are the active ones:

    MLA, MLB, MLC, MLM, MCO

    gold_pro: Premium
    gold_special: Classic
    free: For free

    MPE, MLV, MLU

    gold_special: Premium
    bronze: Classic
    free: For free
    Notes:

    • In the other sites, you may use any of the API listings.

    Listing type specification

    If you want more information about an specific listing_type, include the listing_type on the GET call:
    Example:

    https://api.mercadolibre.com/sites/MLA/listing_types/bronze

    Response:

    {
      "id": "bronze",
      "not_available_in_categories": [
        "MLA1743",
        "MLA1459"
      ],
      "configuration": {
        "name": "Bronce",
        "listing_exposure": "low",
        "requires_picture": false,
        "max_stock_per_item": 9999,
        "deduction_profile_id": null,
        "differential_pricing_id": null,
        "duration_days": {
          "buy_it_now": 60,
          "auction": 7,
          "classified": null
        },
        "immediate_payment": {
          "buy_it_now": false,
          "auction": false,
          "classified": false
        },
        "mercado_pago": "mandatory",
        "listing_fee_criteria": {
          "min_fee_amount": 0,
          "max_fee_amount": 0,
          "percentage_of_fee_amount": 0,
          "currency": "ARS"
        },
        "sale_fee_criteria": {
          "min_fee_amount": 0,
          "max_fee_amount": 100000000000000000,
          "percentage_of_fee_amount": 11,
          "currency": "ARS"
        }
      },
      "exceptions_by_category": [
        {
          "category_id": "MLA1540",
          "category_name": "Servicios",
          "configuration": {
            "name": "Básico 90",
            "listing_exposure": "mid",
            "requires_picture": false,
            "max_stock_per_item": 999,
            "deduction_profile_id": null,
            "differential_pricing_id": null,
            "duration_days": {
              "buy_it_now": null,
              "auction": null,
              "classified": 90
            },
            "immediate_payment": {
              "buy_it_now": false,
              "auction": false,
              "classified": false
            },
            "mercado_pago": "not_available",
            "listing_fee_criteria": {
              "min_fee_amount": 347,
              "max_fee_amount": 347,
              "percentage_of_fee_amount": 0,
              "currency": "ARS"
            },
            "sale_fee_criteria": {
              "min_fee_amount": 0,
              "max_fee_amount": 0,
              "percentage_of_fee_amount": 0,
              "currency": null
            }
          },
          "exceptions_by_category": [
          ]
        }
      ]
    }
    



    Items Clásica and Premium will have unlimited duration, you could consult it from stop_time field:

    curl -X GET https://api.mercadolibre.com/items/MCO415406202?attributes=stop_time

    Also, this listings will be paused if stock is 0, and will be activated when you add new quantity. You’ll see the item like this:

    "status": "paused",
      "sub_status": [
        "out_of_stock"
      ]
    

    If you want to add stock and active the item again, you should do it in this way:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "available_quantity": 1
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN
    

    Don’t forget that the listing type Gratuita is going to keep the current flow.

    The seller could change between the listing type Clásica and Premium every time that he wishes it without any charge, and could pause and finish the items in the same way that is working now.

    If you wish to change from Premium to Clásica, you will have to follow these steps:

    curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "id": "gold"
    }
    https://api.mercadolibre.com/items/{Item_id}/listing_type?access_token=$ACCESS_TOKEN
    

    Available listing types

    You can query available listing types by user and for a given category_id.
    Example:

    https://api.mercadolibre.com/users/{Cust_id}/available_listing_types?category_id={Category_id}&access_token=$ACCESS_TOKEN

    Response:

    {
      "category_id": "MLC3530",
      "available": [
        {
          "site_id": "MLC",
          "id": "gold_premium",
          "name": "Oro Premium",
          "remaining_listings": null
        },
        {
          "site_id": "MLC",
          "id": "gold",
          "name": "Oro",
          "remaining_listings": null
        },
        {
          "site_id": "MLC",
          "id": "silver",
          "name": "Plata",
          "remaining_listings": null
        },
        {
          "site_id": "MLC",
          "id": "bronze",
          "name": "Bronce",
          "remaining_listings": null
        },
        {
          "site_id": "MLC",
          "id": "free",
          "name": "Gratuita",
          "remaining_listings": null
        }
      ]
    }



    If you can’t list under a certain listing type and you want to know why you don’t have it available, you can make this GET call to know the cause:
    Example:

    https://api.mercadolibre.com/users/{Cust_id}/available_listing_type/free?category_id={Category_id}&access_token=$ACCESS_TOKEN

    Response:

    {
      "available": false,
      "cause": "You have more than 5 transactions in the last year.",
      "code": "list.transactions.exceeded"
    }



    Note:

    • Upgrades are available in MLB only; for the remaining sites you will need to complete the posting and re post with the desired listing type.

    Listing exposures

    This API returns information about the exposure levels associated to all listing types in MercadoLibre.
    You can query all listing exposures available by site, making a simple GET call.
    Example:

    https://api.mercadolibre.com/sites/MLA/listing_exposures

    Response:

    {[
      {
        "id": "lowest",
        "name": "Última",
        "home_page": false,
        "category_home_page": false,
        "advertising_on_listing_page": true,
        "priority_in_search": 4
      },
      {
        "id": "low",
        "name": "Inferior",
        "home_page": false,
        "category_home_page": false,
        "advertising_on_listing_page": false,
        "priority_in_search": 3
      },
      {
        "id": "mid",
        "name": "Media",
        "home_page": false,
        "category_home_page": true,
        "advertising_on_listing_page": false,
        "priority_in_search": 2
      },
      {
        "id": "high",
        "name": "Alta",
        "home_page": false,
        "category_home_page": true,
        "advertising_on_listing_page": false,
        "priority_in_search": 1
      },
      {
        "id": "highest",
        "name": "Superior",
        "home_page": true,
        "category_home_page": true,
        "advertising_on_listing_page": false,
        "priority_in_search": 0
      }
    ]



    And query each one by it’s Id:
    Example:

    https://api.mercadolibre.com/sites/MLA/listing_exposures/high

    Response:

    {
      "id": "high",
      "name": "Alta",
      "home_page": false,
      "category_home_page": true,
      "advertising_on_listing_page": false,
      "priority_in_search": 1
    }


    Available upgrades

    You can make upgrades to higher listing types to give your listings more exposition on our sites.
    If you need to make an upgrade, you can check which listing types are available for your item.

    Example:

    https://api.mercadolibre.com/items/{Item_id}/available_upgrades?access_token=$ACCESS_TOKEN

    Response:

    [
      {
        "site_id": "MLC",
        "id": "gold_premium",
        "name": "Oro Premium"
      },
      {
        "site_id": "MLC",
        "id": "gold",
        "name": "Oro"
      },
      {
        "site_id": "MLC",
        "id": "silver",
        "name": "Plata"
      }
    ]



    That’s it! Now you’re ready to get the right exposition for your products and make item upgrades.

    Since we know sometimes you won’t get your listing done in just one try, we offer you the possibility to check if your listing is exactly the way you want it before publishing. To know more about listing validator, please read this article.

    Downgrades

    A downgrade is when you reduce your item exposition by updating to a lower listing type. This is available for some particular cases:

    • Listings on MLB (Brazil) are allowed to have downgrades between gold_pro to gold_special and back anytime.
    • Listings on payment_required before they start can be downgraded.
    • Downgrade a listing to free is not allowed.

    Please rate this

    Analytics & Benchmarking

    If you want sellers to use the application that you developed to enhance their business, take into account that you have available a lot of useful information to help sellers create sales strategies and make smart decisions on time.

    Bear in mind that with our API you will be able to take the actions below:

    Follow our guides to learn how to take advantage of every resource!

    Sales metrics

    At this point, you must already know that sales on MercadoLibre are in the Orders resource. You can use it to take metrics on product sales, your seller’s monthly sales, each sale result, and the money earned. You can offer this to your sellers so that they get accurate data about how their business is doing on MercadoLibre.

    Follow the guide of the Orders resource and learn how to take sales metrics.

    Visits and questions metrics

    It may come handy for you to keep metrics on visits and questions so you can use this information to take action on how buyers react to the items you listed, for example you can try titles or pictures and see if the visits increase or decrease, and you can try different descriptions templates and specifications to check if users need to make many questions before bidding on your products or they bid quickly, and also this will be helpful to know the most frequently asked question and develop a feature that suggests answers for them.
    To achieve this you can use our visits resource and the questions search.

    Reputation metrics

    Reputation is each user public face on MercadoLibre, so sellers with a better reputation will improve their chances of selling over other users. Have this in mind and make your sellers aware of the importance of giving and getting feedback. Go to this guide to know how to work with the feedback resource.

    Help the sellers who use your application find out the most frequently searched words on our Marketplace. Follow this article to use our Trend resource.

    Price comparison

    You could suggest sellers using your system what’s the best price to sell their products and be competitive by analyzing the price of the same kind of products listed on MercadoLibre. To do this it may come handy to learn how to search items by category, then check the price field of those items and calculate the average.



    Next topic:
    MercadoLíder & Official Stores.

    Please rate this

    Manage feedback

    According to MercadoLibre’s business rules, after the sale (or purchase) is complete, the buyer and the seller must provide feedback about the transaction and rate each other. Buyers and sellers build their reputations based on their trading partners’ ratings.

    Contents:

    Resource description

    AttributeDescription
    fulfilledTrue or False. Indicates whether the order was completed or not.Required.
    messageA string under 160 chars. Required.
    ratingPossible values are ‘negative’, ‘neutral’ in case ‘fulfilled’: ‘false’ or positive in case ‘fulfilled’: ‘true’. Required.
    reasonMandatory field in case ‘fulfilled’: ‘false’.
    restock_itemOnly for sellers, when ‘fulfilled’: ‘false’. When ‘restock_item’: ‘true’ means the order was not completed so the item should be restocked. The only restriction for restocking is that the status of the item cannot be ‘closed’.
    has_seller_refunded_moneyOnly for sellers, when the order is ‘fulfilled’: ‘false’ and exists a payment associated with the order. Indicates if the user has issued a refund to the buyer.

    Accepted values to send as “reason”

    SELLER (All sites except MLB, MPA, MRD & MPT):

    • SELLER_OUT_OF_STOCK
    • SELLER_DIDNT_TRY_TO_CONTACT_BUYER
    • BUYER_NOT_ENOUGH_MONEY
    • BUYER_REGRETS


    SELLER (MPA, MRD & MPT):

    • SELLER_REGRETS
    • THEY_DIDNT_ANSWER
    • BUYER_REGRETS
    • SELLER_OUT_OF_STOCK
    • SELLER_DIDNT_TRY_TO_CONTACT_BUYER
    • BUYER_NOT_ENOUGH_MONEY
    • THEY_NOT_HONORING_POLICIES
    • OTHER_MY_RESPONSIBILITY
    • OTHER_THEIR_RESPONSIBILITY


    BUYER:

    • SELLER_OUT_OF_STOCK
    • BUYER_PAID_BUT_DID_NOT_RECEIVE
    • OTHER_MY_RESPONSIBILITY

    Posting feedback

    To associate feedback with an order, do a POST to the order as follows:

    curl -X POST -H "Content-Type: application/json" -d
    '{
      "fulfilled": false,
      "rating": "neutral",
      "message": "Operation not completed",
      "reason": "THEY_DIDNT_ANSWER",
      "restock_item": false,
      "has_seller_refunded_money": true
    }'
    
    "https://api.mercadolibre.com/orders/{order_Id}/feedback?access_token=$ACCESS_TOKEN"

    Responding to Feedback

    You can reply to feedback you received from your trading partners to explain your reasons or to give additional information by doing a POST to the API, including feedback_id, as follows:

    curl -X POST -H "Content-Type: application/json" -d'{
    "reply":"COMMENT 2."
    }' "https://api.mercadolibre.com/feedback/{feedback_Id}/reply?access_token=$ACCESS_TOKEN"

    How do I know the other party Feedback Id?

    This information can be obtained by doing a GET to orders. If you have already done this, there is no need to do it again, since the feedback_id is included in the GET response:

    curl -X GET "https://api.mercadolibre.com/orders/{order_Id}?access_token=$ACCESS_TOKEN"

    Response:

    {
      "id": 825103323,
      "status": "confirmed",
      "status_detail": {
        "code": null,
        "description": null
      },
      "date_created": "2014-03-17T23:27:53.000-04:00",
      "date_closed": "2014-03-17T23:27:53.000-04:00",
      "last_updated": "2014-06-01T16:36:28.000-04:00",
      "order_items": [
        {
          "item": {
            "id": "MLA494467937",
            "title": "Tag Heuer Aquaracer Automatico 43mm Cal16 Day-d Linea Nueva",
            "variation_id": null,
            "variation_attributes": []
          },
          "quantity": 1,
          "unit_price": 24100,
          "currency_id": "ARS"
        }
      ],
      "total_amount": 24100,
      "currency_id": "ARS",
      "buyer": {
        "id": 9981145,
        "nickname": "CARLITOS8665",
        "email": "carlitos8665@gmail.com",
        "phone": {
          "area_code": "011",
          "number": "1544706706",
          "extension": null
        },
        "alternative_phone": {
          "area_code": "011",
          "number": "48027618",
          "extension": null
        },
        "first_name": "Carlos",
        "last_name": "Acuña",
        "billing_info": {
          "doc_type": null,
          "doc_number": null
        }
      },
      "seller": {
        "id": 114499680,
        "nickname": "WATCHES-LUXURY2",
        "email": "watches-luxury2@hotmail.com",
        "phone": {
          "area_code": null,
          "number": "( 011) 1552490473",
          "extension": null
        },
        "alternative_phone": {
          "area_code": null,
          "number": "",
          "extension": null
        },
        "first_name": "carolina soledad",
        "last_name": "casares"
      },
      "payments": [],
      "feedback": {
        "purchase": {
          "id": 5040068164512,
          "date_created": "2014-04-07T11:20:00.000-04:00",
          "fulfilled": true,
          "rating": "positive",
          "status": "active"
        },
        "sale": {
          "id": 5040068160032,
          "date_created": "2014-04-07T11:20:57.000-04:00",
          "fulfilled": true,
          "rating": "neutral",
          "status": "active"
        }
      },
      "shipping": {
        "status": "to_be_agreed"
      },
      "tags": [
        "paid",
        "not_delivered"
      ],
      "mediations": [],
      "application_id": "2568868276694852",
      "hidden_for_seller": false,
      "buying_mode": "buy_it_now"
    }

    There is one pair of feedback_id for each transaction: sale and purchase. In this test example,“id”: 5040103892781 is the feedback_id for the sale-side , while “id”: 5040103885872 corresponds to purchase-side.

    Changing feedback

    You have already learned how to GET the other party’s feedback_id just by doing a POST to the API as follows:

    curl -X PUT -H "Content-Type: application/json" -d '{
      "fulfilled": true,
      "rating": "positive",
      "message": "It’s ok.",
    }' "https://api.mercadolibre.com//feedback/{feedback_id}?access_token=$ACCESS_TOKEN"



    Next topic: Searches & advanced features.

    Please rate this

    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

    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.

    topicsconmensajeria

    – 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, 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.
      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.

    • messaging – The topic will inform the subscriber of new messages created with his/her user_id as receiver.

    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.

    messaging

    • Each new message getting into the platform will post a topic to be informed to the subscriber.
    • When sending messages.
    • When there are messages read.



    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 https://api.mercadolibre.com/items/{Item_id}?access_token=ACCESS_TOKEN


    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 https://api.mercadolibre.com/orders/{Order_id}?access_token=ACCESS_TOKEN


    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 https://api.mercadolibre.com/questions/{Question_id}?access_token=ACCESS_TOKEN



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

    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 https://api.mercadolibre.com/collections/{Payment_id}?access_token=ACCESS_TOKEN


    messaging

    Notification response:

    {"user_id":,"resource":}

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

    curl -X GET https://api.mercadolibre.com/messages/?access_token=

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

    https://api.mercadolibre.com/myfeeds?app_id=(APP_ID)&offset=1&limit=5

    Next:
    Manage feedback.

    Please rate this

    Manage Sales

    An order is a request a customer places on a listed item with the intention to purchase it under a series of conditions he/she will choose throughout the checkout flow.
    These conditions are detailed on the order that will be replicated for the buyer and the seller accounts as well. On the order you’ll find a lot of information to fill out about your product and you’ll be able to reserve and/or subtract stock.

    Contents:

    Receive an order

    Once a new order is created on your user, you can check its details by making a request to the order resource:
    Example:

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

    Response:

    {
      "id": 768570754,
      "status": "paid",
      "status_detail": null,
      "date_created": "2013-05-27T10:01:50.000-04:00",
      "date_closed": "2013-05-27T10:04:07.000-04:00",
      "order_items": - [
    	- {
      	"item": - {
        	"id": "MLB12345678",
      	  "title": "Samsung Galaxy",
        	"variation_id": null,
        	"variation_attributes": [
        	],
      	},
      	"quantity": 1,
      	"unit_price": 499,
      	"currency_id": "BRL",
    	},
      ],
      "total_amount": 499,
      "currency_id": "BRL",
      "buyer": - {
    	"id": "123456789",
    	"nickname": "COMPRADORTESTE",
    	"email": "b@b.com",
    	"phone": - {
      	"area_code": "11",
      	"number": "12345678",
      	"extension": null,
    	},
    	"first_name": "Comprador de testes",
    	"last_name": "da Silva",
    	"billing_info": - {
      	"doc_type": "CPF",
      	"doc_number": "12345678910",
    	},
      },
      "seller": - {
    	"id": "123456789",
    	"nickname": "VENDEDORTESTES",
    	"email": "a@a.com",
    	"phone": - {
      	"area_code": null,
      	"number": "11 12345678",
      	"extension": "11",
    	},
    	"first_name": "Vendedor de Testes",
    	"last_name": "testes de documentacao",
      },
      "payments": - [
    	- {
      	"id": "596707837",
      	"transaction_amount": 499,
      	"currency_id": "BRL",
      	"status": "approved",
      	"date_created": null,
      	"date_last_modified": null,
    	},
      ],
      "feedback": - {
    	"purchase": null,
    	"sale": null,
      },
      "shipping": - {
    	"id": 20676482441,
    	"shipment_type": "shipping",
    	"status": "handling",
        "date_created": "2013-05-27T10:03:28.000-04:00",
    	"receiver_address": - {
      	"id": 12345678,
      	"address_line": "Rua dos testes 123  ",
      	"zip_code": "01001000",
      	"city": - {
        	"id": "BR-SP-44",
        	"name": "São Paulo",
      	},
      	"state": - {
        	"id": "BR-SP",
        	"name": "São Paulo",
      	},
      	"country": - {
        	"id": "BR",
        	"name": "Brasil",
      	},
      	"latitude": null,
      	"longitude": null,
      	"comment": null,
    	},
    	"currency_id": "BRL",
    	"cost": 0,
      },
      "tags": - [
    	"paid",
    	"not_delivered",
      ],
    }

    Orders have a lot of attributes. Below you will see a description of the most important fields.
    id Unique order identifier.
    date_created Order creation date.
    date_closed Order confirmation date. It is set when an order status changes for the first time to confirmed / paid and the item is subtracted from the stock.
    expiration_date This is the deadline for the user to qualify since, after that date, the feedback is made visible, payments are released (if any), and charges are created.
    status Order status. See possible values.
    status_detail Status detail, in case the order is canceled.
    code Status code.
    description Status description.
    comprador Buyer’s Information.
    vendedor Seller’s information.
    order_items Order item listings.
    payments Order-related payments.
    feedback Order-related feedback information.
    shipping Shipping configuration for this order.
    total_amount Total invoice amount.
    currency_id Currency ID.
    tags List of seller selected tags, such as delivered, paid.

    Search Orders

    The search orders resource will help you browse every order that belongs to users for whom you have a valid token.

    https://api.mercadolibre.com/orders/search?buyer=buyer_id&access_token={...}

    The fields “available_filters” and “available_sorts” are available in search orders.

    How to filter?

    For example, to filter your orders with “paid” status, you will find the “order.status” ID among the “available_filters,” and, in turn, you will find the value with “paid” ID in that field.

    https://api.mercadolibre.com/orders/search?seller=seller_id&order.status=paid&access_token={...}

    If you want to filter your orders by date, you should do the following:

    https://api.mercadolibre.com/orders/search?seller=&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00&access_token=

    How to sort?

    In this case, you should add “sort” to the available sort ID that you wish to apply, for example: “date_desc”.

    https://api.mercadolibre.com/orders/search?seller={seller_id}&order.status=paid&sort=date_desc&access_token={...}

    Note: By default, it sorts by date_asc. The sorting date is:

    • Sellers by date_closed.
    • Buyers by date_created.

    Recent Orders

    Recent orders are the latest orders that were generated for a user. The response will include orders in which the current date is before expiration_date, and haven’t been qualified by any of the parties.
    Searching for a seller’s recent orders:

    https://api.mercadolibre.com/orders/search/recent?seller=seller_id&access_token={...}

    Searching for a buyer’s recent orders:

    https://api.mercadolibre.com/orders/search/recent?buyer=buyer_id&access_token={...}

    Archived Orders

    If you are looking for an order with expiration_date after current date or which was qualified by both parties, you can use the search archived orders resource:
    Searching for a seller’s archived orders:

    https://api.mercadolibre.com/orders/search/archived?seller=seller_id&access_token={...}

    Searching for a buyer’s archived orders:

    https://api.mercadolibre.com/orders/search/archived?buyer=buyer_id&access_token={...}

    Pending Orders

    This search will retrieve all the orders with “pending” status, and will automatically skip canceled orders.
    If you want to see a specific seller’s orders, send the seller_id:

    https://api.mercadolibre.com/orders/search/pending?seller=seller_id&access_token={...}

    To search by buyer, replace the parameters as follows:

    https://api.mercadolibre.com/orders/search/pending?buyer=user_id&access_token={...}

    Order Status

    Order statuses are the following:
    confirmed
    Initial status of an order, even if it is still unpaid.
    payment_required
    Order payment should be confirmed to display user information.
    payment_in_process
    There is an order-related payment, but it has not been credited yet.
    partially_paid
    The order-related payment is credited, but it is not enough.
    paid
    The order-related payment is credited.
    cancelled
    For some reason, the order was not fulfilled.*
    invalid
    The order was invalidated as it came from a malicious buyer.

    *Note:
    An order may be canceled due to the following reasons:

    • Payment approval was required to subtract stock, but, during the approval process period, the item was paused/terminated due to stockout; so, the payment is returned to the buyer.
    • Payment was required, but, as it was not paid within a specific period, it was automatically canceled.
    • After making a transaction, for some reason the seller is banned from the site.

    Mandatory Mercado Pago Flow (only for countries with MP)

    How to find out if a site has Mercado Pago enabled?
    To get that information, call:

    curl https://api.mercadolibre.com/sites/MLA

    If you receive “MLAMP” as a response within “payment_method_ids,” you will be able to work smoothly with this flow.

    Explanatory Note: MLAMP is Mercado Pago’s payment method ID:

    curl https://api.mercadolibre.com/payment_methods/MLAMP

    On our platform you will find orders which can go through Mercado Pago’s mandatory flow as the only payment method, and others which cannot.
    This choice will be mandatory in the scenarios below:

    • All MLB orders
    • All MLA and MLM orders from the sale of products with “condition”: “new”
    • Official Store Listings in every country with Mercado Pago.
    • Categories with Mercado Pago as the only choice. (For more information, visit: “Immediate payment categories
    • User automatically marked to have transactions routed through this flow with the mark “immediate_payment” in the users API.
    • Seller “auto” marked to have sales routed through this flow.


    Now we will explain the general operation of orders entered through this flow or otherwise:
    1) Orders entered through this flow are created with a “payment_required” status.
    And they have the following characteristics:

    • They are not visible to the seller.
    • The item is not subtracted from the stock.
    • The date_closed field is not filled out.
    • Counterpart data is not filled out.
    • Only the “created_orders” topic notification is sent.

    When the total amount of the sale payment is credited, order status changes from “payment_required” to “paid.” At that time:

    • They become visible to the seller.
    • The item is subtracted from the stock.
    • The date_closed field is filled out.
    • The counterpart’s data is filled out.
    • The “orders” topic notifications start to be sent.


    2) Orders NOT entered through this flow are created with a “confirmed” status. Starting at that time:

    • They are visible to the seller.
    • The item is subtracted from the stock.
    • The date_closed field is filled out.
    • The counterpart’s data is filled out.
    • The “orders”/“created_orders” topic notifications start to be sent.

    If a payment made through Mercado Pago is credited for the total amount of the sale, order status changes from “confirmed” to “paid”.

    Explanatory Note: In both cases, if the buyer selects Mercado Envíos (ME2, only in countries where this service is enabled) in the payment flow, the shipping will have the label ready to print once the order status changes to “paid.” More information.

    How does your app become aware of a purchase?

    The creation of an order is an event that occurs on MercadoLibre’s side, so you’ll need to subscribe to our orders feed to become aware in real time when that event occurs.
    Go to our Application Manager and edit your application Notifications Settings. For more information about creating and configuring a new app, please check this link.
    You must choose a Callback URL: configure the public URL of the domain where you want to receive all the notifications from MercadoLibre. For example:
    The creation of an order is an event that occurs on MercadoLibre’s side, so you’ll need to subscribe to our orders feed to become aware in real time when that event occurs.
    Go to our Application Manager and edit your application Notifications Settings. For more information about creating and configuring a new app, please check this link.
    You must choose a Callback URL: configure the public URL of the domain where you want to receive all the notifications from MercadoLibre. For example: “https://backend.soleorigami.com/notification”.

    ORDERS

    This configuration allows you to interact with MercadoLibre notifications. All the events (like payments and shipping) related to an order will be notified to your callback URL.

    Receive a Notification

    Mercado Libre will send you notifications through a POST message with information in the listing body. The most important attribute in the message is the notification-related user_id, followed by the resource. The resource is the element which was updated or created.

    {
      "user_id": 1234,
      "resource": "/orders/731867397",
      "topic": "orders",
      "received": "2011-10-19T16:38:34.425Z",
      "application_id" : 14529
      "sent" : "2011-10-19T16:40:34.425Z",
      "attempts" : 0
    }

    After receiving a notification, you must send an acknowledgment (ACK 200) to MercadoLibre in order to stop receiving it.

    Payments

    Mercado Pago is MercadoLibre’s payment platform. If you want to integrate a payment solution on your platform, you should check Mercado Pago’s developers’ website.

    Multiple Payment Scenario

    In some cases, when the payment is rejected for reaching the credit card limit, we let users add another payment with a second credit card.

    How can I know if there are two payments?

    When you make a GET to Orders API, you’ll see that there will be two IDs with the details of each payment in the payment array.

    Example:

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

    Response:

    {
    	"buyer": {
        	"alternative_phone": {
            	"area_code": null,
            	"extension": null,
            	"number": ""
        	},
        	"billing_info": {
            	"doc_number": "67045427794",
            	"doc_type": "CPF"
        	},
        	"email": "test_user_21963158@testuser.com",
        	"first_name": "Test",
        	"id": 160903317,
        	"last_name": "Test",
        	"nickname": "TETE2022123",
        	"phone": {
            	"area_code": "01",
            	"extension": null,
            	"number": "1111-1111"
        	}
    	},
    	"coupon": {
        	"amount": 0,
        	"id": null
        },
    	"currency_id": "BRL",
    	"date_closed": null,
    	"date_created": "2014-10-26T22:46:18.000-04:00",
    	"feedback": {
        	"purchase": null,
        	"sale": null
    	},
    	"id": 893431118,
    	"last_updated": "2014-10-26T22:50:10.000-04:00",
        "mediations": [],
    	"order_items": [
        	{
            	"currency_id": "BRL",
            	"item": {
                	"id": "MLB600034093",
                	"title": "Item De Testeo, Por Favor No Ofertar --kc:off",
                	"variation_attributes": [],
                	"variation_id": null
            	},
            	"quantity": 1,
            	"unit_price": 591
        	}
    	],
    	"paid_amount": 591,
    	"payments": [
        	{
            	"activation_uri": null,
            	"atm_transfer_reference": {
                	"company_id": null,
                    "transaction_id": null
            	},
                "available_actions": [],
            	"card_id": null,
            	"collector": {
                	"id": 169648308
            	},
            	"coupon_amount": 0,
            	"coupon_id": null,
            	"currency_id": "BRL",
            	"date_created": "2014-10-26T22:48:46.000-04:00",
                "date_last_modified": "2014-10-27T00:51:53.000-04:00",
            	"id": 885920310,
            	"installments": 1,
            	"issuer_id": "25",
            	"operation_type": "regular_payment",
            	"order_id": 893431118,
            	"overpaid_amount": 0,
            	"payer_id": 160903317,
                "payment_method_id": "visa",
            	"payment_type": "credit_card",
            	"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
            	"shipping_cost": 0,
            	"site_id": "MLB",
            	"status": "approved",
            	"status_code": null,
            	"status_detail": "accredited",
                "total_paid_amount": 296,
                "transaction_amount": 296
        	},
        	{
            	"activation_uri": null,
                "atm_transfer_reference": {
                	"company_id": null,
                    "transaction_id": null
            	},
                "available_actions": [],
            	"card_id": null,
            	"collector": {
                	"id": 169648308
            	},
            	"coupon_amount": 0,
            	"coupon_id": null,
            	"currency_id": "BRL",
    	        "date_created": "2014-10-26T22:50:10.000-04:00",
                "date_last_modified": "2014-10-26T22:50:21.000-04:00",
            	"id": 885920410,
            	"installments": 3,
            	"issuer_id": "25",
            	"operation_type": "regular_payment",
            	"order_id": 893431118,
            	"overpaid_amount": 0,
            	"payer_id": 160903317,
                "payment_method_id": "visa",
            	"payment_type": "credit_card",
            	"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
            	"shipping_cost": 0,
            	"site_id": "MLB",
            	"status": "approved",
            	"status_code": null,
            	"status_detail": "accredited",
                "total_paid_amount": 315.62,
                "transaction_amount": 295
        	}
    	],
    	"seller": {
        	"alternative_phone": {
            	"area_code": null,
            	"extension": null,
            	"number": ""
        	},
        	"email": "test_user_70385259@testuser.com",
        	"first_name": "Test",
      	  "id": 169648308,
        	"last_name": "Test",
        	"nickname": "TETE6072468",
        	"phone": {
            	"area_code": "01",
            	"extension": null,
            	"number": "1111-1111"
        	}
    	},
    	"shipping": {
        	"status": "to_be_agreed"
    	},
    	"status": "paid",
    	"status_detail": null,
    	"tags": [
        	"not_delivered",
        	"paid"
    	],
    	"total_amount": 591,
        "total_amount_with_shipping": 591
    }

    How to get information about a payment?

    To get information about a buyer’s payment, using the token go to “payments” resource.

    Example:

    https://api.mercadolibre.com/payments?access_token=

    How to get information about a payment from the seller?

    To get information about a payment from the seller’s role, go to payment_id es “collections” resource.

    Example:

    https://api.mercadolibre.com/collections?access_token=

    Advanced

    Order Notes

    A note is an annotation sellers can add to orders. Notes can have up to 300 characters each and, once you post a note, you can either modify or delete it.

    How to add a note to an order?

    curl -X POST -H "Content-Type: application/json" -d '{  	
       	"note": "test",
    }' https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN

    See Order Notes

    curl -X GET https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN

    How to modify a note?

    curl -X PUT -H "Content-Type: application/json" -d '{
       	"note": "test2",
    }' https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN

    Delete Notes

    curl -X DELETE https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN

    Block Bids

    Even though we have a fraud prevention feature and flows to keep buyers and sellers safe, sometimes you may find users who, for some reason, bid on your items. These cases can be sent to your blacklist to prevent them from bidding.

    How do I block bids from a specific user?

    Make a POST with the cust_id of the user you want to block on the JSON and yours in the url, like in the following example:

    curl -X POST -H "Content-Type: application/json" -d
    { user_id: {cust_id} }
    https://api.mercadolibre.com/users/{cust_Id}/order_blacklist?access_token=$ACCESS_TOKEN

    Check your blacklist

    If you want to know which users are on your blacklist, make a GET to the API with your cust_id in the url:

    curl -X GET https://api.mercadolibre.com/users/{cust_id}/order_blacklist?access_token=$ACCESS_TOKEN

    Remove a user from your blacklist

    If you don’t want to block a user from making bids anymore, you can remove him/her from your blacklist by making a DELETE to the API with your cust_id and the blocked user’s cust_id.

    curl -X DELETE https://api.mercadolibre.com/users/{your_cust_id}/order_blacklist/{cust_id}

    Error Code Reference

    ErrorDescriptionPossible solution
    order_not_found

    Order not found.

    $order_id incorrect.The order cannot be found, check if the order_id is correct. More information
    empty_order_id

    Order ID can not be empty.

    $order_id is null.The parameter order_id cannot be null, check the URL used. More information
    invalid_order_id

    Invalid order id.

    $order_id incorrect.The parameter order_id must be a integer number. (For search your orders see this topic)
    not_identified_user

    Can not identify the user.

    Can not identify the user.Send a token.
    not_owned_order

    The user has not access to the order.

    $seller or $buyer incorrect.To see one order, your access_token must be generated from seller or buyer.
    caller.id.invalid

    caller.id does not match buyer nor seller.

    $seller or $buyer incorrect.To see one order, you must be use one ID from seller or buyer.
    feedback_not_found

    The feedback does not exist.

    Reply error.Check if feedback exist for give a reply.
    invalid_fulfilled

    ‘fulfilled’ parameter must be true or false.

    Error on give feedback.Check the parameter $fulfilled this must be boolean (remove quotation marks) and check if the parameter $reason is not null in case of $fulfilled: false.
    reply_time_expired

    Reply time expired. There is a 14 days period to reply a feedback.

    Error on give reply on feedback.The reply can be sent in 14 days past the feedback date.
    reply_already_exists

    Reply already exists for the feedback.

    Error on give reply on feedback.The feedback supports only one reply.



    Next topic:
    Messaging API.

    Please rate this

    Manage questions & answers

    Questions are the way buyers can communicate to sellers on the Item details page before making a transaction, and therefore, the way you handle interaction at this stage will be decisive to make a successful sale.

    Contents:

    Search questions

    There are a few ways to search questions.

    Questions received by a seller

    curl -X GET -H "Content-Type: application/json" 'https://api.mercadolibre.com/questions/search?seller_id={Seller_id}&access_token=$ACCESS_TOKEN'

    Questions received on an item

    curl -X GET -H "Content-Type: application/json" 'https://api.mercadolibre.com/questions/search?item={Item_id}'

    Questions made by a user on an item

    curl -X GET -H "Content-Type: application/json" 'https://api.mercadolibre.com/questions/search?item={Item_id}&from={Cust_id}'

    Questions by id

    curl -X GET -H "Content-Type: application/json" 'https://api.mercadolibre.com/questions/{question_id}?access_token=$ACCESS_TOKEN'

    Note: Bear in mind that if you query without an access token and the question status is DELETED or BANNED, you will get “question not found”



    Let’s take a look at the attributes we’ll found on the Search Questions resource.

    Attributes description

    AttributeDescription
    idQuestion Id.
    date_createdCreation date.
    item_idItem Id that the question belongs to.
    seller_idSeller Id of the item.
    statusQuestion status. Possible values:
    unansweredQuestion is not answered yet.
    answeredQuestion was answered.
    closed_unansweredThe item is closed and the question was never answered.
    under_reviewThe item is under review and the question too.
    textText of the question.
    answerAnswer from the seller to the question.
    date_createdCreation date.
    statusStatus of the answer. Possible values: Active, Disabled
    activeAnswer is active.
    disabledThe answer has been disabled.
    textText of the answer.

    Great! now you know what aspects to have in mind about questions. Check what actions are available according to questions search.

    Allowed methods

    MethodDescription
    GET /questions/:idReturns a question with that id.
    POST /questionsCreates a question on an item.
    DELETE /questions/:idDeletes a question.
    POST /answers/POST an answer to a given question.
    POST /my/questions/hiddenHide questions.

    As you can see, you can search questions by item, by seller, by the user who made them and filter them by status or period. You can also search all your received questions and hide them if you want.

    Ask questions

    This is a very simple task. You only need to know the item_id and send it along with a text String on the Json body like in the following example:

    curl -X POST -H "Content-Type: application/json" -d '{
       "text":"Test question.",
       "item_id":"MLA608007087"
    }' https://api.mercadolibre.com/questions/MLA608007087?access_token=$ACCESS_TOKEN

    Answer questions

    When you have a large amount of items listed on MercadoLibre you’re probably gonna receive lots of questions so we recommend you develop a way to answer those questions in a semi-automatic way, where answers are suggested to operators basing on frequent keywords.
    To do so, you need to know how to answer a question by API. This is gonna be easy.

    First, let’s check all the questions you got on your item. Just make a question search by item like in the example:

    curl 'https://api.mercadolibre.com/questions/search?item_id=ITEM_ID&access_token=XXXX'

    You’ll see questions have a status, so you’ll probably gonna have to keep those under “unanswered” status.

    Now let’s answer a single question:

    curl -X POST -H ""Content-Type: application/json"" -d '{
    	"question_id": 3957150025,
    	"text":"Test answer..."
    }' https://api.mercadolibre.com/answers?access_token=$ACCESS_TOKEN

    Get questions detail

    Example:

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

    Response:

    {
      "id": 3957150025,
      "answer": {
        "date_created": "2016-02-29T11:21:27.000-04:00",
        "status": "ACTIVE",
        "text": "Test answer..."
      },
      "date_created": "2016-02-29T11:19:42.000-04:00",
      "deleted_from_listing": false,
      "hold": false,
      "item_id": "MLA608007087",
      "seller_id": 202593498,
      "status": "ANSWERED",
      "text": "Test question.",
      "from": {
        "id": 207119838,
        "answered_questions": 1
      }
    }

    When working with questions is very useful to listen to Notifications since it enables you to have a real-time feed of events that occur regarding to them. Learn how to work with notifications.

    Delete questions

    If you have the need to delete a question an user made on your item just use the DELETE method with the question ID and the seller’s access token.
    Example:

    curl -X DELETE 'https://api.mercadolibre.com/questions/${question_id}?access_token=$ACCESS_TOKEN'

    Response:

    [
      "Question deleted."
    ]

    Questions blacklist

    Managing the question’s blacklist allows you to block users from asking questions on your items. Later on, you can remove them from the blacklist to allow questions.

    This blacklist is user-based and the seller has full control over the list of users on it. Let’s see a few examples of thing you can do with it.

    Send users to questions blacklist

    curl -X POST -H "Content-Type: application/json" -d
    '{
      "user_id": blocked user id
    }'
    https://api.mercadolibre.com/users/$SELLER_ID/questions_blacklist?access_token=$ACCESS_TOKEN

    Get questions blacklist

    curl -X GET 'https://api.mercadolibre.com/users/$SELLER_ID/questions_blacklist?access_token=$ACCESS_TOKEN '

    Remove a user from blacklist

    curl -X DELETE 'https://api.mercadolibre.com/users/$SELLER_ID/questions_blacklist/$USER_ID?access_token=$ACCESS_TOKEN'

    Perfect, now you know everything there’s is to know about our question blacklist. We hope it comes handy if it’s needed.

    How to be aware of a question?

    A question on an item is an event that occurs on MercadoLibre’s side, so you’ll need to subscribe to our questions feed to be aware in real time when that event occurs.
    First of all, we have to configure our application to be capable of getting notifications. This can be done by subscribing your application to questions notifications. Go to our Application Manager (http://applications.mercadolibre.com) and edit your application Notifications Settings. For more information about creating and configuring a new app, please check this guide.
    You must choose a Callback URL: configure the public URL of your domain where you want to receive all the notifications from MercadoLibre. E.g.: “https://backend.soleorigami.com/notification”.

    Also you need to specify which “topic” you will list, in this case you must select questions.
    This configuration allows you to interact with MercadoLibre notifications. All the events regarding new questions will be notified to your callback URL.

    Receiving a Notification

    MercadoLibre will send you notifications through a POST message with information inside items body. The most important attribute in the message is the user_id which is related to the notification and second one is the resource. The resource is the element that has been updated or it has been created.

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

    After receiving the notification you must send an acknowledgment (ACK 200) to MercadoLibre in order to stop receiving the notification.
    Check our Notifications tutorial to know further.

    Error codes reference

    ErrorDescriptionPossible solution
    invalid_questionThe question is invalid.Cannot answer question.The parameter question_id must be a integer number. (To search your question call the resource/questions/search).
    invalid_post_bodyInvalid JSON. Valid attributes are: {0}.Invalid parameters.Expected parameters are question_id and text.



    Next topic:
    Manage sales.

    Please rate this

    Sync and moditify listings

    Once you have active listings on our marketplace, you’ll probably need to update and modify those listings from time to time in order to synchronize stock with other platforms you’re working with, pause listings, improve descriptions, update prices and more.
    Follow this guide to know how to achieve this actions.

    Contents:

    Considerations

    Not every field can be updated and this will vary whether the item had sales or not, and also remember your item must be active in order to be modified. You can modify the values for:

    • Title
    • Available_quantity
    • Price
    • Video
    • Pictures
    • Description*
    • Shipping

    *It’s not possible modify, just add a post.
    When the item has sales you won’t be allowed to change any of the following item fields:

    • Condition
    • Buying mode
    • Non MercadoPago Payment Methods
    • Warranty
    • Description*
    • *It’s not possible modify, just add a post.

    Also remember that:

    • Category can’t be modified via API.
    • Listing type can be modified only once.

    Update your item

    Let’s see a basic example of updating an item title and price. The only thing you need is the item_id of the listed product and of course, the seller’s access_token.

    Example:

     curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "title": "Your new title",
      "price": 1000
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN



    Nice, your item title and price has been updated and you should receive a code 200 OK response status to know everything went well.
    Keep in mind that it can take some time until you see the item’s information refreshed.

    Description

    It’s very easy to update a description, and is something you can do whether the item has bids or not, but since there are some considerations you need to keep when adding or replacing descriptions, check our descriptions article to make sure you get it right.

    Pictures

    You can always add or replace item pictures, refer to our working with pictures tutorial to know the best way to get through it.

    Listing types

    When you want more exposition on your item you need to make a listing type upgrade. Know the details and considerations and learn how to achieve an upgrade on our Listing types and Upgrades tutorial.

    Changing listing status

    Any item listed on our marketplace can hold different status, check the following description of each one:


    closed: Finalizes your publication. Once closed, it cannot be reactivated again, but it can be relisted.

    Example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "status":"closed"
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN


    paused: Pauses your publication. Once paused, it will not be visible to other MercadoLibre’s users, but it will not be closed and it can be reactivated later on.
    Example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "status":"paused"
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN



    active: Reactivates a previously paused item.
    Example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "status":"active"
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN


    Note: If you need to make any changes on the item status, you need to send any of these values for the “status” field, note the value is case sensitive and must be sent in lowercase.

    If your item is currently closed and your intention is to relist it, check our relist article to achieve it right away.
    Please check out the listing life-cycle article to know more about item status.

    Machine Status Reference

    Active: Listing is active and bids and questions can be received. You can change the listing display (upgrade listing type).

    Payment required: This is the case where a debtor user or a user with low credit policy makes a listing and it is automatically reactivated once the user makes the payment.

    Under Review: The item is under review by Mercado Libre due to the following reasons:

    • warning: item still active but pending to be corrected by the user. If it is not corrected within 2 days it will change to waiting_for_patch.
    • waiting_for_patch: item hidden until the user corrects the reported breach.
    • held: hidden item waiting for a manual moderation by Mercado Libre.
    • pending_documentation: item hidden until the user submits the requested documentation.
    • forbidden: item removed due to moderation.

    Note: If you have any doubts about this state we suggest you check it with your commercial assessorr or MyML.

    Paused: It may be automatically (out of stock) or at the user’s discretion.

    • out of stock: the item was paused for being out of stock, and it will be automatically activated upon restocking.

    Note: The item will be paused in the VIP and no bids can be received.

    Closed: This is the final item status, and it can be due to the following reasons:

    • waiting for patch
    • held
    • expired: the listing end time was reached (end_time), and there is still stock.
    • deleted: it is added when the item is closed, and the seller decides to delete it. Or when the item expires and it is automatically re-listed.
    • suspended
    • freezed

    Note: Bear in mind that, after a period of time, finished items will no longer be displayed for query.

    Delete listing

    Deleting a listing has no way back, so be careful when you call this action. Also note that there’s no need to delete closed items since they’ll be discarded automatically after some time.
    If you still need to delete an item, for example items in status: payment_required that won’t respond to ‘closed’ status, do as it follows:
    Example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
    "status": "closed"
    }
    
    {
    "deleted":"true"
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN

    That’s it! Your item should be removed.

    Update stock

    Updating an item stock is quite easy. Just add the value in the “available_quantity” field taking the following into account:

    • When making a PUT to an available_quantity with 0, the status will change to “paused” with out_of_stock sub status.
    • When making a PUT to an available_quantity with 0 and out_of_stock status, the status will change to active without out_of_stock sub status.

    Note: This change can be made to items and item variations.

    Where is this functionality possible?

    Those sites that support automatic pausing with stock 0 are MLB, MLA, MLM, MLC, MPE, MLV.

    Example:

    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
    {
      "available_quantity": 6
    }
    https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN

    Easy. You can check your listing and see stock updated.
    If you need to update stock or make any changes on an item with variations, you’ll find a slightly difference on how the updates are made, please follow up our variations tutorial to know how to do it right.



    Next topic: Manage questions & answers.

    Please rate this

    MercadoLíder & Official Stores

    Now that you already know how to work with Mercado Libre users, it is time to analyze their special features for MercadoLíderes & Official Stores.

    Official Stores

    Some selected users are part of Mercado Libre Official Stores, and have one or more brands under the same user. Follow this tutorial to learn how to work.

    Deals

    If you have received an invitation for one of this campaigns and you want to join, follow this tutorial to learn the basic of how to suggest your products.

    Intellectual Property Protection Program

    Our Program enables intellectual property right owners or agents to report and request removal of postings breaching their rights. For more information read this tutorial.

    Manage users

    Overview

    If you registered your application, authenticated and created a Test user successfully, the next step is to learn how to work with users (sellers and buyers).

    Contents:

    Get my personal data

    If you are logged in MercadoLibre and have a token, you will be able to make the call below and learn about your user-related information:

    Example:

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

    Response:

    {
      "id": 202593498,
      "nickname": "TETE2870021",
      "registration_date": "2016-01-06T11:31:42.000-04:00",
      "first_name": "Test",
      "last_name": "Test",
      "country_id": "AR",
      "email": "test_user_50698062@testuser.com",
      "identification": {
    	"type": "DNI",
    	"number": "1111111"
      },
      "address": {
    	"state": "AR-C",
    	"city": "Palermo",
    	"address": "Test Address 123",
    	"zip_code": "1414"
      },
      "phone": {
    	"area_code": "01",
    	"number": "1111-1111",
    	"extension": "",
    	"verified": false
      },
      "alternative_phone": {
    	"area_code": "",
    	"number": "",
    	"extension": ""
      },
      "user_type": "real_estate_agency",
      "tags": [
    	"real_estate_agency",
    	"test_user",
    	"user_info_verified"
      ],
      "logo": null,
      "points": 100,
      "site_id": "MLA",
      "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
      "shipping_modes": [
    	"custom",
    	"not_specified"
      ],
      "seller_experience": "ADVANCED",
      "seller_reputation": {
    	"level_id": null,
    	"power_seller_status": null,
    	"transactions": {
      	"period": "historic",
      	"total": 0,
      	"completed": 0,
      	"canceled": 0,
      	"ratings": {
        	"positive": 0,
        	"negative": 0,
        	"neutral": 0
      	}
    	}
      },
      "buyer_reputation": {
    	"canceled_transactions": 0,
    	"transactions": {
      	"period": "historic",
      	"total": null,
      	"completed": null,
      	"canceled": {
        	"total": null,
        	"paid": null
      	},
      	"unrated": {
        	"total": null,
        	"paid": null
      	},
      	"not_yet_rated": {
        	"total": null,
        	"paid": null,
        	"units": null
      	}
    	},
    	"tags": [
    	]
      },
      "status": {
    	"site_status": "active",
    	"list": {
      	"allow": true,
      	"codes": [
      	],
      	"immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
      	}
    	},
    	"buy": {
      	"allow": true,
      	"codes": [
      	],
      	"immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
      	}
    	},
    	"sell": {
      	"allow": true,
      	"codes": [
      	],
      	"immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
      	}
    	},
    	"billing": {
          "allow": true,
      	"codes": [
      	]
    	},
    	"mercadopago_tc_accepted": true,
    	"mercadopago_account_type": "personal",
    	"mercadoenvios": "not_accepted",
    	"immediate_payment": false,
    	"confirmed_email": false,
    	"user_type": "eventual",
    	"required_action": ""
      },
      "credit": {
    	"consumed": 100,
    	"credit_level_id": "MLA1"
      }
    }

    Get data from other users

    If you want to query third-party user data, you will be able to identify two information levels: public data, which you can find navigating the MercadoLibre profile of any other user, e.g.: http://perfil.mercadolibre.com.ar/TETE2870021, and private data, which will be hidden unless you have user permission and a valid token to work on his/her behalf.
    In both cases, first you need to know the user ID.

    How to get a user’s ID?

    If you do not have the ID but you know the user’s nickname and the site he/she belongs to, you will be able to get their ID using the following search:

    Call:

    https://api.mercadolibre.com/sites/{Site_id}/search?nickname={Nickname}

    Example:

    https://api.mercadolibre.com/sites/MLA/search?nickname=TETE2870021

    Response:

    {
      "site_id": "MLA",
      "seller": {
    	"id": 202593498,
    	"seller_reputation": {
      	"power_seller_status": null
    	},
    	"real_estate_agency": false,
    	"car_dealer": false,
    	"tags": [
    	]
      },
      "paging": {
    	"total": 2,
    	"offset": 0,
    	"limit": 50
      },
      "results": [
    	{
      	"id": "MLA598903377",
      	"site_id": "MLA",
      	"title": "Test Item - Nao Ofertar",
      	"subtitle": null,
      	"seller": {
        	"id": 202593498,
        	"power_seller_status": null,
        	"car_dealer": false,
        	"real_estate_agency": false,
        	"tags": [
        	]
      	},
      	"price": 200,
      	"currency_id": "ARS",
      	"available_quantity": 1,
      	"sold_quantity": 0,
      	"buying_mode": "buy_it_now",
      	"listing_type_id": "bronze",
      	"stop_time": "2016-03-06T17:16:49.000Z",
      	"condition": "new",
      	"permalink": "http://articulo.mercadolibre.com.ar/MLA-598903377-test-item-nao-ofertar-_JM",
      	"thumbnail": "http://mla-s2-p.mlstatic.com/546311-MLA20539702714_012016-I.jpg",
      	"accepts_mercadopago": true,
      	"installments": {
        	"quantity": 6,
        	"amount": 42.33,
        	"currency_id": "ARS"
      	},
      	"address": {
        	"state_id": "AR-C",
        	"state_name": "Capital Federal",
        	"city_id": "",
        	"city_name": "Palermo"
      	},
      	"shipping": {
        	"free_shipping": false,
        	"mode": "not_specified"
      	},
      	"seller_address": {
        	"id": 175597910,
        	"comment": "",
        	"address_line": "",
        	"zip_code": "",
        	"country": {
          	"id": "AR",
          	"name": "Argentina"
        	},
        	"state": {
          	"id": "AR-C",
          	"name": "Capital Federal"
        	},
        	"city": {
          	"id": "",
          	"name": "Palermo"
       	 },
        	"latitude": -34.571148,
        	"longitude": -58.423298
      	},
      	"attributes": [
      	],
      	"original_price": null,
      	"category_id": "MLA374515",
      	"official_store_id": null
    	},
    	{
      	"id": "MLA599121050",
      	"site_id": "MLA",
      	"title": "Item De Test - No Ofertar",
      	"subtitle": null,
      	"seller": {
        	"id": 202593498,
        	"power_seller_status": null,
        	"car_dealer": false,
        	"real_estate_agency": false,
        	"tags": [
        	]
      	},
      	"price": 1000,
      	"currency_id": "ARS",
      	"available_quantity": 1,
      	"sold_quantity": 0,
      	"buying_mode": "buy_it_now",
      	"listing_type_id": "bronze",
      	"stop_time": "2016-03-07T20:12:41.000Z",
      	"condition": "new",
      	"permalink": "http://articulo.mercadolibre.com.ar/MLA-599121050-item-de-test-no-ofertar-_JM",
      	"thumbnail": "http://mla-s2-p.mlstatic.com/493311-MLA20538550251_012016-I.jpg",
      	"accepts_mercadopago": true,
      	"installments": {
        	"quantity": 6,
            "amount": 211.65,
        	"currency_id": "ARS"
      	},
      	"address": {
        	"state_id": "AR-C",
        	"state_name": "Capital Federal",
        	"city_id": "",
        	"city_name": "Palermo"
      	},
      	"shipping": {
        	"free_shipping": false,
        	"mode": "not_specified"
      	},
      	"seller_address": {
        	"id": 175597910,
        	"comment": "",
        	"address_line": "",
        	"zip_code": "",
        	"country": {
          	"id": "AR",
          	"name": "Argentina"
        	},
        	"state": {
      	    "id": "AR-C",
          	"name": "Capital Federal"
        	},
        	"city": {
          	"id": "",
          	"name": "Palermo"
        	},
        	"latitude": -34.571148,
        	"longitude": -58.423298
      	},
      	"attributes": [
      	],
      	"original_price": null,
      	"category_id": "MLA90105",
      	"official_store_id": null
    	}
      ],
      "secondary_results": [
      ],
      "related_results": [
      ],
      "sort": {
    	"id": "relevance",
    	"name": "More relevant"
      },
      "available_sorts": [
    	{
     	 "id": "price_asc",
      	"name": "Lower price"
    	},
    	{
      	"id": "price_desc",
      	"name": "Higher price"
    	}
      ],
      "filters": [
      ],
      "available_filters": [
    	{
      	"id": "category",
      	"name": "Categories",
      	"type": "text",
    	  "values": [
        	{
          	"id": "MLA1648",
          	"name": "Computación",
          	"results": 1
        	},
        	{
          	"id": "MLA1430",
          	"name": "Ropa y Accesorios",
          	"results": 1
        	}
      	]
    	},
    	{
      	"id": "state",
      	"name": "Location",
      	"type": "text",
      	"values": [
        	{
          	"id": "TUxBUENBUGw3M2E1",
          	"name": "Capital Federal",
          	"results": 2
        	}
      	]
    	},
    	{
      	"id": "accepts_mercadopago",
     	 "name": "MercadoPago filter",
      	"type": "boolean",
      	"values": [
        	{
          	"id": "yes",
          	"name": "With MercadoPago",
          	"results": 2
        	}
      	]
    	},
    	{
      	"id": "installments",
      	"name": "Pago",
      	"type": "text",
      	"values": [
        	{
          	"id": "yes",
          	"name": "Installments",
          	"results": 2
        	},
        	{
          	"id": "no_interest",
          	"name": "Sin interés",
          	"results": 0
        	}
      	]
    	},
    	{
      	"id": "condition",
      	"name": "Condition filter",
      	"type": "text",
      	"values": [
        	{
          	"id": "new",
          	"name": "New",
          	"results": 2
        	}
      	]
    	},
    	{
      	"id": "buying_mode",
      	"name": "Buying mode filter",
      	"type": "text",
      	"values": [
        	{
          	"id": "buy_it_now",
          	"name": "Buy it now",
          	"results": 2
        	}
      	]
    	},
    	{
      	"id": "has_pictures",
      	"name": "Items with images filter",
      	"type": "boolean",
      	"values": [
        	{
          	"id": "yes",
          	"name": "With pictures",
          	"results": 2
        	}
      	]
    	}
      ]
    }

    Query a user’s public information

    Now, as you already know the user ID, you can make a call to the users’ resource as shown below in order to get the public information of the user you want:

    Call:

    curl GET -X  https://api.mercadolibre.com/users/{User_id}

    Example:

    GET -X  https://api.mercadolibre.com/users/202593498

    Response:

    {
      "id": 202593498,
      "nickname": "TETE2870021",
      "registration_date": "2016-01-06T11:31:42.000-04:00",
      "country_id": "AR",
      "address": {
        "state": "AR-C",
    	"city": "Palermo"
      },
      "user_type": "normal",
      "tags": [
    	"normal",
    	"test_user",
    	"user_info_verified"
      ],
      "logo": null,
      "points": 100,
      "site_id": "MLA",
      "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
      "seller_reputation": {
    	"level_id": null,
    	"power_seller_status": null,
    	"transactions": {
      	"period": "historic",
      	"total": 0,
      	"completed": 0,
      	"canceled": 0,
      	"ratings": {
        	"positive": 0,
        	"negative": 0,
        	"neutral": 0
      	}
    	}
      },
      "buyer_reputation": {
    	"tags": [
    	]
      },
      "status": {
    	"site_status": "active"
      }
    }

    Get private information of a user who accepted the use of my application

    In order to get a user’s private data, you just need to know the user’s ACCESS_TOKEN at the end of the call that you made before.

    Call:

    curl GET -X  https://api.mercadolibre.com/users/{User_id}?access_token=¢ACCESS_TOKEN

    Example:

    curl GET -X  https://api.mercadolibre.com/users/202593498?access_token=¢ACCESS_TOKEN

    Response:

    {
      "id": 202593498,
      "nickname": "TETE2870021",
      "registration_date": "2016-01-06T11:31:42.000-04:00",
      "first_name": "Test",
      "last_name": "Test",
      "country_id": "AR",
      "email": "test_user_50698062@testuser.com",
      "identification": {
    	"type": "DNI",
    	"number": "1111111"
      },
      "address": {
    	"state": "AR-C",
    	"city": "Palermo",
    	"address": "Test Address 123",
    	"zip_code": "1414"
      },
      "phone": {
    	"area_code": "01",
    	"number": "1111-1111",
    	"extension": "",
    	"verified": false
      },
      "alternative_phone": {
    	"area_code": "",
    	"number": "",
    	"extension": ""
      },
      "user_type": "normal",
      "tags": [
    	"normal",
    	"test_user",
    	"user_info_verified"
      ],
      "logo": null,
      "points": 100,
      "site_id": "MLA",
      "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
      "shipping_modes": [
    	"custom",
    	"not_specified"
      ],
      "seller_experience": "ADVANCED",
      "seller_reputation": {
    	"level_id": null,
    	"power_seller_status": null,
    	"transactions": {
      	"period": "historic",
      	"total": 0,
      	"completed": 0,
      	"canceled": 0,
      	"ratings": {
        	"positive": 0,
        	"negative": 0,
        	"neutral": 0
      	}
    	}
      },
      "buyer_reputation": {
    	"canceled_transactions": 0,
    	"transactions": {
      	"period": "historic",
      	"total": null,
      	"completed": null,
      	"canceled": {
        	"total": null,
        	"paid": null
      	},
      	"unrated": {
        	"total": null,
        	"paid": null
      	},
      	"not_yet_rated": {
        	"total": null,
        	"paid": null,
        	"units": null
      	}
    	},
    	"tags": [
    	]
      },
      "status": {
    	"site_status": "active",
    	"list": {
      	"allow": true,
      	"codes": [
      	],
      	"immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
        }
      },
    	"buy": {
      	"allow": true,
      	"codes": [
      	],
          "immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
      	}
    	},
    	"sell": {
      	"allow": true,
      	"codes": [
      	],
      	"immediate_payment": {
        	"required": false,
        	"reasons": [
        	]
      	}
        },
    	"billing": {
      	"allow": true,
      	"codes": [
      	]
    	},
    	"mercadopago_tc_accepted": true,
    	"mercadopago_account_type": "personal",
    	"mercadoenvios": "not_accepted",
    	"immediate_payment": false,
    	"confirmed_email": false,
    	"user_type": "eventual",
    	"required_action": ""
      },
      "credit": {
    	"consumed": 100,
    	"credit_level_id": "MLA1"
      }
    }

    As you can see, this time you got more information about the user: full name, e-mail, telephone, address, etc. Please do not disclose this data since it may jeopardize the user.

    Update user’s information

    You can use our resources to update your user information after registration. This is a common issue, since at this instance you’re not asked to fill your address or personal identification, but you need to have them filled or you’ll be unable to list items on MercadoLibre.
    To update your user information, follow the example:

    Example:

    curl -X PUT -H "Content-Type: application/json" -d
    {
    "identification_type": "DNI",
    "identification_number": "33333333",
    "address": "Triunvirato 5555",
    "state":"AR-C",
    "city":"Capital Federal",
    "zip_dode": "1431",
    "phone":{
            "area_code":"011",
            "number":"4444-4444",
            "extension":"001"
        	},
    "first_name":"Pedro",
    "last_name": "Picapiedras",
    "company":{
              "corporate_name":"Acme",
              "brand_name":"Acme Company"
          	},
    "mercadoenvios": "accepted"
    }
    
    https://api.mercadolibre.com/users/{User_id}?access_token=

    Congratulations, you’ve updated your user Information. Remember to only send the fields you want to update.

    User seller with Mercado Pago mandatory

    If you want all your operations are exclusively through Mercado Pago you must indicate in your user information. To disable the option agree with the seller.

    PUT:

     curl -XPUT -H "Content-type: application/json" -d 
    
    '{
        "reason": "by_user"
    }'
    
    https://api.mercadolibre.com/users/{user_id}/immediate_payment?access_token=$ACCESS_TOKEN

    To delete the option only accept Mercado Pago:

     curl -XDELETE 
    
    'https://api.mercadolibre.com/users/{user_id}/immediate_payment/by_user?access_token=$ACCESS_TOKEN

    Common error codes

    206 – Partial content: in some cases Users API resource will return a 206 – Partial Content code. This is going to happen when the request to some of the data fails (for example, user reputation), to make you aware that you’re getting an incomplete response.


    Next topic: Manage MercadoLibre official stores.

    Please rate this

    Visits resource

    This API retrieves information about visits on MercadoLibre items VIPs (View Product Page).
    You can query data by time windows and sites. Remember that relistings inherit the item historic visits of it’s parent_item, no matter how many times they are relisted.

    Parameter description

    TypeParameterDescription
    IntegerUser_idUser id.
    StringItem_idItem id.
    DateDate_fromDate, ISO format, that defines the start of the query.
    DateEndingOptional. Date, ISO format, which states the time of completion of the sample, by default it’s the current date and time.
    StringUnitQuery unit, possible values: [ “day”].
    Integertotal_vistisTotal visits on an item.
    Arrayvisits_detailVisits detailed by country and site
    ArrayresultsVisits detail grouped by time intervals. The length is defined by the parameter Unit.


    Total visits by user

    Retrieves the total visits on every item of an user, by site and between date ranges. This also applies for visits on other MercadoLibre sites like TuCarro, TuInmueble, Autoplaza, etc.
    Resource:

    https://api.mercadolibre.com/users/{User_id}/items_visits?date_from={Date_from}&date_to={Date_to}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/users/52366166/items_visits?date_from=2014-06-01T00:00:00.000-00:00&date_to=2014-06-10T00:00:00.000-00:00’

    Response:

    {
    "user_id": 52366166,
    "date_from": "2014-06-01T00:00:00.000-00:00",
    "date_to": "2014-06-10T00:00:00.000-00:00",
    "total_visits": 120,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 59,
    },
    {
    "company": "tuinmueble",
    "quantity": 61,
    },
    ],
    }


    Total visits by item

    Retrieves total visits on an item between date ranges and by site.
    Resource:

    https://api.mercadolibre.com/items/{Items_id}/visits?date_from={Date_from}&date_to={Date_to}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/items/MCO496961166/visits?date_from=2014-04-14T00:00:00.000-03:00&date_to=2014-05-30T23:59:59.999-03:00’

    Response:

    {
    "item_id": "MCO496961166",
    "date_from": "2014-04-14T00:00:00.000-03:00",
    "date_to": "2014-05-30T23:59:59.999-03:00",
    "total_visits": 152,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 70,
    },
    {
    "company": "tucarro",
    "quantity": 82,
    },
    ],
    }


    Total visits by item MULTI-GET

    Retrieves the total visitas according to an array of items concatenated within a date range, by site.
    Resource:

    https://api.mercadolibre.com/items/visits?ids={Id1, Id2}date_from={Date_from}&date_to={Date_to}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/items/visits?ids=MLA506635149,MLA506634973,MLA503004418&date_from=2014-06-01T00:00:00.000-00:00&date_to=2014-06-10T00:00:00.000-00:00’

    Response:

    [
    {
    "item_id": "MLA506635149",
    "date_from": "2014-06-01T00:00:00.000-00:00",
    "date_to": "2014-06-10T00:00:00.000-00:00",
    "total_visits": 134,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 134,
    },
    ],
    },
    {
    "item_id": "MLA506634973",
    "date_from": "2014-06-01T00:00:00.000-00:00",
    "date_to": "2014-06-10T00:00:00.000-00:00",
    "total_visits": 122,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 122,
    },
    ],
    },
    {
    "item_id": "MLA503004418",
    "date_from": "2014-06-01T00:00:00.000-00:00",
    "date_to": "2014-06-10T00:00:00.000-00:00",
    "total_visits": 355,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 355,
    },
    ],
    },
    ]


    Dated visits by user

    Retrieves visits on every item of an user for a certain time window, by site. The information detail it’s grouped by time intervals.
    Resource:

    https://api.mercadolibre.com/users/{User_id}/items_visits/time_window?last={Last}&unit={Unit}&ending={Ending}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/users/52366166/items_visits/time_window?last=2&unit=day’

    Response:

    {
    "user_id": 52366166,
    "total_visits": 2083,
    "date_from": "2014-06-10T04:00:00Z",
    "date_to": "2014-06-12T04:00:00Z",
    "last": 2,
    "unit": "day",
    "results": [
    {
    "date": "2014-06-10T04:00:00Z",
    "total": 1637,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 1637,
    },
    ],
    },
    {
    "date": "2014-06-11T04:00:00Z",
    "total": 446,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 446,
    },
    ],
    },
    ],
    }


    Dated visits by item

    Retrieves visits on an item for a certain time window, by site. The information detail it’s grouped by time intervals.
    Resource:

    https://api.mercadolibre.com/users/{Item_id}/visits/time_window?last={Last}&unit={Unit}&ending={Ending}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/items/MLA506635149/visits/time_window?last=2&unit=day&ending=2014-06-11’

    Response:

    {
    "item_id": "MLA506635149",
    "total_visits": 15,
    "date_from": "2014-06-09T04:00:00Z",
    "date_to": "2014-06-11T04:00:00Z",
    "last": 2,
    "unit": "day",
    "results": [
    {
    "date": "2014-06-09T04:00:00Z",
    "total": 10,
    "visits_detail": - [
    {
    "company": "mercadolibre",
    "quantity": 10,
    },
    ],
    },
    {
    "date": "2014-06-10T04:00:00ZZ",
    "total": 5,
    "visits_detail": - [
    {
    "company": "mercadolibre",
    "quantity": 5,
    },
    ],
    },
    ],
    }


    Dated visits by item MULTI-GET

    Retrieves the visits according to an item array (max 50), by site. The information detail it’s grouped by time intervals.
    Resource:

    https://api.mercadolibre.com/items/visits/time_window?ids={Id1, Id2}last={Last}&unit={Unit}&ending={Ending}

    Example:

    curl -X GET ‘https://api.mercadolibre.com/items/visits/time_window?ids=MLA506635149,MLA506634973,MLA503004418&last=3&unit=day‘

    Response:

    [
    {
    "item_id": "MLA506635149",
    "total_visits": 0,
    "date_from": "2015-08-30T04:00:00Z",
    "date_to": "2015-09-02T04:00:00Z",
    "last": 3,
    "unit": "day",
    "results": [
    {
    "date": "2015-08-30T04:00:00Z",
    "total": 0,
    "visits_detail": []
    },
    {
    "date": "2015-08-31T04:00:00Z",
    "total": 0,
    "visits_detail": []
    },
    {
    "date": "2015-09-01T04:00:00Z",
    "total": 0,
    "visits_detail": []
    }
    ]
    },
    {
    "item_id": "MLA506634973",
    "total_visits": 0,
    "date_from": "2015-08-30T04:00:00Z",
    "date_to": "2015-09-02T04:00:00Z",
    "last": 3,
    "unit": "day",
    "results": [
    {
    "date": "2015-08-30T04:00:00Z",
    "total": 0,
    "visits_detail": []
    },
    {
    "date": "2015-08-31T04:00:00Z",
    "total": 0,
    "visits_detail": []
    },
    {
    "date": "2015-09-01T04:00:00Z",
    "total": 0,
    "visits_detail": []
    }
    ]
    },
    {
    "item_id": "MLA503004418",
    "total_visits": 169,
    "date_from": "2015-08-30T04:00:00Z",
    "date_to": "2015-09-02T04:00:00Z",
    "last": 3,
    "unit": "day",
    "results": [
    {
    "date": "2015-08-30T04:00:00Z",
    "total": 42,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 42
    }
    ]
    },
    {
    "date": "2015-08-31T04:00:00Z",
    "total": 38,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 38
    }
    ]
    },
    {
    "date": "2015-09-01T04:00:00Z",
    "total": 89,
    "visits_detail": [
    {
    "company": "mercadolibre",
    "quantity": 89
    }
    ]
    }
    ]
    }
    ]

    If you need more information about relistings, please check Relist Your Items tutorial.

    Please rate this

    Ship products

    The Mercadolibre’s shipping department handles all the information about how a product goes from one user to another.

    Contents:

    Shipping modes

    As a quick summary, listings in MercadoLibre has 4 different shipping modes (please check what modes are available in your country):

    • not_specified: It means the seller did not specify any shipping price for their items and the buyer has to get in contact with the seller to agree on a shipping option and price for the purchase.
    • custom: Sellers can include a table of up to 10 shipping costs on an item, and the buyer must provide that number on the checkout process.
    • me1: (Mercado Envios mode 1)This method offers a shipping calculator to calculate the shipping cost for every order allowing the seller to choose the shipping service of his choice, but choosing a carrier and tracking number managment is handled by the seller.
    • me2 (Mercado Envios mode 2)This method provides the seller a prepaid label and tracking numbercode with a local predefined carrier in each country. Seller does not have to worry with choosing a carrier and handling the tracking number. This is the most recommended mode to use since it brings an excellent experience for buyers and sellers. the shipping company chosen by ML.

    Country specifications

    BrasilArgentinaMéxicoColombiaChile
    Modes

    ME2, ME1, custom, not_specifiedME2, ME1, custom, not_specifiedME2, custom, not_specifiedME2, custom, not_specifiedME2, custom, not_specified
    Free ShippingYesYesYesYesYes
    Free Shipping region exclusionYes, Norte and NordesteNoNoNoNo
    CarrierCorreiosOcaDHLServiEntregaChilexpress
    Dimensions restrictions (C) Minimum 16cm Máximum 105cm – (L) Minimum 11cm Máximum 105cm – (A) Minimum 2cm Máximum 105 cmNo restrictions120cm40x40x40cm80x80x120cm
    Maximum weight30kg25kg70kg30kg50kg

    Notes:

    • Mercado Envios mode 2 is available for sellers from Argentina, Brazil, Colombia and Mexico who want to opt-in to participate in the program.
    • Mercado Envios mode 1 is only available for selected sellers from Argentina and Brazil who’ve reached a commercial agreement with MercadoLibre and are integrated.

    How do I know a user’s mode?

    You can check if the user is already allowed to list with ME1 or ME2 shipping mode with a GET to the users API.

    GET https://api.mercadolibre.com/users/:user_id?access_token=



    This will return a lot of information about the authenticated user, one of which is the shipping_modes attribute.
    Response:

    "shipping_modes":[
        "custom",
        "not_specified",
        "me1"
    ]



    Also there are some restrictions on certain categories. Use the shipping_modes resource to verify if a seller can list an item with me2 shipping for a given category. The response indicates if me2 mode is available and the shipping methods that can be used.

    URL

    https://api.mercadolibre.com/users/:user_id/shipping_modes?category_id=MLB39373

    Response:

    [
      {
        "mode": "custom",
        "shipping_attributes": {
          "dimensions": "optional",
          "costs": "required",
          "free": {
            "methods": "not_allowed",
            "accepted_methods": [
            ],
            "rules": [
            ]
          },
          "local_pick_up": "optional"
        }
      },
      {
        "mode": "not_specified",
        "shipping_attributes": {
          "dimensions": "optional",
          "costs": "not_allowed",
          "free": {
            "methods": "not_allowed",
            "accepted_methods": [
            ],
            "rules": [
            ]
          },
          "local_pick_up": "optional"
        }
      },
      {
        "mode": "me2",
        "shipping_attributes": {
          "dimensions": "optional",
          "costs": "not_allowed",
          "free": {
            "methods": "optional",
            "accepted_methods": [
              73328,
              73330
            ],
            "rules": [
              {
                "free_mode": "country",
                "value": null,
                "default": true,
                "free_shipping_flag": true
              }
            ]
          },
          "local_pick_up": "optional"
        }
      }
    ]



    By default all users are allowed to list “not specified” and “custom” shipping. If a user is marked with either me1 or me2 you can see it as an option in shipping modes.

    Shipping preferences

    There’s also a public resource that will allow you to know any user shipping preferences in case you need. Just make the following call:
    Call:

     curl -X GET https://api.mercadolibre.com/users/:user_id/shipping_preferences
    {
        "custom_calculator": false, 
        "free_configurations": [
            {
                "condition": {
                    "type": "all", 
                    "value": null
                }, 
                "rule": {
                    "default": true, 
                    "free_mode": "country", 
                    "value": null
                }
            }, 
            {
                "condition": {
                    "type": "all", 
                    "value": null
                }, 
                "rule": {
                    "default": false, 
                    "free_mode": "exclude_region", 
                    "value": [
                        "BR-NO", 
                        "BR-NE"
                    ]
                }
            }
        ], 
        "local_pick_up": false, 
        "mandatory_mode_for_user": [], 
        "modes": [
            "custom", 
            "not_specified", 
            "me2"
        ], 
        "option": "in", 
        "picking_type": null, 
        "services": [
            21, 
            22, 
            23
        ], 
        "site_id": "MLB", 
        "thermal_printer": null, 
        "trusted_user": false
    }



    You’ll be able to check the free shipping configuration (more information later on), modes and other stuff.

    Shipping methods

    Each site has a set of shipping methods available. They have different shipping times and costs. Sellers can offer free shipping in one or both of these methods.
    To see the available methods by site there is a special resource.
    URL for Brazil

    https://api.mercadolibre.com/sites/MLB/shipping_methods
    JSON Response
    {
        "id": 500645,
        "name": "Expresso",
        "status": "active",
        "site_id": "MLB",
        "free_options": [
            "country"
        ]
    },
    {
        "id": 501548,
        "name": "CBT MLB",
        "status": "active",
        "site_id": "MLB",
        "free_options": [
            "country"
        ]
    },
    {
        "id": 100009,
        "name": "Normal",
        "status": "active",
        "site_id": "MLB",
        "free_options": [
            "country"
        ]
    },
    {
        "id": 182,
        "name": "Expresso",
        "status": "active",
        "site_id": "MLB",
        "free_options": [
            "country"
        ]
    }


    Response

    • id – Shipping method ID is used when listing an item with shipping.
    • name – Name of the shipping method
    • site_id – The site ID, the shipping method that it belongs to.
    • free_options –

    Shipping status summary

    Shipping status may vary on the order depending the shipping mode selected for the product. For modes that support automatic tracking and tracking numbers are monitored, like with Mercado Envios mode 2, and mode 1 under some configurations, shipping status will be updated by us, while for custom shipping mode and other configurations of Mercado Envios mode 1, you’ll be responsible for sending a tracking number and update the shipping status. This is not mandatory but we suggest you to do it so you improve your chances of getting better feedback from the buyers.
    Status:
    to_be_agreed
    Shipment will be agreed between the seller and the buyer.
    pending
    Shipments are created with this state.
    handling
    Payment has been received for this shipment.
    ready_to_ship
    Authorization code has been received from carrier.
    shipped
    Carrier has informed shipment departure.
    delivered
    Carrier has informed shipment arrival.
    not_delivered
    Carrier was unable to deliver package.
    cancelled
    Shipment has been cancelled.

    Check full tables of shipping status and it’s substatus.

    Mercado Envios overview

    Mercado Envios is our business unit that help sellers with lot of facilities to ship their products, actually active on MLA, MLB, MLM, MLC and MCO. As we specified before, there are two Mercado Envios options you can choose: mode 1 and mode 2.

    Differences between ME1 & ME2

    ME1ME2
    Good for big sellers that already deal with a carrier of their choice and have a process that takes care of calculating shipping costs, collect the payment, and printing shipping labels with the sale & shipping information.Best choice for medium & big sellers that need an intermediate to deal the carrier, helps both seller & buyer to keep track of the product, calculates shipping costs and takes care the whole shipping process, collecting the payment and printing shipping labels with all the sale & shipping information.
    Only on MLA, MLC and MLB.Only on MLA, MLB, MLM, MLC & MCO.
    Sellers choose the carrier.We have an agreement with the most trusted carriers of each country and offer sellers pre-paid shipping labels.
    Sellers provide custom package dimensions or use default category standard dimensions.Sellers work with the standard dimensions of each category.
    We calculate and fix shipping costs basing on origin, destination and package dimensions.We calculate and fix shipping costs basing on the origin, destination, price of the item, and package dimensions.
    The seller gets the payment collected for the shipping immediately and takes care of paying the label and the carrier.We take care of collecting the money and paying for the shipping.
    Supports free shipping. Seller takes care of charges for shipping the product.Supports free shipping. We send you a bill to pay charges for shipping the product.
    Sellers are in charge of tracking the product and informing the shipping status to buyers.We keep track of the product and update the shipping status automatically for sellers and buyers.

    Not specified

    If, when you make a POST through Mercado Envíos, the category rejects it and it is added to this choice by default -although the user has not enabled it-, it is posted as item with shipping modes “not_specified”.
    If you don’t send any shipping information for the item, the default will be “not_specified”. Also, if there are no modes that support the given dimensions for your item, you should list under this mode.
    You can make a call to our API with your user_id, the category where you want to list, and your item dimensions to know what shipping modes you have available, if the dimensions are not supported, you’ll only get “not_specified” mode on the response.
    Note: If the category has ME2 they are ignored the dimensions sent.

    Example:

    curl -X GET https://api.mercadolibre.com/users/:user_id/shipping_modes?category_id=MLB74723&dimensions=10x50x100,30001

    Response:

    [
       {
          "mode":"not_specified",
          "shipping_attributes":{
             "dimensions":"optional",
             "costs":"not_allowed",
             "accepted_methods":[
    
             ]
          }
       }
    ]


    Local Pick Up

    The local_pick_up attribute enables the option for buyers to choose to pick up the item from the store and not incur shipping costs. Set local_pick_up to true for sellers that offer this option to buyers.


    Next topic: Sync listings


    Related article

    Please rate this

    Product Guide

    On MercadoLibre you can list under different conditions, and then change, pause, relist, and end listings whenever you want. Moreover, you can add other sellers’ listings to favorites, ask and answer questions, share in social media, etc.


    There are different types of listings: on the one hand, we have the products for which you can bid. A bid is placed, a purchase order is created, the parties exchange contact information, a payment is generated, the parties rate each other, end.


    When listing this type of products, you will be able to work with search, question, and answer management systems, manage stock and variations of the same product, and manage sales, shipping and ratings.


    Next topic: Authenticate

    Please rate this

    Category Dump

    What is the Category Tree

    The category tree is a structure where MercadoLibre organizes its listings. Each country has its own category tree that is different from each other. Listings can only be posted on the leaf categories of the tree.

    Category Tree changes

    Sometimes, the category tree changes because a new category is created, or an existing category is split in two or more categories. All the listings posted in the old category are automatically moved to the new category.

    Why should I synchronize the Category Tree?

    It is recommended making a dump of the whole category tree for a given country site for offline processing on a daily basis, so you are up to date with new categories. It is very useful when you are giving your user the possibility of mapping categories from his side to MercadoLibre’s category tree.

    Working with Category Tree dump

    This API returns the category tree in JSON format within a gzip-encoded response.
    To get the categories for Brazil, for example, use this URL:

    curl https://api.mercadolibre.com/sites/MLB/categories/all  > categoriesMLB.gz


    This URL contains 2 headers that can be used to check when the last dump was generated.

    • X-Content-Created: contains the date of the last generation.
    • X-Content-MD5: contains the MD5 checksum of the last generation.


    ~$ curl -I  https://api.mercadolibre.com/sites/MLB/categories/all
    HTTP/1.1 200 OK
    Server: nginx/1.0.4
    Date: Tue, 24 Jul 2012 15:14:58 GMT
    Content-Type: application/json;charset=UTF-8
    Connection: keep-alive
    X-MLAPI-Version: 1.9.5
    Content-Encoding: gzip
    X-Content-Created: 2012-07-24T14:00:59.716Z
    X-Content-MD5: 943541196986770119b4af1e66bda2dc

    Category dump with attributes

    Since categories have attributes of their own that you also need to map, by making the following call you can get a file that contains the category tree with each of it’s attributes.
    Example:

    curl https://api.mercadolibre.com/sites/MLA/categories/all?withAttributes=true > mla.gz


    Please rate this

    List products

    Now that you went through authentication, users and categories, we think you are ready to list your first listing. Follow this tutorial to learn how to do it.

    Contents:

     

    Basics

    On MercadoLibre’s API, listings are items that contains products and other attributes you can sell or buy. Users can’t exchange contact information right away on them, so every time there’s an intention of buying a product, potential buyers are able to make as many questions they want on the item and when they’re ready, they need to make an offer on the seller’s product, so an order is created for both seller and buyer detailing the transaction as a sale or a purchase for each one, and that’s when contact information is visible automatically between those users.

    Listing Results

    Each item you list will appear in the listing results of a given product search. For example, when a user search for the query “ipod”, as a result he will get a list of all items related. Your item can be in that list.
    When someone clicks on an item, the item details page is displayed, showing all the information about the item that was provided at the time of listing, keep reading to know more about it.

    Item details page

    When a user chooses an item from the result, this page displays the following item details:

    • Item_id
    • Title
    • Category
    • Pictures
    • Price
    • City
    • Sold quantity
    • Questions
    • Seller’s reputation
    • Detailed description

    Item Fields

    Let’s see a regular item in detail. This is easy since you only need to know the item_id associated to the product, and since it’s public you can get it from the item’s details page on the top of the page, like in the example picture. You just need to add the site_id before the number and that’s it. Now you can call the Items resource to get all the related information:

    Call:

    curl - X GET https://api.mercadolibre.com/items/{Item_id}

    Example:

    curl - X GET https://api.mercadolibre.com/items/MLA600190449

    Response:

    {
      "id": "MLA600190449",
      "site_id": "MLA",
      "title": "Iphone 6 64gb Space Gray Liberado",
      "subtitle": null,
      "seller_id": 118617944,
      "category_id": "MLA352543",
      "official_store_id": null,
      "price": 16550,
      "base_price": 16550,
      "original_price": null,
      "currency_id": "ARS",
      "initial_quantity": 2,
      "available_quantity": 2,
      "sold_quantity": 0,
      "buying_mode": "buy_it_now",
      "listing_type_id": "bronze",
      "start_time": "2016-01-13T18:10:29.000Z",
      "stop_time": "2016-03-13T18:10:29.000Z",
      "condition": "new",
      "permalink": "http://articulo.mercadolibre.com.ar/MLA-600190449-iphone-6-64gb-space-gray-liberado-_JM",
      "thumbnail": "http://mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-I.jpg",
      "secure_thumbnail": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-I.jpg",
      "pictures": [
        {
          "id": "873411-MLA20547233702_012016",
          "url": "http://mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-O.jpg",
          "size": "225x225",
          "max_size": "225x225",
          "quality": ""
        },
        {
          "id": "234411-MLA20547233720_012016",
          "url": "http://mla-s1-p.mlstatic.com/234411-MLA20547233720_012016-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/234411-MLA20547233720_012016-O.jpg",
          "size": "259x194",
          "max_size": "259x194",
          "quality": ""
        },
        {
          "id": "768311-MLA20547233735_012016",
          "url": "http://mla-s1-p.mlstatic.com/768311-MLA20547233735_012016-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/768311-MLA20547233735_012016-O.jpg",
          "size": "300x168",
          "max_size": "300x168",
          "quality": ""
        }
      ],
      "video_id": null,
      "descriptions": [
        {
          "id": "MLA600190449-1007729488"
        }
      ],
      "accepts_mercadopago": true,
      "non_mercado_pago_payment_methods": [
      ],
      "shipping": {
        "mode": "me2",
        "local_pick_up": true,
        "free_shipping": true,
        "free_methods": [
          {
            "id": 73328,
            "rule": {
              "free_mode": "country",
              "value": null
            }
          }
        ],
        "dimensions": null,
        "tags": [
        ]
      },
      "international_delivery_mode": "none",
      "seller_address": {
        "id": 138834162,
        "comment": "",
        "address_line": "",
        "zip_code": "",
        "city": {
          "id": "TUxBQ05FVXF1ZW4",
          "name": "Neuquén"
        },
        "state": {
          "id": "AR-Q",
          "name": "Neuquén"
        },
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "latitude": -38.95628353,
        "longitude": -68.12749595,
        "search_location": {
          "neighborhood": {
            "id": "",
            "name": ""
          },
          "city": {
            "id": "TUxBQ05FVXF1ZW4",
            "name": "Neuquén"
          },
          "state": {
            "id": "TUxBUE5FVW4xMzMzNQ",
            "name": "Neuquén"
          }
        }
      },
      "seller_contact": null,
      "location": {
      },
      "geolocation": {
        "latitude": -38.96055205,
        "longitude": -68.12525497
      },
      "coverage_areas": [
      ],
      "attributes": [
      ],
      "listing_source": "",
      "variations": [
      ],
      "status": "active",
      "sub_status": [
      ],
      "tags": [
      ],
      "warranty": null,
      "catalog_product_id": null,
      "parent_item_id": null,
      "differential_pricing": null,
      "deal_ids": [
      ],
      "automatic_relist": false,
      "date_created": "2016-01-13T18:10:29.000Z",
      "last_updated": "2016-01-13T18:26:54.000Z"
    }

    Defining attributes

    Some of the fields are mandatory when you create an item, while some others can be skipped or will be automatically added to the item.They will define how the item is displayed, how buyers can purchase it and the position on search results among other variables.

    Title

    Title is a mandatory attribute and is the key for buyers to find your product, for this reason you should be as specific as possible.
    The best way to build a title is name + brand + model + technical specifications and characteristics + additional services. Separate words with spaces, don’t use symbols or punctuation signs. Check you are not misspelling any words. For example: Ipod Touch Apple 16gb 5 Geração.

    Description

    A detailed description will improve your chances to sell a product and will save time from answering questions. It can be a text-only description or you can add your own personalized HTML. There are some considerations when working with descriptions, for example, it’s not allowed posting a description with contact information. If you are interested in increasing your knowledge about this topic, check our descriptions guide.

    Condition

    When listing an item you need to declare if the condition is new, used or not_specified. This attribute is mandatory to complete a list operation.

    Available quantity

    This attribute defines the stock, that’s the number of products available for selling on this item. The highest value is defined by the chosen listing type. See more details in the listing type section.

    Pictures

    Nice pictures can make an item more appealing and give buyers a better idea of the item’s appearance. Basically, you should add an array of up to six URL pictures on the Json.

    {
     ....
     "pictures":[
      {"source":"http://yourServer/path/to/your/picture.jpg"},
      {"source":"http://yourServer/path/to/your/otherPicture.gif"},
      {"source":"http://yourServer/path/to/your/anotherPicture.png"}
     ]
     ...
    }

    We highly recommend you don’t use slow servers to host your pictures since this can lead to disadvantages when listing.
    You can also add or change pictures to your item here later on. Please read more about this topic to know which kind of pictures are allowed and how to work with them here.

    Category

    Sellers must define a category in MercadoLibre site. This attribute is mandatory and only accepts pre-established ids. For more information read categories guide. To get a category suggestion read this article.

    {
     ....
      "category_id":"MLA12683",
     ...
    }

     

    Price

    This is a mandatory attribute, when you define a new item it must have a price. We suggest you search similar items on our marketplace to know the best price for your products and increase your competitivity. If you defined a price and then you’re not happy with it, you can change it later on, learn to modify items.

    Currency

    Besides price, you need to define a currency. This one is also a mandatory attribute. You need to define it using a pre-established id. Calling our Currencies resource you will know which Id to send.

    Payment methods

    It’s important that you have in consideration which payment methods you have available to work with. This will vary depending on the country you are currently working. Check this guide to know more about it .

    Shipping

    Shipping details are not mandatory, but there are many options to choose, and shipping the products you sell is a competitive advantage. Know more about the shipping options you have here.

    Product Identifiers

    Not a mandatory attribute either and only available for some countries and user types. Know more about it.

    Seller Custom Field

    The seller custom field is not mandatory but is very useful since there aren’t any pre-established values and you can send anything as a String. Most sellers use this field to associate their own SKUs to their products, to identify the product sold on the order.
    Example:

    curl -X PUT -d '{"seller_custom_field": "21000093"}' https://api.mercadolibre.com/items/MLA599074368?access_token=¢ACCESS_TOKEN

    Listing type

    This is another case of a mandatory attribute that only accepts pre-defined values and is very important for you to understand about it.
    There are different listing types available for each country. You should make a mixed call through sites and listing_types resources to know which listing_types are supported.

    Call:

    curl https://api.mercadolibre.com/sites/{Site_id}/listing_types

    Example:

    curl https://api.mercadolibre.com/sites/MLA/listing_types

    Response:

    [
      {
        "site_id": "MLA",
        "id": "gold_pro",
        "name": "Oro Premium Full"
      },
      {
        "site_id": "MLA",
        "id": "gold_premium",
        "name": "Oro Premium"
      },
      {
        "site_id": "MLA",
        "id": "gold_special",
        "name": "Oro Profesional"
      },
      {
        "site_id": "MLA",
        "id": "gold",
        "name": "Oro"
      },
      {
        "site_id": "MLA",
        "id": "silver",
        "name": "Plata"
      },
      {
        "site_id": "MLA",
        "id": "bronze",
        "name": "Bronce"
      },
      {
        "site_id": "MLA",
        "id": "free",
        "name": "Gratuita"
      }
    ]

    The fees for selling your item, as well as how it ranks on search results will vary according to the chosen listing type. You will find information about each listing type feeds and characteristics on each country marketplace FAQs, or you can make an API call like this:

    Call:

    curl https://api.mercadolibre.com/sites/{Site_id}/listing_types/{Listing_type}

    Example:

    curl https://api.mercadolibre.com/sites/MLA/listing_types/silver

    Response:

    {
      "id": "silver",
      "not_available_in_categories": [
      ],
      "configuration": {
        "name": "Plata",
        "listing_exposure": "mid",
        "requires_picture": false,
        "max_stock_per_item": 9999,
        "deduction_profile_id": null,
        "differential_pricing_id": null,
        "duration_days": {
          "buy_it_now": 60,
          "auction": 7,
          "classified": null
        },
        "immediate_payment": {
          "buy_it_now": false,
          "auction": false,
          "classified": false
        },
        "mercado_pago": "mandatory",
        "listing_fee_criteria": {
          "min_fee_amount": 5,
          "max_fee_amount": 160,
          "percentage_of_fee_amount": 1,
          "currency": "ARS"
        },
        "sale_fee_criteria": {
          "min_fee_amount": 0,
          "max_fee_amount": 100000000000000000,
          "percentage_of_fee_amount": 7.5,
          "currency": "ARS"
        }
      },
      "exceptions_by_category": [
        {
          "category_id": "MLA1743",
          "category_name": "Autos, Motos y Otros",
          "configuration": {
            "name": "Plata",
            "listing_exposure": "mid",
            "requires_picture": false,
            "max_stock_per_item": 1,
            "deduction_profile_id": null,
            "differential_pricing_id": null,
            "duration_days": {
              "buy_it_now": null,
              "auction": null,
              "classified": 60
            },
            "immediate_payment": {
              "buy_it_now": false,
              "auction": false,
              "classified": false
            },
            "mercado_pago": "not_available",
            "listing_fee_criteria": {
              "min_fee_amount": 147,
              "max_fee_amount": 147,
              "percentage_of_fee_amount": 0,
              "currency": "ARS"
            },
            "sale_fee_criteria": {
              "min_fee_amount": 0,
              "max_fee_amount": 0,
              "percentage_of_fee_amount": 0,
              "currency": null
            }
          },
          "exceptions_by_category": [
          ]
        },
        {
          "category_id": "MLA1459",
          "category_name": "Inmuebles",
          "configuration": {
            "name": "Plata",
            "listing_exposure": "mid",
            "requires_picture": false,
            "max_stock_per_item": 1,
            "deduction_profile_id": null,
            "differential_pricing_id": null,
            "duration_days": {
              "buy_it_now": null,
              "auction": null,
              "classified": 60
            },
            "immediate_payment": {
              "buy_it_now": false,
              "auction": false,
              "classified": false
            },
            "mercado_pago": "not_available",
            "listing_fee_criteria": {
              "min_fee_amount": 147,
              "max_fee_amount": 147,
              "percentage_of_fee_amount": 0,
              "currency": "ARS"
            },
            "sale_fee_criteria": {
              "min_fee_amount": 0,
              "max_fee_amount": 0,
              "percentage_of_fee_amount": 0,
              "currency": null
            }
          },
          "exceptions_by_category": [
          ]
        },
        {
          "category_id": "MLA1540",
          "category_name": "Servicios",
          "configuration": {
            "name": "Básico 365",
            "listing_exposure": "mid",
            "requires_picture": false,
            "max_stock_per_item": 999,
            "deduction_profile_id": null,
            "differential_pricing_id": null,
            "duration_days": {
              "buy_it_now": null,
              "auction": null,
              "classified": 365
            },
            "immediate_payment": {
              "buy_it_now": false,
              "auction": false,
              "classified": false
            },
            "mercado_pago": "not_available",
            "listing_fee_criteria": {
              "min_fee_amount": 727,
              "max_fee_amount": 727,
              "percentage_of_fee_amount": 0,
              "currency": "ARS"
            },
            "sale_fee_criteria": {
              "min_fee_amount": 0,
              "max_fee_amount": 0,
              "percentage_of_fee_amount": 0,
              "currency": null
            }
          },
          "exceptions_by_category": [
          ]
        }
      ]
    }

     

    Listing an item

    You’re ready to list your first item. Notice you’ll need an access_token to make it. If you have questions regarding how to get your access token, please go back to the Authenticate tutorial. Also we recommend using test users to post test items, if you are not familiar with that, please check the generating test users sections here. In addition, we highly recommended you validate the Json you’re sending before making the POST, so you better check out this easy and quick item validation tutorial.
    You can create a Json for your item basing on the following example, or send it as it is, and you’ll be listing a sample product on the site:

    curl -X POST -H "Content-Type: application/json" -d
    '{
    "title":"Item de test - No Ofertar",
    "category_id":"MLA3530",
    "price":10,
    "currency_id":"ARS",
    "available_quantity":1,
    "buying_mode":"buy_it_now",
    "listing_type_id":"gold_special",
    "condition":"new",
    "description": "Item de test - No Ofertar",
    "video_id": "YOUTUBE_ID_HERE",
    "warranty": "12 months",
    "pictures":[
    {"source":"http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"}
    ]
    }'
    https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN

    Note that this example works for MLA (Argentina), if you’re working on any other country you’ll need to replace values for category_id, currency_id and maybe listing_type_id.

    Items with mandatory Mercado Pago

    Items with mandatory Mercado Pago
    Mercado Pago as the only payment method may be referred to as “Mandatory Mercado Pago” or “Immediate Payment.” Therefore, we exclude the “As agreed with the seller” payment choice.
    An item may be marked with immediate payment just like a user or category.
    This scenario applies to:

    List an item with immediate payment

    If you want to get your item paid only with Mercado Pago, you may set that choice when you create a new item, or when you change an active one. To that end, use the tag “inmediate_payment”.

    Example:

    POST
    curl -X POST -H "Content-Type: application/json" -d
    '{
        "title": "Item de test - No Ofertar",
        "category_id": "MLA47392",
        "price": 10,
        "currency_id": "ARS",
        "available_quantity": 1,
        "buying_mode": "buy_it_now",
        "listing_type_id": "gold_special",
        "condition": "new",
        "description": "Item:,  Ray-Ban WAYFARER Gloss Black RB2140 901  Model: RB2140. Size: 50mm. Name: WAYFARER. Color: Gloss Black. Includes Ray-Ban Carrying Case and Cleaning Cloth. New in Box",
        "video_id": "YOUTUBE_ID_HERE",
        "tags": [
            "immediate_payment"
        ],
        "warranty": "12 months by Ray Ban",
        "pictures": [
            {
                "source": "https://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
            },
            {
                "source": "https://en.wikipedia.org/wiki/File:Teashades.gif"
            }
        ]
    }'
    
    https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN
    PUT
    curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d 
    
    ‘{
      "tags": [
            "immediate_payment"
        ],
    }’
    
    
    https://api.mercadolibre.com/items/MLA626369506?access_token=$ACCESS_TOKEN

    Categories with immediate payment

    Some categories within MercadoLibre require Mercado Pago as the only choice. To find out if the category where you wish to list is one of them, check the following:

    curl https://api.mercadolibre.com/sites/categories/{category_id}
    
    "immediate_payment": "required",
        "item_conditions": [
          "new",
          "not_specified",
          "used"
        ],

    If the “immediate_payment” field is set as “required,” Mercado Pago is mandatory. If it reads “optional,” it also accepts “As agreed with the seller”.

    List an official store Item

    Listing an official store item is just like listing any other item, except that you also need to add the official_store_id attribute on the Json.
    Example:

    curl -X POST -H "Content-Type: application/json" -d '{
      "title":"Item de Test -No Ofertar",
      "category_id":"MLA34323",
      "price":10,
      "official_store_id": 60,
      "currency_id":"ARS",
      "available_quantity":1,
      "buying_mode":"buy_it_now",
      "listing_type_id":"bronze",
      "condition":"new",
      "description": "Escultura de cerámica",
      "pictures":[
        {"source":"http://mla-s2-p.mlstatic.com/estatuas-femeninas-130-mts-cemento-gris-21185-MLA20205509642_122014-O.jpg"}
      ]
    }' https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN

    Note: If your store is multi-brand you need to specify the official_store_id of the brand where you want to list that item. Check our Official Stores guide to know more about this topic .

    Common errors in the API response while listing on multi-brand Official Stores

    If you don’t send the official_store_id of the item for a multi-brand Official Store, you’ll get as response the possible IDs you could send with your user:

    "message": "Validation error",
       "error": "validation_error",
       "status": 400,
       "cause": [{
           "code": "item.official_store_id.invalid",
           "message": "Users type brand have to provide one of this [60, 274, 257] official store id"
    If you send an invalid official_store_id for a multibrand Official Store you’ll get:
    {
       "message": "body.invalid_official_store_id",
       "error": "The seller 148829068 is not allowed to use official_store_id 315 on site MLA.",
       "status": 403,
       "cause": []
    }

    If you send an invalid official_store_id for a multibrand Official Store you’ll get:

    {
       "message": "body.invalid_official_store_id",
       "error": "The seller 148829068 is not allowed to use official_store_id 315 on site MLA.",
       "status": 403,
       "cause": []
    }

     

    Error Codes Reference

    ErrorDescriptionPossible solution
    Item.start_time.invalid

    Start time $startTime is only updateable in NOT_YET_ACTIVE ítems.

    Field start time cannot be updated.The parameter start_time can only be updated if the item status is NOT_YET_ACTIVE
    Item.category_id.invalid

    Category $categoryId does not exist.

    Category not found.To see the available categories check the page/sites/$siteId (Check $sideId).
    Item.category_id.invalid

    Is not allowed to post in category $categoryId. Make sure you’re posting in a leaf category

    $category.listing_allowed false.Before post an item, make sure it is allowed to post in the chosen category, see the parameter listing_allowed on /categories/$categoryId.
    Item.buying_mode.invalid

    Category $categoryId only supports listing modes: $category.buyingModes.

    $item.buying_modes is invalidTo see the available listing modes in category check the page /categories/$categoryId in parameter settings:{buying_modes:[…]}.
    Item.attributes.missing_required

    The attributes $requiredAttributeIds are required for category $item.categoryId. Check the attribute is present in the attributes list or in all variation attributes combination.

    Category is required atribute.To see the attributes mandatory on this category check the page /categories/$categoryId/attributes in parameter {tags:{required:{true}}}.
    Item.listing_type_id.invalid

    Invalid listing_type_id.

    $item.listing_type_id is invalid.To see the available listing types in category check the page /categories/$categoryId/listing_types.
    Item.listing_type_id.requiresPicturesItem

    pictures are mandatory for listing type $item.listingTypeId

    Pictures is required.To see if the pictures is mandatory in category check the page /categories/$categoryId/listing_types/silver in parameter requires_picture:{}.
    Item.site_id.invalid

    Site $item.siteId doesn’t exist.

    $item.site_id is invalid.To the available sites, see the page /sites.
    Item.description.max

    The description field is too long. More than $maxSize characters is not allowed.

    Number of characters exceeded.The number of characters in description must be less then 50000 characters.
    Item.pictures.max

    Items in category $item.categoryId cannot exceeds $maxPicturesPerItem pictures.

    Number of images exceeded.To see the quantity of pictures per item in category check the page /categories/$categoryId in parametermax_pictures_per_item:{}.
    Item.attributes.invalid_length

    Invalid value length for attribute $it.attributeId.

    Maximum length is ${attribute.value_max_length}.To see the attributes max_length on this attribute check the page /categories/$categoryId/attributes in parameter value_max_length for attributes with .value_type string or number…
    seller.unable_to_list

    The seller cannot post.

    The seller cannot post for certain cause. Identify the “cause” field in the response.
    • Find out the meaning of “cause” under /users#options, set the status to list, and you will see the meaning.
    • Try to make the first manual posting from My Account in Mercado Libre to see the warnings in the flow.



    Next topic: Ship products



    Related articles:
    Add and configure shipping options for your products.

    Know listing prices and exposures.

    Learn how to add variations for your products.

    Send product identifiers and feature your products on Google Shopping.

    Please rate this

    Set categories for your products

    Categories are a hierarchical set of groups in which items of a similar nature are listed, called “Category Tree”. Categories help buyers find the kind of items they want, as the buyer only needs to look into one or few categories to find items they are interested in. Sellers benefit from the use of categories by the increasing chances of selling due to better and faster access to items by buyers.
    Each site has its own set of categories, which means that Argentina will have a unique set of categories, different from the ones in Brazil.
    Before listing an item, you need to go through the category structure and choose the one in which you want to list. To help you make it, you can download the complete category hierarchy with ID and human-friendly names from our API.

    Contents:

    Categories by Site

    The Sites resource can give you the category structure for a particular country, in this case Argentina.

    https://api.mercadolibre.com/sites/MLA/categories
    "categories": [
    {
    "id": "MLA5725",
    "name": "Accesorios para Vehiculos",
    },
    {
    "id": "MLA1071",
    "name": "Animales y Mascotas",
    },
    {
    "id": "MLA1367",
    "name": "Antigüedades",
    },
    {
    "id": "MLA1743",
    "name": "Autos, Motos y Otros",
    },

    For a second level categories, or information related to specific categories, you have to use the Categories resource, sending the category Id as a URL parameter.
    The next example shows the “Animales y Mascotas” category:

    https://api.mercadolibre.com/categories/MLA1071
    {
    "id": "MLA1071",
    "name": "Animales y Mascotas",
    "permalink": "http://home.mercadolibre.com.ar/animales-y-mascotas",
    "total_items_in_this_category": "30434",
    "path_from_root": [
    {
    "id": "MLA1071",
    "name": "Animales y Mascotas",
    },
    ],
    "children_categories": [
    {
    "id": "MLA1100",
    "name": "Aves",
    "total_items_in_this_category": "1430",
    },
    {
    "id": "MLA1117",
    "name": "Caballos",
    "total_items_in_this_category": "1092",
    },
    .
    .


    As you can see, you get the “path_from_root” and children_categories attributes. Use these attributes to browse through the category tree and find the specific category for your item.
    Categories JSON
    Making a call to a particular category will let you know specific information and description that belongs to it. Following you’ll find the description of some of these attributes.

    curl https://api.mercadolibre.com/categories/MLA9558
    {
    "id": "MLA9558",
    "name": "Givenchy",
    "picture": null,
    "permalink": null,
    "total_items_in_this_category": 706,
    "path_from_root": [
    {
    "id": "MLA1246",
    "name": "Salud y Belleza"
    },
    {
    "id": "MLA1271",
    "name": "Perfumes y Fragancias"
    },
    {
    "id": "MLA1273",
    "name": "Mujer"
    },
    {
    "id": "MLA9558",
    "name": "Givenchy"
    }
    ],
    "children_categories": [
    ],
    "attribute_types": "none",
    "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
    "buy_it_now",
    "auction"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
    "ARS"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
    "used",
    "not_specified",
    "new"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 12,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
    "custom",
    "not_specified",
    "me2",
    "me1"
    ],
    "shipping_options": [
    "custom",
    "carrier"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "articulo",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": null,
    "minimum_price": null
    },
    "meta_categ_id": 38838,
    "attributable": false
    }

    Name

    This attribute shows a human-friendly label. You cannot use this label to search items. If you are interested in searching using categories ids, you can use the following request:

    curl https://api.mercadolibre.com/sites/MLA/search?category=MLA5726



    See more on search items by category article.

    Path from root

    When you are in a category you can know the path from root to the category selected.
    Take a look how MercadoLibre uses this path to show the item’s category:image-category

    Finding the best category for your item

    A leaf category is the last category on the tree and those are the only categories where you can post items.
    Choosing the right category for your item will determine how quickly buyers will find your item and will improve your chances of selling it. For this reason, we highly recommend to use our Category predictor tool before listing an item.

    Maybe some categories won’t have a good suggestions, so you’ll have to make the user of your system to map manually the categories for his products. The simplest process could be to use the Category API and navigate the category tree to detect the best option. You must use only those categories retrieved from the API which don’t have subcategories related.

    Another option could be to find similar items in MercadoLibre and use their category.



    Next topic: List products



    Related articles:

    Use our Category predictor tool before listing an item.

    Learn how to list products.

    Please rate this

    Authentication and Authorization

    Mercado Libre platform allows you to work with our API public and private resources, via HTTP calls using GET, PUT, POST, DELETE and OPTIONS.
    Public resources, such as available sites and categories, can be anonymously accessed, while private resources and user-own actions, such as listing an item, giving feedback or viewing purchase/sale information, require application-based authorization.
    This guide explains the meaning of authentication and the authorization flow to be followed to obtain an access_token (access key to private resources for each user granting authorization to the application – valid for 6 hours).
    For example:
    Without access_token (Public Resource)

    https://api.mercadolibre.com/users/226384143/
    
    {
      "id": 226384143,
      "nickname": "TETE9928972",
      "registration_date": "2016-08-25T11:36:00.000-04:00",
      "country_id": "AR",
      "address": {
        "state": "AR-C",
        "city": "Palermo"
      },
      "user_type": "normal",
      "tags": [
        "normal",
        "test_user",
        "user_info_verified"
      ],
      "logo": null,
      "points": 100,
      "site_id": "MLA",
      "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
      "seller_reputation": {
        "level_id": null,
        "power_seller_status": null,
        "transactions": {
          "period": "historic",
          "total": 1,
          "completed": 1,
          "canceled": 0,
          "ratings": {
            "positive": 0,
            "negative": 0,
            "neutral": 1
          }
        }
      },
      "buyer_reputation": {
        "tags": [
        ]
      },
      "status": {
        "site_status": "active"
      }
    }


    With access_token (Private Resource)

     
     https://api.mercadolibre.com/users/226384143?access_token=$ACCESS_TOKEN
    
    {
      "id": 226384143,
      "nickname": "TETE9928972",
      "registration_date": "2016-08-25T11:36:00.000-04:00",
      "first_name": "Test",
      "last_name": "Test",
      "country_id": "AR",
      "email": "test_user_38730994@testuser.com",
      "identification": {
        "type": "DNI",
        "number": "1111111"
      },
      "address": {
        "state": "AR-C",
        "city": "Palermo",
        "address": "Test Address 123",
        "zip_code": "1414"
      },
      "phone": {
        "area_code": "01",
        "number": "1111-1111",
        "extension": "",
        "verified": false
      },
      "alternative_phone": {
        "area_code": "",
        "number": "",
        "extension": ""
      },
      "user_type": "normal",
      "tags": [
        "normal",
        "test_user",
        "user_info_verified"
      ],
      "logo": null,
      "points": 100,
      "site_id": "MLA",
      "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
      "shipping_modes": [
        "custom",
        "not_specified"
      ],
      "seller_experience": "ADVANCED",
      "bill_data": {
        "accept_credit_note": null
      },
      "seller_reputation": {
        "level_id": null,
        "power_seller_status": null,
        "transactions": {
          "period": "historic",
          "total": 1,
          "completed": 1,
          "canceled": 0,
          "ratings": {
            "positive": 0,
            "negative": 0,
            "neutral": 1
          }
        }
      },
      "buyer_reputation": {
        "canceled_transactions": 0,
        "transactions": {
          "period": "historic",
          "total": null,
          "completed": null,
          "canceled": {
            "total": null,
            "paid": null
          },
          "unrated": {
            "total": null,
            "paid": null
          },
          "not_yet_rated": {
            "total": null,
            "paid": null,
            "units": null
          }
        },
        "tags": [
        ]
      },
      "status": {
        "site_status": "active",
        "list": {
          "allow": true,
          "codes": [
          ],
          "immediate_payment": {
            "required": false,
            "reasons": [
            ]
          }
        },
        "buy": {
          "allow": true,
          "codes": [
          ],
          "immediate_payment": {
            "required": false,
            "reasons": [
            ]
          }
        },
        "sell": {
          "allow": true,
          "codes": [
          ],
          "immediate_payment": {
            "required": false,
            "reasons": [
            ]
          }
        },
        "billing": {
          "allow": true,
          "codes": [
          ]
        },
        "mercadopago_tc_accepted": true,
        "mercadopago_account_type": "personal",
        "mercadoenvios": "not_accepted",
        "immediate_payment": false,
        "confirmed_email": false,
        "user_type": "simple_registration",
        "required_action": ""
      },
      "credit": {
        "consumed": 101.1,
        "credit_level_id": "MLA1"
      }
    }

    Contents:

    Authentication

    Authentication is the act or process of determining or confirming whether someone or something is, in fact, who or what it is declared to be.
    In the case of a person, authentication consists in verifying his/her identity based on one or several factors, ensuring the sender’s data are correct.

    Some authentication methods are:

    • Biomedical methods, fingerprints or retinal scan, etc.
    • Smart cards that save a user´s certificate information.
    • Standard methods based on passwords.
    • For example, to log into Mercado Libre we authenticate ourselves by entering our user name and password.

    login

    Authorization

    Authorization is the process whereby we allow someone or something to access private resources.
    The authorization should define which resources and operations can be performed, since it is not the same to grant read-only than read and write access.

    How do we obtain authorization? Via the OAuth 2.0 Protocol, which is one of the most widely used protocols in open platforms (Twitter, Facebook, etc.) and a secure method to work with private resources.

    OAuth offers:

    • Confidentiality, the user will never have to disclose his/her key.
    • Integrity, private data can only be viewed by applications with permits to do so.
    • Availability, data will always be available, on a need basis.

    This protocol offers 4 possible operating modes, called Grant Types:

    – The Authorization Code Grant Type (Server Side)
    – The Implicit Grant Type (Client Side)
    – The Password Credentials Grant Type
    – The Client Credentials Grant Type

    Although each of them is used for different purposes depending on the service being developed, below you will find the explanation of the first two types since they will allow you to work with our resources and develop tools for every user in Mercado Libre.

    Client-side

    The Client-side authorization flow is better suited for applications executing the client-side code, e.g., applications developed in javascript/ajax, Angular or mobile applications.
    For more information about this flow, go to the tutorial “Client-Side Authorization

    Server-side

    The Server Side authorization flow is better suited for applications executing the server-side code, such as, applications developed in Java, Grails, Go, etc.
    Note: This option will be helpful for applications executing cron jobs, to update product stock or operate when the user is not directly interacting with the application.
    For more information about this flow, go to the tutorial “Server-Side Authorization

    Get your access_token!

    Enter the application ID you have just created:

    *Please enter a valid Application ID
    User informationJSON Response

    -

    Use our SDKs

    Using our SDKs the authentication process will be simpler since our SDKs save you from coding the whole OAuth protocol from scratch.
    Our community is already using them!
    We already provide SDKs for:

    If you find an enhancement or have a suggestion, you can share it with the community creating a Pull Request within our GitHub repository.

    Considerations

    Token validity and expiration
    When you get an access_token, it will be immediately valid and usable to make requests to the API for a limited period of 6 hours.
    There are also events which may cause an access_token to become invalid before the expiration time. For example: user changing his/her password, an application refreshing its App Secret and, of course, a user revoking permissions to your application.

    Error Codes Reference

    ErrorDescriptionPossible solution
    invalid_client

    invalid client_id or client_secret

    Invalid client_id and/or client_secret provided.Check your application info and verify parameters client_id and client_secret
    invalid_grant

    To create an access token the user {0} must have an active session, or your application should request authorization for offline_access scope.

    The provided authorization grant is invalid, expired, revoked, or does not match the redirection URI used in the authorization request.Verify the parameter redirect_uri is the same configured in your application (App Manager), if this not solve, do a new request to obtain a new code.
    invalid_grant

    Error validating grant. Your authorization code or refresh token may have expired or it has already been used.

    It has expired or it has already been used.Make a new request to obtain one new code or refresh_token.
    invalid_grant

    The client_id does not match the original.

    Client ID does not match.The parameter client_id wasn’t found, to get your client_id, consult your application (App Manager).
    invalid_grant

    The redirect_uri does not match the original.

    Redirect URI does not match the original.The parameter redirect_uri is not the same configured in you application, to get your a redirect_uri, consult your application (App Manager)
    invalid_scopeThe requested scope is invalid, unknown, or malformed.The values allowed for parameter scope are:“offline_access”,”write”,”read”.
    invalid_request

    Wrong number of parameters with duplicate values.

    The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed.Verify that the parameters sent are valid and are not duplicated.
    unsupported_grant_type

    Unsupported grant type: ${0}.

    The authorization grant type is not supported by the authorization server.The values allowed for parameter grant_type are“authorization_code” or “refresh_token”.
    forbidden

    The caller is not authorized to access this resource

    The caller is not authorized to access.It is using the token of another user.


    Next topic: Manage user



    Related articles:
    Server side authentication flow
    Client side authentication flow

    Please rate this