Item description

Tips for describing a post

• First load the important data in the data sheet, that is to say all the specifications without forgetting the universal product code.
• Verify that the data that you are going to write in the description are the details that are not in the data sheet.
• Organize and structure the information hierarchically. Use uppercase, hyphens, spacing, etc.
• Be brief and read your own description to check its length.

Get item description

Retrieves the description of a global selling item for a specific site and logistic type.

Parameters

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/$ITEM_ID/description?site_id=$SITE_ID&logistic_type=$LOGISTIC_TYPE

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/CBT123456/description?site_id=MLM&logistic_type=remote

Response:

{
  "text": "",
  "plain_text": "This description is in your local language",
  "translated_plain_text": "This description is in your local language",
  "last_updated": "2021-12-10T14:48:05Z",
  "date_created": "2021-04-08T16:29:47Z"
}

Response fields

Errors

Upload item description

Once the global item is created, you can load its description with the following POST. Remember that they must contain plain text and you will not be able to change the fonts, sizes or mark texts in bold. You can only perform line breaks as follows: \n.

Parameters (Body)

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "$SITE_ID",
  "logistic_type": "$LOGISTIC_TYPE",
  "plain_text": "plain text description \n"
}
https://api.mercadolibre.com/marketplace/items/$ITEM_ID/description

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "MLM",
  "logistic_type": "remote",
  "plain_text": "Product description text.\nNew line here."
}
https://api.mercadolibre.com/marketplace/items/CBT123456/description

Response (201 Created):

{
  "message": "",
  "error": "Created",
  "status": 201,
  "cause": null
}

Errors

Benefits of using plain text

• They will have better results in searches.
• Descriptions can be downloaded 5 times faster.
• They will be properly displayed in all devices (mobile, tablets, computer).
• Besides, you will be able to upload up to 10 item pictures and/or a link with a YouTube video.

Example of a well-structured description

Below is an example of how a well-organized product description should look. Notice the clear hierarchy, proper use of line breaks, and structured information:

Replace an existing description

To make modifications to an existing description, use the following PUT request.

Parameters (Body)

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "$SITE_ID",
  "logistic_type": "$LOGISTIC_TYPE",
  "description": {
    "plain_text": "$PLAIN_TEXT"
  }
}
https://api.mercadolibre.com/global/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "MLM",
  "logistic_type": "remote",
  "description": {
    "plain_text": "Updated description text."
  }
}
https://api.mercadolibre.com/global/items/CBT123456

Response (200 OK):

{}

Errors

Character validation errors

If you POST or PUT a description that contains unacceptable characters (such as HTML tags or emojis), the response will contain information about the error, including the position of the invalid character.

Invalid characters examples

The following characters are not allowed in descriptions:

Example request with invalid characters (emoji):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "MLM",
  "logistic_type": "remote",
  "plain_text": "Great product! :) Buy now!"
}
https://api.mercadolibre.com/marketplace/items/$ITEM_ID/description

Example request with invalid characters (HTML):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
  "site_id": "MLM",
  "logistic_type": "remote",
  "plain_text": "Text <br> with HTML"
}
https://api.mercadolibre.com/marketplace/items/$ITEM_ID/description

Error response:

{
  "message": "Validation error",
  "error": "validation_error",
  "status": 400,
  "cause": [
    {
      "department": "items",
      "cause_id": 398,
      "type": "error",
      "code": "item.description.type.invalid",
      "references": [
        "plain_text[12]"
      ],
      "message": "The description must be in plain text"
    }
  ]
}

In the references field you can find the exact position of the character that generates the error. In this example, position 12.

Next: Specific Regulations.