Marketplace items

Important:
As of July 1, it will be mandatory that all PUT requests to items be: https://api.mercadolibre.com/global/items. Please, start updating your endpoints.

Get available marketplace sites to publish

To list the items in the marketplaces, we need to know which assets we have for our user. So, make the following GET request with the user id:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET http://api.mercadolibre.com/marketplace/users/$USER_ID

This resource presents the user and all the marketplaces that our user has configured:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET http://api.mercadolibre.com/marketplace/users/471826944

Response:

{
    "user_id": 471826944,
    "site_id": "CBT",
    "marketplaces": [
        {
            "user_id": 471828584,
            "site_id": "MLM",
            "logistic_type": "remote"
        },
        {
            "user_id": 471830260,
            "site_id": "MLB",
            "logistic_type": "remote"
        },
        {
            "user_id": 538932857,
            "site_id": "MLC",
            "logistic_type": "remote"
        }
    ]
}

So, at the moment of listing, you only have to see the site_id and logistic_type fields to determine the marketplace where the publication will be available.


Create marketplace items

Through the following resource, you may list production Global Selling items on the Marketplace where it is required. Remember that this way the listing will work in a production environment and the listing quota per site will be 10.000 per day.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/items/$ITEM_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/items/CBT1234
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": [
    {
      "site_id": "MLM",
      "logistic_type": "remote"
    },
    {
      "site_id": "MLB",
      "logistic_type": "remote",
       "price":11.23
    }
  ]
}'
Note:
When you add the product price, the value is interpreted as a U.S. dollar amount, although the item will be listed with a differentiated price on each site.

Response:

[
    {
        "action": "POST",
        "item_id": "MLM111111",
        "parent_id": "CBT1234",
        "logistic_type": "remote",
        "site_id": "MLM",
        "errors": null
    },
    {
        "action": "POST",
        "item_id": "MLB111111",
        "parent_id": "CBT1234",
        "logistic_type": "remote",
        "site_id": "MLB",
        "errors": null
    }
]

Parameters

item_id: It is the Global Selling item identifier.

Errors creating marketplace items

