Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 22/08/2023

Brand Central

With this resource, the sellers can send products suggestions for products that not exist in our Mercado Libre catalog. It will help our catalog to growth, giving the possibility to add more products faster and improving the whole flow.

Notifications status

With this topic, catalog_suggestions you can subscribe and start to receive notifications of the status of suggestions to catalog. The possible status to a suggestion are:

  • UNDER_REVIEW: the suggestions are in review by Mercado Libre.
  • WAITING_FOR_FIX: an error was found in the data and must be corrected by the user.
  • PUBLISHED: the suggestion was approved, and the product was created and active en the catalog.
  • REJECTED: the suggestion was rejected by legal reasons and because the product was found in our catalog.

Suggestions quota

The user_id returns information if a seller is enabled or not, to use this recourse, and you can also obtain the capacity (quota) that the user has available for create suggestion.


Request:

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

Example:

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

Response:

{
  "quota": [
     {
        "type": "standard",
        "available": 10
     }
  ]
}

User response not allowed:

{
  "code": "forbidden",
  "message": "User not allowed",
  "status_code": 403
}

Available domains

The site_di returns a dump of whole domains, to indicate if it's possible or not to create suggestions.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/domains/$SITE_ID/available/full

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/domains/MLA/available/full

Response:

{
    "generation_date": "2021-11-15T04:32:14.512952Z",
    "domains": [
        {
            "id": "MLA-CELLPHONE_USB_AND_AUXILIARY_ADAPTERS",
            "name": "Adaptadores de USB y auxiliar para celulares",
            "pictures": [
                {
                    "id": "715173-MLU30701120250_052019",
                    "url": "http://http2.mlstatic.com/D_NQ_NP_715173-MLU30701120250_052019-F.jpg",
                    "secure_url": "https://http2.mlstatic.com/D_NQ_NP_715173-MLU30701120250_052019-F.jpg",
                    "size": "500x500"
                }
                ],
            "available": false
        },
        {
            "id": "MLA-AIR_CONDITIONERS",
            "name": "Aires acondicionados",
            "pictures": [
                {
                    "id": "795131-MLU26486283495_122017",
                    "url": "http://mlu-s1-p.mlstatic.com/795131-MLU26486283495_122017-F.jpg",
                    "secure_url": "https://mlu-s1-p.mlstatic.com/795131-MLU26486283495_122017-F.jpg",
                    "size": "500x500"
                }
            ],
            "available": true
        },
        ...
    ]
}

Domain technical data

The domain_id, returns the suggestions by domain technical data.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs?channel_id=catalog_suggestions

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs?channel_id=catalog_suggestions

Response:

{
  "input": {
    "groups": [
      {
        "id": "MAIN",
        "label": "Características principales",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
              "component": "TEXT_INPUT",
              "label": "Marca",
              "ui_config": {
                  "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca.",
                  "allow_custom_value": false,
                  "allow_filtering": false
              },
              "attributes": [
                  {
                      "id": "BRAND",
                      "name": "Marca",
                      "value_type": "string",
                      "value_max_length": 255,
                      "tags": [
                          "catalog_required",
                          "required"
                      ],
                      "hierarchy": "PARENT_PK",
                      "relevance": 1
                  }
              ],
              "unified_units": []
          }
        ]
      },
      {
        "id": "OTHER",
        "label": "Otros",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
              "component": "TEXT_INPUT",
              "label": "Modelo detallado",
              "ui_config": {
                  "allow_custom_value": false,
                  "allow_filtering": false
              },
              "attributes": [
                  {
                      "id": "DETAILED_MODEL",
                      "name": "Modelo detallado",
                      "value_type": "string",
                      "value_max_length": 255,
                      "tags": [
                          "hidden"
                      ],
                      "hierarchy": "CHILD_DEPENDENT",
                      "relevance": 1
                  }
              ],
              "unified_units": []
          }
        ]
      }
    ]
  },
  "output": {
    "main_title": "Características Principales",
    "groups": [
      {
        "id": "GENERAL_CHARACTERISTICS",
        "label": "Características generales",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
            "component": "TEXT_OUTPUT",
            "label": "Marca",
            "ui_config": {
                "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca."
            },
            "attributes": [
              {
                "id": "BRAND",
                "name": "Marca",
                "value_type": "string",
                "tags": [],
                "hierarchy": "PARENT_PK",
                "relevance": 1
              }
            ]
          },
          {
            "component": "TEXT_OUTPUT",
            "label": "Línea",
            "ui_config": {},
            "attributes": [
              {
                "id": "LINE",
                "name": "Línea",
                "value_type": "string",
                "tags": [],
                "hierarchy": "PARENT_PK",
                "relevance": 1
              }
            ]
          }
        ]
      }
    ]
  }
}

