List products

In the Global Selling API, publications have items (products) with attributes to be sold and are visible when the user selects the product from the results list. The items are created in Global Selling (CBT site) and then can be listed in the marketplaces of Mercado Libre that the seller has enabled. Once an item is published on a marketplace, it begins to be visible to buyers who visit the site.
Learn with this guide how to list products.

Contents

→List products flow
→Create an Global Site item
→Codes errors reference
→Product status
→Delete marketplace items
→Items specifications
    ↳Item detail page
    ↳Defining attributes
    ↳Title
    ↳Description
    ↳Condition
    ↳Available-quantity
    ↳Pictures
    ↳Category
    ↳Price
    ↳Currency
    ↳Product Identifiers
    ↳SKU
    ↳Variations
    ↳An item condition
    ↳Product warranty
→Listing type
→How to know in which marketplaces can I publish?
→Marketplace items
→Modify Marketplace item details
→Get the Marketplace item details
→Guide to modify items
→List an Official Store item



List products flow

In this way, the seller will be able to see the Global Selling item that it represents, to the physical product that it has in its deposit related to local items found in the Marketplaces that he published.
For example, a seller from China with the product "cereal bars" should create the item on the Global Selling site: "Cereal Bar - Sapphire - Test Bar" which will have the content in english and the price in US dollars (USD). Then, you can list it in the enabled marketplaces, such as Mexico and Brazil using the APIs corresponding to items/marketplace, in two local items:
- https://api.mercadolibre.com/items/MLM722109336
- https://api.mercadolibre.com/items/MLB1421316520
The item will have its translated content and the price according to the marketplace of the country. If the seller has 10 (ten) units in stock, they must be detailed in the Global Selling item and this amount will be in all sites where the item is listed, as well as when a sale is made, the subtraction will be reflected in the Global Selling site.
In relation to the price of the product, the seller can put a specific price for each marketplace and, if not defined, the price of the Global Selling item will be replicated. Remember that the item may have affected properties and should be modified in the Global Selling item, while others may be made directly on each item per marketplace.
Learn more with the following flow:

Create an Global Site item

The items are created in Global Selling (CBT site) and then can be listed in the marketplaces of Mercado Libre that the seller has enabled. Make the next request POST with an access_token. Also, you can learn more Items specifications.

Request:

curl -X POST http://api.mercadolibre.com/items/?access_token=$ACCESS_TOKEN

Example:

curl -X POST http://api.mercadolibre.com/items/?access_token=$ACCESS_TOKEN 

{
  "listing_type_id": "gold_pro",
  "title": "Test Item - for LoadTest tests",
  "available_quantity": 100,
  "category_id": "CBT11796",
  "buying_mode": "buy_it_now",
  "currency_id": "USD",
  "condition": "new",
  "site_id": "CBT",
  "price": 15.1,
  "accepts_mercadopago": true,
  "non_mercado_pago_payment_methods": [],
  "warranty": "1 year",
  "sale_terms": [
    {
      "id": "WARRANTY_TIME",
      "value_name": "90 days"
    },
    {
      "id": "WARRANTY_TYPE",
      "value_id": "2230279"
    }
  ],
  "attributes": [
    {
      "id": "PACKAGE_HEIGHT",
      "value_name": "10 cm"
    },
    {
      "id": "FOOTWEAR_TYPE",
      "value_name": "Zapatilla"
    },
    {
      "id": "PACKAGE_WIDTH",
      "value_name": "10 cm"
    },
    {
      "id": "PACKAGE_LENGTH",
      "value_name": "10 cm"
    },
    {
      "id": "PACKAGE_WEIGHT",
      "value_name": "0.7 lb"
    },
    {
      "id": "BRAND",
      "name": "Brand",
      "value_id": null,
      "value_name": "DOMINIQ",
      "value_struct": null,
      "values": [
        {
          "id": null,
          "name": "DOMINIQ",
          "struct": null,
          "source": 1054850885297509
        }
      ],
      "attribute_group_id": "OTHERS",
      "attribute_group_name": "Otros",
      "source": 1054850885297509
    },
    
    {
      "id": "GENDER",
      "name": "Gender",
      "value_id": "371795",
      "value_name": "Babies",
      "value_struct": null,
      "values": [
        {
          "id": "371795",
          "name": "Bebés",
          "struct": null,
          "source": 1
        }
      ],
      "attribute_group_id": "OTHERS",
      "attribute_group_name": "Otros",
      "source": 1
    },
    {
      "id": "ITEM_CONDITION",
      "name": "Item condition",
      "value_id": "2230284",
      "value_name": "New",
      "value_struct": null,
      "values": [
        {
          "id": "2230284",
          "name": "New",
          "struct": null,
          "source": 1054850885297509
        }
      ],
      "attribute_group_id": "OTHERS",
      "attribute_group_name": "Otros",
      "source": 1054850885297509
    },
    {
      "id": "MODEL",
      "name": "Model",
      "value_id": null,
      "value_name": "A-59081-6",
      "value_struct": null,
      "values": [
        {
          "id": null,
          "name": "A-59081-6",
          "struct": null,
          "source": 1054850885297509
        }
      ],
      "attribute_group_id": "OTHERS",
      "attribute_group_name": "Otros",
      "source": 1054850885297509
    }
  ],
  "pictures": [
    {
      "source": "http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg"
    }
  ],
  "description": {
    "plain_text": "this is a test item"
  }
}

