Global Listing

Get listing limit

Get the limit quantity of listings available per each marketplace user for a particular global user.

Request:

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

Response:

[
    {
        "user_id": 823718333,
        "site_id": "MLM",
        "logistic_type": "remote",
        "quota": 15000,
        "total_items": 6
    },
    {
        "user_id": 823714222,
        "site_id": "MLC",
        "logistic_type": "remote",
        "quota": 15000,
        "total_items": 0
    },
    {
        "user_id": 823714444,
        "site_id": "MLB",
        "logistic_type": "remote",
        "quota": 0,
        "total_items": 14
    }
]

Response fields

quota: limit quantity of active items that the seller can have for each marketplace.
site_id: identification for each marketplace site or country.
total_items: active listings quantity that the seller has for this site.

Listing flow

Defining Attributes

All listings must be created in English and priced in US dollars (USD). Some fields are mandatory when creating a listing, while others can be optional or manually added later. These fields determine how the listing appears, how buyers can make purchases, and its position in search results, among other factors. To maximize your chances of making a sale, ensure that this information is as accurate and clear as possible.

The following information will guide you through each of the fields that must be included in the request body and how they should be formatted. At the end of this section, you'll find an example request for creating a listing.

Sites To Sell

This attribute is required and represents the configurations for each marketplace where you wish to sell the item. Each configuration can include the following attributes:

• Site ID [Mandatory]: Specifies the country where the product will be listed.
• Logistic Type [Mandatory]: Defines the shipping logistics, such as remote or fulfillment.
• Prices: Allows you to set a different price for each marketplace. If no price is specified, the global item price will be applied by default. Prices must be provided in US Dollars.
• Listing Type ID: Lets you choose the listing type between Classic “gold_special” and Premium “gold_pro” for each marketplace, depending on what is permitted by the country and the category. The default value is set to Premium.

{
  "sites_to_sell": [
    {
      "site_id": "MLN",
      "logistic_type": "remote",
      "price": 20
    },
    {
      "site_id": "MLN",
      "logistic_type": "fulfillment"
    },
    {
      "site_id": "MLC",
      "logistic_type": "remote",
      "listing_type_id": "gold_pro"
    },
    {
      "site_id": "MLC",
      "logistic_type": "fulfillment"
    },
    {
      "site_id": "MLB",
      "logistic_type": "remote",
      "price": 30,
      "listing_type_id": "gold_special"
    },
    {
      "site_id": "MCO",
      "logistic_type": "remote"
    }
  ]
}

Title

The title is crucial for buyers to find your listing, so it should be as clear and specific as possible. Follow these recommendations:

• Structure: Create the title using the format Product + Brand + Product Key Specifications that help identify the product.
• Avoid Extra Information: Do not include details about other services like returns, free shipping, or installment payments in the title.
• Condition of the Product: If your product is new, used, or refurbished, don’t include this information in the title—add it to the product features, and we will display it in the listing details.
• Discounts: If you offer a discount, we will display the percentage of the promotion and use a special label to highlight it. There’s no need to add this information to the title.
• Formatting: Separate words with spaces, and avoid using punctuation or symbols. Be sure to check for any spelling errors.
• Title Length: The maximum length of the title is determined by the category of the product ("max_title_length").

Note: Mentioning stock quantities in the title is not allowed—doing so may result in your listing being moderated.

{
 ....
  "title":"Item title must be written in english",
 ...
}

Description

Providing detailed information in your product descriptions will significantly increase your chances of making a sale and help you avoid answering repetitive questions. Your description should include the product’s technical features and its key advantages over competitors. This enables buyers to quickly find all the relevant specifications. We suggest the following best practices:

• Ensure that the details you include in the description are not already covered in the product’s data sheet.
• Organize the information clearly using formatting tools such as uppercase letters, hyphens, and proper spacing.
• Keep the description concise and review it to ensure it’s not too lengthy.
• You can include the description in the request body using the following format:

{
 ....
  "description": {
  "plain_text": "Your description"
  }
 ...
}

Condition

When listing an item you need to declare if the condition is new. This attribute is mandatory to complete a listing operation.

{
 ...
  "condition":"new",
 ...
}

Available Quantity

This attribute defines the stock, that's the number of products available for selling on this item. The maximum value is defined by the chosen listing type. See more details in the listing type section. If your listing has variations, the available quantity must be specified in each variation. Learn more about variations.