Suggestions by technical data

Some resources are allowed just to input or output the technical data to a determinate domain. The input have the settings that we use to request for the attributes, and the output have the ones that define which attributes that we are going to show in the front.


Input

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' hhttps://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs/input?channel_id=catalog_suggestions

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs/input?channel_id=catalog_suggestions

Response:

{
  "groups": [
    {
      "id": "MAIN",
      "label": "Características principales",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
            "component": "TEXT_INPUT",
            "label": "Marca",
            "ui_config": {
                "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca.",
                "allow_custom_value": false,
                "allow_filtering": false
            },
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_type": "string",
                    "value_max_length": 255,
                    "tags": [
                        "catalog_required",
                        "required"
                    ],
                    "hierarchy": "PARENT_PK",
                    "relevance": 1
                }
            ],
            "unified_units": []
        }
      ]
    },
    {
      "id": "OTHER",
      "label": "Otros",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
            "component": "TEXT_INPUT",
            "label": "Modelo detallado",
            "ui_config": {
                "allow_custom_value": false,
                "allow_filtering": false
            },
            "attributes": [
                {
                    "id": "DETAILED_MODEL",
                    "name": "Modelo detallado",
                    "value_type": "string",
                    "value_max_length": 255,
                    "tags": [
                        "hidden"
                    ],
                    "hierarchy": "CHILD_DEPENDENT",
                    "relevance": 1
                }
            ],
            "unified_units": []
        }
      ]
    }
  ]
}
  }
}

Output

Request

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs/output?channel_id=catalog_suggestions

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs/output?channel_id=catalog_suggestions

Response:

{
  "main_title": "Características Principales",
  "groups": [
    {
      "id": "GENERAL_CHARACTERISTICS",
      "label": "Características generales",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
          "component": "TEXT_OUTPUT",
          "label": "Marca",
          "ui_config": {
              "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca."
          },
          "attributes": [
            {
              "id": "BRAND",
              "name": "Marca",
              "value_type": "string",
              "tags": [],
              "hierarchy": "PARENT_PK",
              "relevance": 1
            }
          ]
        },
        {
          "component": "TEXT_OUTPUT",
          "label": "Línea",
          "ui_config": {},
          "attributes": [
            {
              "id": "LINE",
              "name": "Línea",
              "value_type": "string",
              "tags": [],
              "hierarchy": "PARENT_PK",
              "relevance": 1
            }
          ]
        }
      ]
    }
  ]
}

Previous validations

With this resource, you can check the suggestion before send. Receive a possible suggestion and returns validations are specific of Brand Central, Standard products and Items.


Example:

curl -X POST  -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "title": "Sugerencia de test",
    "domain_id": "MLA-CELLPHONES",
    "pictures": [
        {
          "id": "647954-MLA46144073729_052021"
        }
    ],
    "attributes": [
        {
            "id": "BRAND",
            "values": [
                {
                     "name": "Samsung"
                }
            ]
        },
        {
            "id": "IS_DUAL_SIM",
            "values": [
                {
                    "name": "Si"
                }
            ]
        },
        {
            "id": "GTIN",
            "values": [
                {
                    "name": 12345678
                }
            ]
        },
        {
            "id": "RAM",
            "values": [
                {
                    "name": "6 GB"
                }
            ]
        },
        {
            "id": "COLOR",
            "values": [
                {
                    "name": "Rojo"
                }
            ]
        }
    ]
}
'
https://api.mercadolibre.com/catalog_suggestions/validate

Response: Status 200 OK


When the suggestion has a validation error.


Status: 400


Example:


{
    "error": "validation_error",
    "message": "Validation error",
    "status": 400,
    "cause": [
        {
            "department": "items",
            "cause_id": 10147,
            "type": "error",
            "code": "item.attributes.missing_required",
            "references": [
                "item.attributes",
                "item.variations.attribute_combinations"
            ],
            "message": "The attributes [MODEL, INTERNAL_MEMORY] are required for category MLA1055. Check the attribute is present in the attributes list or in all variation's attributes_combination or attributes."
        },
        {
            "department": "quality",
            "cause_id": 3026,
            "type": "error",
            "code": "InvalidProductIdentifier",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El código universal 12345678 tiene un formato incorrecto."
        },
        {
            "department": "quality",
            "cause_id": 3035,
            "type": "error",
            "code": "IreqAttributesMissing",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Memoria interna\" es obligatorio y no está cargado."
        },
        {
            "department": "quality",
            "cause_id": 3017,
            "type": "error",
            "code": "InvalidAttributeValue",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Es Dual SIM\" debe ser alguna de las opciones disponibles y le cargaste \"Si\"."
        },
        {
            "department": "quality",
            "cause_id": 304,
            "type": "error",
            "code": "CatalogRequiredMissing",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Modelo\" es obligatorio y no está cargado."
        }
    ]
}