Response:

{
    "id": "CBT936662945",
    "site_id": "CBT",
    "title": "Test Item - For Loadtest Tests",
    "subtitle": null,
    "seller_id": 526124693,
    "category_id": "CBT11796",
    "official_store_id": null,
    "price": 15.1,
    "base_price": 15.1,
    "original_price": null,
    "inventory_id": null,
    "currency_id": "USD",
    "initial_quantity": 100,
    "available_quantity": 100,
    "sold_quantity": 0,
    "sale_terms": [
        {
            "id": "WARRANTY_TIME",
            "name": "Warranty time",
            "value_id": null,
            "value_name": "90 days",
            "value_struct": {
                "number": 90,
                "unit": "days"
            },
            "values": [
                {
                    "id": null,
                    "name": "90 days",
                    "struct": {
                        "number": 90,
                        "unit": "days"
                    }
                }
            ]
        },
        {
            "id": "WARRANTY_TYPE",
            "name": "Type of warranty",
            "value_id": "2230279",
            "value_name": "Factory warranty",
            "value_struct": null,
            "values": [
                {
                    "id": "2230279",
                    "name": "Factory warranty",
                    "struct": null
                }
            ]
        }
    ],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_pro",
    "start_time": "2020-06-05T20:30:52.276Z",
    "stop_time": "2040-05-31T04:00:00.000Z",
    "end_time": "2040-05-31T04:00:00.000Z",
    "expiration_time": "2020-08-24T20:30:52.364Z",
    "condition": "new",
    "permalink": "",
    "pictures": [
        {
            "id": "651485-CBT42094098772_062020",
            "url": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
            "secure_url": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
            "size": "500x500",
            "max_size": "500x500",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [
        {
            "id": "CBT936662945-2707505771"
        }
    ],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": [],
        "logistic_type": "not_specified",
        "store_pick_up": false
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 1087531567,
        "comment": "",
        "address_line": "Calle falsa 212",
        "zip_code": "22344",
        "city": {
            "id": "Q04tQ1FDaG9uZ3Fpbmc",
            "name": "Chongqing"
        },
        "state": {
            "id": "CN-CQ",
            "name": "Chongqing"
        },
        "country": {
            "id": "CN",
            "name": "China"
        },
        "latitude": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "",
                "name": ""
            },
            "city": {
                "id": "",
                "name": ""
            },
            "state": {
                "id": "",
                "name": ""
            }
        }
    },
    "seller_contact": null,
    "location": {},
    "geolocation": {
        "latitude": "",
        "longitude": ""
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "PACKAGE_HEIGHT",
            "name": "Package height",
            "value_id": null,
            "value_name": "10 cm",
            "value_struct": {
                "number": 10,
                "unit": "cm"
            },
            "values": [
                {
                    "id": null,
                    "name": "10 cm",
                    "struct": {
                        "number": 10,
                        "unit": "cm"
                    }
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "FOOTWEAR_TYPE",
            "name": "Footwear type",
            "value_id": null,
            "value_name": "Zapatilla",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Zapatilla",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "PACKAGE_WIDTH",
            "name": "Package width",
            "value_id": null,
            "value_name": "10 cm",
            "value_struct": {
                "number": 10,
                "unit": "cm"
            },
            "values": [
                {
                    "id": null,
                    "name": "10 cm",
                    "struct": {
                        "number": 10,
                        "unit": "cm"
                    }
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "PACKAGE_LENGTH",
            "name": "Package length",
            "value_id": null,
            "value_name": "10 cm",
            "value_struct": {
                "number": 10,
                "unit": "cm"
            },
            "values": [
                {
                    "id": null,
                    "name": "10 cm",
                    "struct": {
                        "number": 10,
                        "unit": "cm"
                    }
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "PACKAGE_WEIGHT",
            "name": "Package weight",
            "value_id": null,
            "value_name": "0.7 lb",
            "value_struct": {
                "number": 0.7,
                "unit": "lb"
            },
            "values": [
                {
                    "id": null,
                    "name": "0.7 lb",
                    "struct": {
                        "number": 0.7,
                        "unit": "lb"
                    }
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "BRAND",
            "name": "Brand",
            "value_id": null,
            "value_name": "DOMINIQ",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "DOMINIQ",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "GENDER",
            "name": "Gender",
            "value_id": "371795",
            "value_name": "Babies",
            "value_struct": null,
            "values": [
                {
                    "id": "371795",
                    "name": "Babies",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "ITEM_CONDITION",
            "name": "Item condition",
            "value_id": "2230284",
            "value_name": "New",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "New",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        },
        {
            "id": "MODEL",
            "name": "Model",
            "value_id": null,
            "value_name": "A-59081-6",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "A-59081-6",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Others"
        }
    ],
    "warnings": [],
    "listing_source": "",
    "variations": [],
    "thumbnail": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "secure_thumbnail": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "status": "active",
    "sub_status": [],
    "tags": [
        "immediate_payment"
    ],
    "warranty": "Factory warranty: 90 days",
    "catalog_product_id": null,
    "domain_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2020-06-05T20:30:52.485Z",
    "last_updated": "2020-06-05T20:30:52.485Z",
    "health": null,
    "catalog_listing": false,
    "item_relations": []
}
Note:
For the Global Selling items, the site_id must be “CBT”. The currency_id must be USD and the content must be in English.

Codes errors reference

Error Error message Description Possible 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 invalid. To 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.
requiresPictures
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.

Product status

The available status to parent and child items are active or paused. You can see how to change the status:

Parent item (CBTXXX) Children item
- active
- paused
- active
- paused
- deleted

Example to pause a CBT item:

curl -X PUT https://api.mercadolibre.com/items/$ITEM_ID?access_token=$ACCESS_TOKEN

{
    "status":"paused"
}
Note:
Request the /items resource with the parent id (CBT item id), and put the status to modify the status.

Response:

{
    "id": "CBT927817181",
    "site_id": "CBT",
    "title": "Test Item - For Loadtest Tests",
    "subtitle": null,
    "seller_id": 526124693,
    "category_id": "CBT11796",
    "official_store_id": null,
    "price": 15.1,
    "base_price": 15.1,
    "original_price": null,
    "inventory_id": null,
    "currency_id": "USD",
    "initial_quantity": 9999,
    "available_quantity": 9999,
    "sold_quantity": 0,
    "sale_terms": [],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_pro",
    "start_time": "2020-05-13T21:35:34.000Z",
    "stop_time": "2040-05-08T04:00:00.000Z",
    "end_time": "2040-05-08T04:00:00.000Z",
    "expiration_time": "2020-08-24T19:36:37.958Z",
    "condition": "new",
    "permalink": "",
    "pictures": [],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {...},
    "international_delivery_mode": "none",
    "seller_address": {...},
    "seller_contact": null,
    "location": {},
    "geolocation": {...},
    "coverage_areas": [],
    "attributes": [...],
    "warnings": [],
    "listing_source": "",
    "variations": [],
    "thumbnail": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "secure_thumbnail": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "status": "paused",
    "sub_status": [],
    "tags": [
        "immediate_payment"
    ],
    "warranty": "Factory warranty: 90 days",
    "catalog_product_id": null,
    "domain_id": "CBT-BABIES_FOOTWEAR",
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2020-05-13T21:35:34.000Z",
    "last_updated": "2020-06-05T19:36:37.989Z",
    "health": null,
    "catalog_listing": false,
    "item_relations": []
}

Example to pause a child item:

curl -X PUT https://api.mercadolibre.com/marketplace/items/$ITEM_ID?access_token=$ACCESS_TOKEN

{
    "site_id": "MLM",
    "logistic_type": "remote",
    "status":"paused"
}
Note:
Request the /marketplace/items resource with the parent id (CBT item id), and put the site and logistic type to modify the child status.

Response:

{
    "item_id": "CBT935763550",
    "parent_id": "CBT935763550",
    "logistic_type": "remote",
    "site_id": "MLM",
    "errors": null
}

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 https://api.mercadolibre.com/marketplace/items/CBT946690995?access_token=$ACCESS_TOKEN
 -d '{
   "site_id": "MLM",
   "logistic_type": "remote",
   "deleted": true
}'

Response:

{
   "item_id": "CBT946690995",
   "parent_id": "CBT946690995",
   "logistic_type": "remote",
   "site_id": "MLM",
   "errors": null
}

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

A detailed description will improve your chances to sell a product and will save time from answering questions. 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.

Note:
Please, the product description must be in plain text.

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 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 -X GET https://api.mercadolibre.com/categories/$CATEGORY_ID/attributes

Example:

curl -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 -X GET https://api.mercadolibre.com/categories/$CATEGORY_ID/sale_terms

Example:

curl -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.

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.
To Global Site Item, this value is always "gold_pro".


How to know in which marketplaces can I 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 -X GET http://api.mercadolibre.com/marketplace/users/$USER_ID?access_token=$ACCESS_TOKEN

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

curl -X GET http://api.mercadolibre.com/marketplace/users/471826944?access_token=$ACCESS_TOKEN

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.


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.

Request:

curl -X POST https://api.mercadolibre.com/marketplace/items/$ITEM_ID?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/marketplace/items/CBT1234?access_token=$ACCESS_TOKEN 
  -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.
access_token: It is the token that you must create with the credentials provided and the application generated by the seller or the integrator.

Important:
On September 21 we will add two new 400 errors related to validations for marketplace item listings:
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.
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

Modify Marketplace item details

With this resource you may modify Global Selling items on the site where the user requires it. In order to consume this service, a call to the PUT method should be made, just like it is shown in the following request:

curl -X PUT https://api.mercadolibre.com/marketplace/items/CBT1234?access_token=$ACCESS_TOKEN 
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "site_id": "MLM",
    "logistic_type": "remote",
    "price": 1,
    "description": {
        "plain_text": "Aqui se debe ingresar la descripción del ítem"
    }
}
'

Response:

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

Parameters

id: It is the Global Selling item identifier, which is created through a call to the local API.
access_token: it is the token that you must create with the provided credentials and the application generated by the seller or the integrator.


Errors

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.

Get the Marketplace item details

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

Request:

curl -X GET http://api.mercadolibre.com/marketplace/items/MLM720042224?access_token=$ACCESS_TOKEN

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.
access_token: it is the token that you must create with the provided credentials and the application generated by the seller or the integrator.


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

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

List an Official Store item

To list an item from an Official Store, you must add the "official_store_id" attribute in the JSON when listing the Marketplace Item.

The official_store_id is applied per user, in the event that in a marketplace there is only one enabled store and it is not added in the request, when publishing it will be added by default. In case you have more than one store, you must specify which one should be used.

Request:

curl -X POST http://api.mercadolibre.com/marketplace/items/$ITEM_ID?access_token=$ACCESS_TOKEN

Example:

curl -X POST http://api.mercadolibre.com/marketplace/items/CBT923149287?access_token=$ACCESS_TOKEN
  -H 'Content-Type: application/json'
  -d '{
    "config": [
        {
            "site_id": "MLM",
            "logistic_type": "remote",
            "official_store_id":123
        },
        {
            "site_id": "MLB",
            "logistic_type": "remote"
        }
    ]
}'
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.

Next: Sync and modify listings.