Without Variations

{
 ...
  "available_quantity":100
 ...
}

With Variations

{
 ...
  "variations": [
  {
    ...
    "available_quantity": 10,
    ...
  },
{
    ...
    "available_quantity": 40,
    ...
  }
]
 ...
}

Pictures

Nice pictures can make an item more appealing and give buyers a better idea of the item’s appearance. We provide two options:

• We recommend to follow the instructions on the pictures documentation.
• You can add an array of pictures on the Request Body.

{
 ...
 "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"}
 ]
 ...
}

Category

Sellers must define a category in Mercado Libre site. This attribute is mandatory and only accepts pre-established ids. Read to get a category suggestion.

{
 ...
  "category_id":"CBT12683",
 ...
}

Price

This is a mandatory attribute, when you define a new listing it must have a price. We suggest you search similar listings on our marketplace to know the best price for your products and increase your competitiveness. If you define a price and then you’re not happy with it, you can change it later. learn to modify items. You can also specify the price for each marketplace in the attribute "sites_to_sell", as shown previously. If the price is not specified for each marketplace, the price of all the marketplace items will be the same as the global item.

{
 ...
  "price":20,
 ...
}

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

You can have multiple variations of the same product, maintaining a different stock for each one. This way, when you sell a listing, you will see in the purchase order the variation chosen by the buyer, thus facilitating the after-sales process. Learn more about Variations.

{
 ...
  "variations": [
  {
    ...
    "available_quantity": 10,
    "attribute_combinations": [
      {
        "id": "COLOR",
        "value_name": "Blue"
      },
      ...
    ],
    "picture_ids":[
      "http://image-us.bigbuy.win/upload/image/assistant/TJA01327/TJA01327-2.jpg"  
]
    ...
  },
...
   ]
 ...
}

Attributes

Some attributes are defined by the product category, we recommend you to review the Atributtes Docuimentation to learn about category attributes and supported values. You can add your attributes as an array of elements in the Request Body. Additionally, it is mandatory to always specify the package's attributes: length, width, height, weight..

{
 ...
  "attributes": [
  {
    ...
    "id": "IS_WIRELESS",
"value_name": "Yes"
...
  },
...
   ]
 ...
}

Product warranty

Within a listing’s “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.

{
 ...
  "sale_terms": [
  {
    ...
    "id": "WARRANTY_TYPE",
"value_name": "Seller warranty"
...
  },
{
    ...
    "id": "WARRANTY_TIME",
"value_name": "30 days"
...
  },
...
   ]
 ...
}

Listing the Item

In a single request you will be able to list your listing in all the Marketplaces of your preference. Make a POST request with an access token and all the attributes of your product previously described. The listing quota per site is 10.000 request per day:

Request

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST http://api.mercadolibre.com/global/items

Example

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST http://api.mercadolibre.com/global/items 
{
   "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",
      {
         "id":"GENDER",
         "name":"Gender",
         "value_id":"371795",
         "value_name":"Babies",
      },
      {
         "id":"ITEM_CONDITION",
         "name":"Item condition",
         "value_id":"2230284",
         "value_name":"New",
      },
      {
         "id":"MODEL",
         "name":"Model",
         "value_id":null,
         "value_name":"A-59081-6",
      },
      {
         "id":"COLOR",
         "name":"Color",
         "tags":{
            "allow_variations":true,
            "defines_picture":true,
            "required":true
         },
         "hierarchy":"CHILD_PK",
         "relevance":1,
         "value_type":"string",
         "value_max_length":255,
         "values":[
            {
               "id":"52010"
            }
         ]
      },
      {
         "id":"SIZE",
         "name":"Size",
         "value_id":null,
         "value_name":"7 M US Women / 5.5 M US Men",
         "tags":{
            "allow_variations":true,
            "required":true
         },
         "hierarchy":"CHILD_PK",
         "relevance":1,
         "value_type":"string",
         "value_max_length":255,
      },
      {
         "id":"GTIN",
         "name":"Universal product code",
         "value_name":"9102110000",
         "tags":{
            "multivalued":true,
            "required":true,
            "variation_attribute":true,
            "used_hidden":true,
            "validate":true
         },
         "hierarchy":"PRODUCT_IDENTIFIER",
         "relevance":1,
         "type":"product_identifier",
         "value_type":"string",
         "value_max_length":255,
         "tooltip":"How do I recognize it? It is an 8 to 14 digit number next to the barcode, on the product box or on its label.\n\n![Universal product code](https://http2.mlstatic.com/static/org-img/sd-landings/assets/pi-tooltip.png)",
      }
   ],
   "pictures":[
      {
         "source":"http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg"
      }
   ]
}