Create a suggestion

In case you want to create a product suggestion, you will have to send a POST with the necessary information to creating each new suggestion.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
  "title": "Item De Test, No Ofertar!",
  "domain_id": "MLA-CELLPHONES",
  "pictures": [{
    "id": "647954-MLA46144073729_052021"
  }],
  "attributes": [{
      "id": "BRAND",
      "values": [
      {
        "id": "59387",
        "name": "Xiaomi"
      }
     ]
    },
    {
      "id": "LINE",
      "values": [
       {
        "id": "199791",
        "name": "Redmi"
       }
      ]
   }
  ]
}'
https://api.mercadolibre.com/catalog_suggestions

Response:

{
	"id": "MLA922220746",
	"site_id": "MLA",
	"title": "Item De Test, No Ofertar!",
	"seller_id": 238564384,
	"domain_id": "MLA-CELLPHONES",
	"status": "UNDER_REVIEW",
	"attributes": [{
			"id": "BRAND",
			"values": [
			{
				"id": "59387",
				"name": "Xiaomi"
			}
		  ]
		},
		{
			"id": "LINE",
			"values": [
			{
				"id": "199791",
				"name": "Redmi"
			}
		  ]
		}
	],
	"pictures": [{
		"id": "647954-MLA46144073729_052021"
	}]
}

Get a suggestion

With this resource, it is possible to get the detail of a suggestion that was previously created.


Request:

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

Example:

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

Response:

{
  "id": "MLA12345",
  "site_id": "MLA",
  "status": "UNDER_REVIEW" | "WAITING_FOR_FIX" | "PUBLISHED" | "REJECTED",
  "sub_status": "VALIDATING" | "WAITING_FOR_FIX" | "READY_TO_IMPORT" | "IMPORTED" | "PUBLISHED" | "REJECTED",
  "title": "Item De Test, No Ofertar!",
  "seller_id": 111111,
  "domain_id": "MLA-CELLPHONES",
  "attributes": [
    {
      "id": "BRAND",
      "name": "Marca",
      "values": [
        {
          "id": "59387",
          "name": "Xiaomi",
          "struct": null
        }
      ]
    },
    {
      "id": "LINE",
      "name": "Línea",
      "values": [
        {
          "id": "199791",
          "name": "Redmi",
          "struct": null
        }
      ]
    }
  ],
  "pictures": [
    {
      "id": "667092-MLA29115232412_012019",
      "url": "http://http2.mlstatic.com/D_667092-MLA29115232412_012019-O.jpg",
      "secure_url": "https://http2.mlstatic.com/D_667092-MLA29115232412_012019-O.jpg",
      "size": "500x375"
    }
  ],
  "tags": [
    "test_suggestion"
  ],
  "date_created": "2021-06-08T18:49:08Z",
  "last_updated": "2021-06-30T17:51:08Z"
}

Create a description

With this resource, you can create a product description base in the suggestion, adding a description en the item detail.

Example:

curl -X POST-H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{    
    "plain_text": "Texto de la Descripción"
        
}
https://api.mercadolibre.com/catalog_suggestions/${suggestion_id}/description

Response: HTTP status 200 OK.


Modify a description

With this resource, you can modify a description that was sent previously to create.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID/description

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d 
{
  "plain_text": "Texto de la Descripción"
}
https://api.mercadolibre.com/catalog_suggestions/${suggestion_id}/description

Response: HTTP status 200 OK.


Get validations results

With suggestion_id you can validate the result of standard products that are finished until the moment.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID/validations

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/123456/validations

Response:

{
    "validations": [
          {
              "department": "quality",
              "cause_id": 3025,
              "type": "error",
              "code": "InvalidProcessingPicture",
              "references": [
                "suggestion.pictures"
              ],
              "message": "Ocurrió un error procesando la foto. Por favor cargala nuevamente"
          },
          {
              "department": "quality",
              "cause_id": 3025,
              "type": "error",
              "code": "InvalidProcessingPicture",
              "references": [
                "suggestion.pictures"
              ],
              "message": "Ocurrió un error procesando la foto. Por favor cargala nuevamente"
          },
          {
              "department": "quality",
              "cause_id": 3074,
              "type": "error",
              "code": "ProductIdentifierMissing",
              "references": [
                "suggestion.attributes"
              ],
              "message": "El campo \"Código universal de producto\" es obligatorio y no está cargado."
          }
    ]
}

Modify a suggestion

If you want to send a suggestion, you must have to do the following PUT:

Request:

curl -X PUT-H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID

Example:

curl -X PUT-H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
    "title": "Titulo a modificar",
    "attributes": [
      {
        "id": "BRAND",
        "name": "Marca",
         "values": [
          {
            "id": "11111",
            "name": "Xiaomi 1",
            "struct": null
          }
        ]
      },
      {
        "id": "LINE",
        "values": [
          {
            "id": "199791",
            "name": "Redmi",
            "struct": null
           }
        ]
      }
    ],
    "pictures": [
      {
        "id": "647954-MLA46144073729_052021"
      }
    ]
  }

Response:

{
  "id": "MLA1103361143",
  "site_id": "MLA",
  "status": "WAITING_FOR_FIX",
  "title": "Titulo A Modificar",
  "seller_id": 818222588,
  "domain_id": "MLA-GAME_CONSOLES",
  "attributes": [
    {
      "id": "BRAND",
      "name": "Marca",
      "values": [
        {
          "id": "11111",
          "name": "Xiaomi 1"
        }
      ]
    },
    {
      "id": "LINE",
      "name": "Línea",
      "values": [
        {
          "id": "199791",
          "name": "Redmi"
         }
      ]
    },
    {
      "id": "MODEL",
      "name": "Modelo",     
      "values": [
        {
          "name": "juego 1"
         }
      ]
    }
  ],
  "pictures": [
    {
      "id": "647954-MLA46144073729_052021",
      "url": "ttp://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
      "secure_url":"https://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
      "size": "500x313"
    }
  ],
   "tags": [
      "test_suggestion"
  ],
  "date_created": "2021-09-14T20:38:36Z",
  "last_updated": "2021-09-24T17:43:36Z"
}

List suggestions

In this resource it's possible to list all the suggestions created by a user, their details and status.

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/users/$USERID/suggestions/search

Response:

{
  "total": 1,
  "scroll_id": "YXBpY29yZS1pdGVtcy1zZWFyY2g=:ZHMtYXBpY29yZS1pdGVtcy0wNQ==:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFDNmWU1xM29Cb2dhM2N3amFBREM0AAAAAA0NlNkWaDBFWTEzejVRb080N3RDTDVwbzlZdw==",
  "suggestions": [
    {
      "id": "MLA924694517",
      "site_id": "MLA",
      "status": "UNDER_REVIEW",
      "sub_status": "VALIDATING",
      "title": "Item De Test, No Ofertar",
      "seller_id": 772437317,
      "domain_id": "MLA-CELLPHONES",
      "attributes": [
        {
          "id": "BRAND",
          "name": "Marca",
          "values": [
            {
              "id": "59387",
              "name": "Xiaomi",
              "struct": null
            }
          ]
        },
        {
          "id": "LINE",
          "name": "Línea",
          "values": [
            {
              "id": "199791",
              "name": "Redmi",
              "struct": null
             }
          ]
        }
      ],
      "pictures": [
        {
         "id": "647954-MLA46144073729_052021",
         "url": "ttp://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
         "secure_url":"https://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
        "size": "500x313"
        }
      ]
    }
  ]
}

Optional filters

  • scroll_id [string]: If the scroll_id, are scrolling through a user's suggestions (optional).
  • limit [integer]: to configure the element's quantity to return to the request. min: 10 max: 50 default: 50 (optional).
  • offset [integer]: offset of the search, i.e. index of the first element to be returned. The limit should remain fixed during the whole paging, while the offset will vary, increasing by the same amount as the limit. In the response we return the field "total" with which you can be guided to know up to what value the offset can be increased (optional).
  • search_type [scan|search]: search_type = scan returns scroll_id to use the following requests. default: search (optional).
  • domain_ids [string]: to filter the suggestions in some domains (optional).
  • status [string]: to filter the suggestions in some status (optional).
  • title [string]: permit to pass a partial title and search for suggestions where the title matches with the string (optional).

Errors

Error_code Error Message Description
400 Property [title] cannot be blank POST/PUT without title of a suggestion
400 Domain is not active Inactive domain in buybox
400 User is not allowed to create products User without permission to publish
400 User is not allowed to create products from this brand User without permission to publish in a special brand
400 Attribute values must not be null Attribute with value null
400 Item has unprocessable tags Suggestion in a non-modifiable state
400 Domain is not modifiable User try to modify the domain of a suggestion
400 Suggestion ${suggestion_id} can not be modified Status does not support changing the suggestion description
400 Suggestion ${suggestion_id} already has a description Suggestion already has a description created
403 User {caller.id} not allowed to get validations for suggestion {suggestion_id} User does not own the suggestion requesting validations

Using Brand Central for trial users

To start using and testing BC resources with a test user, please submit your test user data in this support.