Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 16/03/2023

Manage users

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

Register as a car dealer (Optional)

If you are a car dealer, you can register your user as such to gain access to our promotional packs. To accomplish this, access the Help section. This step can’t be accessed through API, you need to follow the path: Ayuda > Configuración de mi cuenta > Registrarme como oncesionaria.


Screenshot_4

Once you choose "Registrarme como conscecionaria" you'll be redirected to a form which must be filled with the proper information and you will also be able to choose your desired promotional package. After completing the form, one of our agents will get in touch with you.


Keep in mind that having a promotional pack is not mandatory for listing through the API but it’s really helpful for car dealers. Learn how to work with Promotion Packs.


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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/me

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": "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",
  "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"
  }
}

As shown in the result, it is a –real estate- test user that has been active in the Argentine site since January 6th, 2016, with no relevant reputation data to date.


Get data from other users

If you don't have the id, but you know the nickname and the site a user belongs to, you can get it with the following search.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/{Site_id}/search?nickname={Nickname}

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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": [
    ]
    }

If you wish to consult the data of third party users, you will be able to identify two levels of information: public data, which you can find by browsing the MercadoLibre profile of any other user, and private data, which will not be visible unless you have the user's permissions and a valid token to work on their name. In both cases, the first thing you will need to know is the user's id.

How to obtain a user's ID?

If you don't have the id, but you know the nickname and the site a user belongs to, you can get his id with the following search.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?nickname=TETE2870021

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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
      }
    ]
  }
  ]
}

Consult a user's public information

Well, this way you already know the user's Id, so you can call the users resource as follows and get the public information of the user you want:


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{User_id}

Example:

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

Response:

{
  "id": 205159033,
  "nickname": "TETE4358231",
  "registration_date": "2016-02-04T13:49:09.000-04:00",
  "country_id": "AR",
  "address": {
  "state": "AR-C",
  "city": "Palermo"
  },
  "user_type": "car_dealer",
  "tags": [
  "car_dealer",
  "test_user",
  "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE4358231",
  "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.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{User_id}

Example:

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

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"
  }
}

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 'Authorization: Bearer $ACCESS_TOKEN' -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}

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


User seller S=P (sell equal pay)

If you want all your operations are exclusively through Mercado Pago you must indicate in your user information only accept mode S=P (sell equal pay). To disable the option agree with the seller.


PUT:

curl -XPUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-type: application/json" -d 

'{
    "reason": "by_user"
}'

https://api.mercadolibre.com/users/{user_id}/immediate_payment

To delete the option only accept Mercado Pago:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{user_id}/immediate_payment/by_user

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 packages
Related article: Learn how to manage user's addresses.