HTTP code Error Message
400 bad_request You cannot offer this product in $COUNTRY.
400 bad_request You can't send the product in this kind of shipment in $COUNTRY.
400 forbidden Active listings quota reached. See more Listing Limits.
403 forbidden Invalid caller.id
403 forbidden Can not identify the user.
404 not_found Resource not found.
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 Bad rerquest {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Invalid parameter
404 not_found Item with id $id not found
404 bad_request current user $user_id is not configured to publish in site $site and logistic $logistic

Get the Marketplace item details

To obtain the details of Marketplace items that are listed, you may use the following resource:

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET http://api.mercadolibre.com/marketplace/items/MLM720042224

Response:

{
   "id":"MLM720042224",
   "site_id":"MLM",
   "date_created":"2019-09-19T14:26:05Z",
   "title":"Test Item - Title In Spanish 2",
   "descriptions":[
      {
         "id":"MLM720042224-2336116747"
      }
   ],
   "listing_type_id":"gold_pro",
   "permalink":"https://articulo.mercadolibre.com.mx/MLM-720042224-test-item-title-in-spanish-2-_JM",
   "shipping":{
      "mode":"me1",
      "local_pick_up":false,
      "free_shipping":true,
      "logistic_type":"default",
      "store_pick_up":false,
      "dimensions":"2x5x11,102",
      "free_methods":[
         {
            "id":501645,
            "rule":{
               "free_mode":"country",
               "value":null
            }
         }
      ],
      "tags":[

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

   ],
   "tags":[
      "incomplete_technical_specs",
      "test_item",
      "immediate_payment",
      "cart_eligible"
   ],
   "catalog_product_id":null,
   "domain_id":"MLM-BABIES_FOOTWEAR",
   "international_delivery_mode":"DDP",
   "inventory_id":null,
   "category_id":"MLM71792",
   "official_store_id":null,
   "sold_quantity":14,
   "available_quantity":90,
   "last_updated":"2019-10-29T17:01:33.073Z",
   "price":11,
   "currency_id":"USD",
   "base_exchange_rate":19.717,
   "user_logistic_type":"remote",
   "owner_id":471826944,
   "cbt_item_id":"CBT910360704"
}

Parameters

id: It is the Global Selling item identifier, which is created through a call to the local API.


Delete marketplace items

In order to delete marketplace items, the item to delete must be in a paused or closed state and then make the same PUT:

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/global/items/CBT946690995 -d 
{
   "site_id": "MLM",
   "logistic_type": "remote",
   "deleted": true
}

Response:

{
   "item_id": "CBT946690995",
   "parent_id": "CBT946690995",
   "logistic_type": "remote",
   "site_id": "MLM",
   "errors": null
}
Note:
Once the marketplace items are deleted, the global item (CBTXXXXXXX) will be deleted by the automatic processes from Mercado Libre. This action cannot be done through our APIs.

Guide to modify items

Field Description Resource to use It can be updated
listing_type_id No
title The title is the key for buyers to find your product. /marketplace/items/:id Yes
available_quantity This attribute defines the stock, that's the number of products available for selling on this item. /items/:id Yes, only for items with "remote" logistics.
category_id It is the category where will be publish the item. /items/:id Yes
buying_mode It's the buying mode of item. No
currency_id You need to define a currency. You need to use USD. This one is also a mandatory attribute. No
condition The item condition must be new. This attribute is mandatory to complete a list operation. Yes
price This is a mandatory attribute, when you define a new item it must have a price. /marketplace/items/:id Yes
warranty Within an item “sale_terms” section, define the warranty of the listed product. /items/:id Yes
sale_terms These are the Sales Condition Attributes, which can specify details of the publication, such as the types of warranties of a product. /items/:id Yes
attributes An attribute represents a characteristic of your item /items/:id Yes
pictures They are the images that will be presented in the publication. /items/:id Yes
video_id YouTube video id must be added /items/:id Yes
variations With variations you can count in the same publication all the variants of the item, maintaining even differential stock for each one. /items/:id Yes
description It's a detailed description of item. /marketplace/items/:id Yes
status You must enter the valid status "active" or "paused". /marketplace/items/:id Yes

Errors modifying marketplace items

HTTP code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user.
404 not_found Resource not found.
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Invalid parameter
404 not_found Item with id $id not found
404 bad_request parent user $user_id does not have any child for site $site and logistic $logistic
404 bad_request parent item $item_id does not have any child for site $site and logistic $logistic

Notes:
- If you get the “parent user $user_id does not have any child for site $site and logistic $logistic” error means that try to operate in a marketplace where you are not enabled.
- If you get the “parent item $item_id does not have any child for site $site and logistic $logistic” error means that try to operate in a marketplace with a not created item.

Errors

HTTP code Error Message
403 forbidden Invalid caller.id
404 not_found Resource not found.
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Invalid parameter
404 not_found Item with id $id not found

Items specifications

Item detail 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

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

The title is the key for buyers to find your product. Therefore, it should be as explicit as possible.

Generate the title with Product + Brand + product model + some specifications that help identify the product. Avoid in the title information of other services, such as returns, free shipping or installment payments because your information will be seen by your buyers next to the product, without having to enter the publication.
If your product is new, used or refurbished, do not include it in the title, upload it in the features and we will show it in the detail of the publication.
If you sell the same product but with different colors, do not put the color in the title. Better create variants, so everything will be in a single publication.
If you only have stock of a certain color, load the color when publishing or in the characteristics section so that your buyers read the complete technical sheet, but you can add it in the title since it would be a publication that only sells a variant.
If you make a discount we will also indicate it showing the percentage of the promotion, we also have a special label to call attention. No need to add it in the title.
Separate words with spaces, do not use punctuation or symbols. Check have no spelling errors. It is not allowed to mention stock if you do it your publication will be moderated. The limit of the publication title is set by the category to which it belongs ("max_title_length"). For example: HP Dual Core 425 LED 14 320 GB 4 GB Wifi HDMI Notebook

Note:
You can always make all the changes you need making a PUT on a items resource modifying the tittle field when sold_quantity be 19 inclusive.

Description

Detailed information will improve your chances of selling a product and save you time by not having to answer questions. See more about Item descriptions and considerations to keep in mind.


Condition

When listing an item you need to declare the condition is new. 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 Mercado Libre 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":"CBT12683",
 ...
}

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

The price you must place is in dollars. This is also a mandatory attribute and you must define it using a pre-established id.


Product Identifiers

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


SKU

This information will help your sellers to identify, locate and internally track a product. We only take into account the information loaded in the SELLER_SKU attribute. Learn more about variations considerations.


Variations

With Variations you can count in the same publication all the variants of the item, maintaining even differential stock for each one. In this way, when you receive a purchase, you will see in the purchase order the color and size chosen by the buyer, thus facilitating the after-sales process. Learn more about Variations.


An item condition

To define if a product is new, used or refurbished you will need to send the “item_condition” attribute with the value you intend to give. We recommend you to review the Attribute documentation to learn about category attributes and supported values.

Note:
While today it is allowed to send if an item is new or used in the “condition” field, it should be placed as attribute in the case of “reacondicionado”.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET  https://api.mercadolibre.com/categories/$CATEGORY_ID/attributes

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/categories/CBT5849/attributes

Response:

[{
		"id": "BRAND",
		"name": "Brand",
		"tags": {
			"catalog_required": true
		},
		"hierarchy": "PARENT_PK",
		"relevance": 1,
		"value_type": "string",
		"value_max_length": 255,
		"attribute_group_id": "OTHERS",
		"attribute_group_name": "Others"
	},
	{
		"id": "GTIN14",
		"name": "GTIN-14",
		"tags": {
			"hidden": true,
			"multivalued": true,
			"variation_attribute": true,
			"used_hidden": true,
			"validate": true
		},
		"hierarchy": "PRODUCT_IDENTIFIER",
		"relevance": 2,
		"type": "product_identifier",
		"value_type": "string",
		"value_max_length": 255,
		"attribute_group_id": "OTHERS",
		"attribute_group_name": "Others"
	}
]
Important:
When the listing has “reacondicionado” condition, you need to load the Product Warranty in "sale_terms".

Product warranty

Within an item “sale_terms” section, define the warranty of the listed product. For this, the information should have a combination of attributes: Warranty Type: represents the forms that warranty can take. For example, seller or factory warranty, etc. Warranty Time: represents the time that warranty will be in force.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET  https://api.mercadolibre.com/categories/$CATEGORY_ID/sale_terms

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/categories/CBT5849/sale_terms

Response:

[{
		"id": "WARRANTY_TYPE",
		"name": "Type of warranty",
		"tags": {},
		"hierarchy": "SALE_TERMS",
		"relevance": 2,
		"value_type": "list",
		"values": [{
				"id": "2230280",
				"name": "Seller warranty"
			},
			{
				"id": "2230279",
				"name": "Factory warranty"
			},
			{
				"id": "6150835",
				"name": "No warranty"
			}
		],
		"attribute_group_id": "OTHERS",
		"attribute_group_name": "Others"
	},
	{
		"id": "WARRANTY_TIME",
		"name": "Warranty time",
		"tags": {},
		"hierarchy": "SALE_TERMS",
		"relevance": 2,
		"value_type": "number_unit",
		"value_max_length": 255,
		"allowed_units": [{
				"id": "days",
				"name": "days"
			},
			{
				"id": "months",
				"name": "months"
			},
			{
				"id": "years",
				"name": "years"
			}
		],
		"default_unit": "months",
		"attribute_group_id": "OTHERS",
		"attribute_group_name": "Others"
	}
]
Note:
When setting an item as reconditioned it should be done with a minimum 90-day guarantee. Look more about Publication Policies.

Next: Sync and modify listings.