Response

{
    "item_id": "CBT1234567890",
    "seller_id": 12345678,
    "site_id": "CBT",
    "site_items": [
        {
            "item_id": "MLM1234567890",
            "seller_id": 4567890,
            "site_id": "MLM",
            "logistic_type": "remote"
        },
        {
            "item_id": "MLM0987654321",
            "seller_id": 4567890,
            "site_id": "MLM",
            "logistic_type": "fulfillment"
        },
        {
            "item_id": "MLB1234567890",
            "seller_id": 1098765,
            "site_id": "MLB",
            "logistic_type": "remote"
        },
        {
            "item_id": "MCO1234567890",
            "seller_id": 6543219,
            "site_id": "MCO",
            "logistic_type": "remote"
        }
    ]
}

In this example, the listing in all marketplaces was successful, but the response can also contain error messages.

Responses and Valiations

The Global Selling API response will be successful when the transaction was processed successfully, returning a status code 200. This result represents the information of your product is correct and complete. However, it is necessary to verify each marketplace listing result, to make sure that the listing was created correctly or if there is a validation error for a specific country and logistics.

Notes: It is possible to obtain an error in all marketplace listings. Make sure to verify all of them.

Example

[
    {
        "parent_id": "CBT1234567890",
        "site_id": "MLM",
        "item_id": "MLM1234567890",
        "logistic_type": "remote"
    },
    {
        "parent_id": "CBT1234567890",
        "site_id": "MLB",
        "item_id": "MLB1234567890",
        "logistic_type": "remote"
    },
    {
        "site_id": "MCO",
        "logistic_type": "remote",
        "errors": [
            {
                "message": "validation error",
                "error": "validation_error",
                "status": 400,
                "cause": [
                    {
                        "department": "cbt-item-validation",
                        "cause_id": 5002,
                        "type": "ERROR",
                        "code": "item.price",
                        "references": [
                            "Colombia",
                            "",
                            "U$S2000.00"
                        ],
                        "message": "Maximum price to list or modify in Colombia : U$S2000.00",
                        "custom_data": null
                    }
                ]
            }
        ]
    }
]

If the response contains a status code 4xx, this means that the errors are related to the Global Item and not to a specific marketplace.

Example

{
    "message": "Validation error",
    "error": "validation_error",
    "status": 400,
    "cause": [
        {
            "department": "items",
            "cause_id": 103,
            "type": "error",
            "code": "item.available_quantity.invalid",
            "references": [
                "item.available_quantity"
            ],
            "message": "Stock of item should at least 0."
        },
        {
            "department": "items",
            "cause_id": 123,
            "type": "error",
            "code": "item.available_quantity.invalid",
            "references": [
                "item.available_quantity"
            ],
            "message": "The field is mandatory for selected category."
        }
    ]
}

Activate in another marketplace

TIf you have an existing listing in one (or more) of our marketplaces, you can publish the same product in other marketplaces that you did not consider before, using the information of the existing listing. For example, if you have a listing in Brazil(MLB) and you want to sell the same product in Mexico (MLM), you can make the following request with the existing global listing, specifying the new marketplaces where you want to sell.

Remember that you can set a different price in each marketplace, you can specify this information with the field "price" under the "sites_to_sell " field. If no price is sent, the product will use the price set on the global listing.

Also, you can create the listing with a different listing type (available for MLB, MLC and MCO), specify this information under "sites_to_sell" with the field "listing_type_id".

curl --location 'https://api.mercadolibre.com/global/items/CBT1234567890?caller.id=1234567890' \
--header 'parent-item-info: true' \
--header 'Content-Type: application/json' \
--data '{
    "sites_to_sell": [
        {
            "site_id": "MLM",
            "logistic_type": "remote",
            // Optional
            "listing_type_id": "gold_pro",
            "price": 200
        }
    ]
}'