Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 30/01/2026

Virtual kits

Create irresistible offers and sell more with Virtual Kits.

This feature lets you group several of your products into a single listing to deliver a superior shopping experience and boost your sales. The big advantage is that its inventory is “virtual”: stock is calculated automatically in real time based on the availability of its individual components, without having to assemble bundles in advance.

In this guide, we’ll show you step by step how to search for and select eligible products, publish your first kit, modify it, and manage its sales.

Get ready to take your listings to the next level!

Important:
The initiative will be in production starting October 2025

Special considerations

Here are some considerations to keep in mind when publishing a kit item under the new User Products model.

  • The kit item is immutable; you won’t be able to modify its configuration regarding the products it’s made of and their quantities, but you can modify its sales conditions.
  • Each kit will consist of a maximum of 6 products and a minimum of 2. Each product within the kit can have up to 10 units.
  • The stock of a kit item will be calculated based on the stock of the products that compose it and the configured quantity for each of them within the kit.
    • Example: For the “Fernet + 2 Cokes Kit”, if we have 4 fernets and 4 cokes, we can only assemble 2 kits; therefore, the kit stock will be 2.
  • The user products of the components will have the “kit_component” tag.
  • Creating duplicate user products (kits with the same components and quantities) will not be allowed.
  • The main component product will be the first one in the user product’s components list.
  • We will not allow creating user product kits with attribute “item_condition” != “new”.
  • Kits can be single-channel. For now, only available for marketplace.
  • Full kits will NOT have “inventory_id”.
  • To get the current sales price of the kit item, you must use the /sale_price resource.
Note:
Non-certified partners: To run tests, please add your test user in the following form so we can enable it for creating virtual kits.

Component product finder

Before you can create a kit, you need to select which products will make it up.
This search tool lets you find and validate products in your inventory that are eligible to be part of a kit. As you add products, the finder will apply eligibility filters to ensure you only see compatible options, making the assembly process easier.


Call:

curl -L -X POST \
https://api.mercadolibre.com/users/$SELLER_ID/kits/components/search?searchText=$STRING&limit=2 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN'
  1. Main Product Search.
    Start by searching for the first product that will be the potential main component of your kit. The initial search is performed without compatibility filters.

  2. Selection and Search for Additional Components.
    Once you select the main product, you can add the eligibility filter "ONLY_ELIGIBLE". This means that in subsequent searches you will only see products compatible with those already added to the kit.

  3. Add All Components.
    Continue searching and adding products until your kit is complete. Remember that a kit can have between 2 and 6 different products.

  4. Publish Your Kit.
    Once you’ve added all components, you can proceed to the final publication of the kit.

Call:

curl -L -X POST \
'https://api.mercadolibre.com/users/$SELLER_ID/kits/components/search?searchText=$STRING&limit=2' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Request body - Search with no products added


You only need to indicate the active channel, which for now is marketplace.

{
  "active_channels": [
    "marketplace"
  ]
}

Request body - Search with a selected main component and a list of added components; also requesting only eligible products


You must include the ID of the main product (main_product_id), a list with the IDs of products already added (added_products), and the eligibility filter to ensure compatibility "filters": ["ONLY_ELIGIBLE"].

{
  "main_product_id": "MLAU3044953709",
  "added_products": [
    "MLAU2926276084",
    "MLAU408338970",
    "MLAU3044953709",
    "MLAU3053532482",
    "MLAU1272626713"
  ],
  "active_channels": [
    "marketplace"
  ],
  "search_filters": {
      "only_eligible": "ONLY_ELIGIBLE",
      "family_id": null
   }
}

Available filters

To provide greater flexibility in search results, the following filters are available and must be sent within the search_filters property.


Only eligible: This filter ensures that all results are eligible, excluding products that cannot be part of the kit (those whose type property has the value available).

Example:

{
  "search_filters": {
    "only_eligible": "ONLY_ELIGIBLE"
  }
}

Family ID: This filter allows you to restrict the search to a specific family ID, returning all products that belong to the UP family.

Example:

{
  "search_filters": {
    "family_id": 515477844859253
  }
}

Filter combination: Filters can be combined with each other. For example, you can retrieve only eligible products from a specific family or send them individually.

Example:

{
  "search_filters": {
    "only_eligible": "ONLY_ELIGIBLE",
    "family_id": 515477844859253
  }
}

Response:

{
  "paging": {
    "search_after_hash": null
  },
  "search_text": "cel",
  "result_state": "AVAILABLE",
  "products": [
    {
      "id": "MLAU1272335441", //UP not available - "type": "non_available"
      "title": "Celular Google Pixel 8 Pro 256 Gb  Negro 12 Gb Ram Azul Oscuro",
      "type": "non_available",
      "thumbnail": {
        "secure_url": "https://http2.mlstatic.com/D_617565-MLA81954291020_022025-O.jpg",
        "id": "617565-MLA81954291020_022025"
      },
      "product_ids": [
        {
          "id": "MLA1912685920",
          "type": null
        }
      ],
      "category_name": "Celulares",
      "stock": {
        "title": "Mercado Envíos",
        "locations": [
          {
            "type": "selling_address",
            "quantity": 8,
            "value": "In your warehouse: 8 units"
          }
        ]
      },
      "reasons": [
        {
          "id": "IS_NOT_NEW",
          "message": "You can’t sell this product in a kit because it’s used or refurbished."
        }
      ]
    },
    {
      "id": "MLAU1272626713", //UP available -  "type": "available"
      "title": "Samsung Galaxy S23+ 8gb + 512gb Liberado Rosa Color Rosa",
      "type": "available",
      "thumbnail": {
        "secure_url": "https://http2.mlstatic.com/D_612324-MLA80821630841_112024-O.jpg",
        "id": "612324-MLA80821630841_112024"
      },
      "product_ids": [
        {
          "id": "MLA1450811023",
          "type": null
        }
      ],
      "category_name": "Celulares",
      "stock": {
        "title": "Mercado Envíos",
        "locations": [
          {
            "type": "selling_address",
            "quantity": 1,
            "value": "In your warehouse: 1 unit"
          }
        ]
      },
      "reasons": []
    },
    {...},
    {...},
    {...},
    {...}
]
}

The API response will let you know whether a product is suitable to be included in the kit:

  • Available Products: A product with "type": "available" in the response means it is eligible and can be added to your kit without issues.
  • Unavailable Products: If a product appears as "type": "non_available", you won’t be able to select it. The reason will be specified in the reasons field.

Response:

{
  "paging": {
    "search_after_hash": null
  },
  "search_text": "PRUEBA_SIN_RESULTADOS",
  "result_state": "EMPTY",
  "products": []
}

Create virtual kit

Once you’ve selected all the component products using the finder, you’re ready to publish a Kit. This process consists of grouping the selected products (user_product_id) into a new single listing.

Call:

curl -L -X POST https://api.mercadolibre.com/items/kits \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer Bearer $ACCESS_TOKEN \
-d '{
  "family_name": "KIT lapiz y acondicionador prueba",
  "channels": [
    "marketplace"
  ],
  "thumbnail": {
    "id": "981862-MLA82943132528_032025",
    "secure_url": "https://http2.mlstatic.com/D_707148-MLC54405569361_032023-O.jpg"
  },
  "price": 30,
  "currency_id": "BRL",
  "listing_type_id": "gold_special",
  "official_store_id": null,
  "bundle": {
    "type": "kit",
    "components": [
      {
        "type": "user_product",
        "user_product_id": "MLB03108136853",
        "quantity": 2,
        "automatic_price": null
      },
      {
        "type": "user_product",
        "user_product_id": "MLB03293311857",
        "quantity": 1,
        "automatic_price": null
      }
    ]
  }
}'

Bundle structure

The bundle field is the main node that defines how a product kit is structured. That is, it describes which products it includes, in what quantities, and how its price will be defined.

  • type: Indicates that the object represents a grouped set of products (a kit), and not an individual product.
  • components: A list of products that make up the kit. Each product in this list has 3 key data points:
    • user_product_id: The component product’s unique ID.
    • quantity: Defines how many units of that product are included in the kit. (Limit: maximum 10 units per product.)
    • automatic_price: Determines how the kit price is calculated.
      • If the field is:
        • null: the price is set manually.
        • adding the discount field. Important: if a discount is configured, it must be the same for all components in the kit.

Nota:
For sellers in MLA with the tax condition of Responsable Inscripto, the values for IVA (VALUE_ADDED_TAX) and Internal Taxes (IMPORT_DUTY) will be directly inherited from the component items.

Body - Without price synchronization

To create a kit without price synchronization, you must send the field automatic_price = null.

{
   "family_name": "Kit Aventura: 1 Motosserra Elétrica 2200W 16 Pol + 1 Canivete Retrátil Preto/Madeira",
   "channels": [
       "marketplace"
   ],
  "thumbnail": {
       "id": "981862-MLA82943132520_032025"
   },
   "price": 2001,
   "currency_id": "BRL",
   "official_store_id": null,
   "listing_type_id": "gold_pro",
   "bundle": {
       "type": "kit",
       "components": [
           {
               "type": "user_product",
               "user_product_id": "MLBU3256534109",
               "quantity": 1,
               "automatic_price": null
           },
           {
               "type": "user_product",
               "user_product_id": "MLBU3235954953",
               "quantity": 1,
        	  "automatic_price": null
           }
       ]
   }
}

Body - Price synchronization

To synchronize the kit’s price with the price of its component UPs, include in each component automatic_price with the discount field.

The discount value must be the same for all kit components. Different discounts per UP are not allowed, and discount is sent as a decimal between 0 and 1 (for example, 0.30 = 30%).

When synchronizing, the current price of each UP is taken and the defined discount is applied to calculate the kit price. That’s why the price field doesn’t need to be sent.

{
  "family_name": "Kit Aventura: 1 Motosserra Elétrica 2200W 16 Pol + 1 Canivete Retrátil Preto/Madeira",
  "channels": [
    "marketplace"
  ],
  "thumbnail": {
    "id": "981862-MLA82943132528_032025",
    "secure_url": "https://http2.mlstatic.com/D_707148-MLC54405569361_032023-O.jpg"
  },
  "currency_id": "BRL",
  "official_store_id": null,
  "listing_type_id": "gold_pro",
  "bundle": {
    "type": "kit",
    "components": [
      {
        "type": "user_product",
        "user_product_id": "MLBU32565354109",
        "quantity": 1,
        "automatic_price": { "discount": 0.30 }
      },
      {
        "type": "user_product",
        "user_product_id": "MLBU3235954953",
        "quantity": 2,
        "automatic_price": { "discount": 0.30 }
      }
    ]
  }
}

Successful kit creation response


{
  "id":"MLB5519759426",
  "site_id":"MLB",
  "title":"Kit Aventura: 1 Motosserra Elétrica 2200w 16 Pol + 1 Canivete Retrátil Preto/madeira",
  "subtitle":null,
  "seller_id":655590662,
  "category_id":"MLB269947",
  "user_product_id":"MLBU3297286069",
  "official_store_id":null,
  "price":2001,
  "base_price":2001,
  "original_price":null,
  "inventory_id":null,
  "currency_id":"BRL",
  "initial_quantity":96,
  "available_quantity":96,
  "sold_quantity":0,
  "sale_terms":[
    
  ],
  "buying_mode":"buy_it_now",
  "listing_type_id":"gold_pro",
  "historical_start_time":"2025-07-24T21:10:45.627Z",
  "family_name":"Kit Aventura: 1 Motosserra Elétrica 2200w 16 Pol + 1 Canivete Retrátil Preto/madeira",
  "family_id":5086163669878745,
  "start_time":"2025-07-24T21:10:45.627Z",
  "stop_time":"2045-07-19T04:00:00.000Z",
  "end_time":"2045-07-19T04:00:00.000Z",
  "expiration_time":"2025-10-12T21:10:45.704Z",
  "condition":"new",
  "permalink":"http://produto.mercadolivre.com.br/MLB-5519759426-kit-aventura-1-motosserra-eletrica-2200w-16-pol-1-canivete-retratil-pretomadeira-_JM",
  "pictures":[
     {
        "id":"981862-MLA82943132520_032025",
        "url":"http://mla-s1-p.mlstatic.com/981862-MLA82943132520_032025-O.jpg",
        "secure_url":"https://mla-s1-p.mlstatic.com/981862-MLA82943132520_032025-O.jpg",
        "size":"500x461",
        "max_size":"1065x984",
        "quality":""
     },
     {
        "id":"800684-MLU71335801005_082023",
        "url":"http://mlu-s2-p.mlstatic.com/800684-MLU71335801005_082023-O.jpg",
        "secure_url":"https://mlu-s2-p.mlstatic.com/800684-MLU71335801005_082023-O.jpg",
        "size":"500x489",
        "max_size":"1200x1174",
        "quality":""
     },
     {
        "id":"784795-MLU73420522013_122023",
        "url":"http://mlu-s1-p.mlstatic.com/784795-MLU73420522013_122023-O.jpg",
        "secure_url":"https://mlu-s1-p.mlstatic.com/784795-MLU73420522013_122023-O.jpg",
        "size":"500x412",
        "max_size":"1200x989",
        "quality":""
     }
  ],
  "video_id":null,
  "descriptions":[
  ],
  "accepts_mercadopago":true,
  "non_mercado_pago_payment_methods":[
    
  ],
  "shipping":{
     "mode":"me2",
     "local_pick_up":false,
     "free_shipping":true,
     "methods":[  
     ],
     "dimensions":null,
     "tags":[
        "mandatory_free_shipping"
     ],
     "logistic_type":"cross_docking",
     "store_pick_up":false
  },
  "international_delivery_mode":"none",
  "seller_address":{
     "id":1480628396,
     "comment":"",
     "address_line":"Grito de gloria 620",
     "zip_code":"01405001",
     "city":{
        "id":"BR-SP-44",
        "name":"São Paulo"
     },
     "state":{
        "id":"BR-SP",
        "name":"São Paulo"
     },
     "country":{
        "id":"BR",
        "name":"Brasil"
     },
     "latitude":-23.5587498,
     "longitude":-46.6341625,
     "search_location":{
        "neighborhood":{
           "id":"TUxCQkpBUm0xaTF2",
           "name":"Jardim Paulista"
        },
        "city":{
           "id":"TUxCQ1NQLTkxMjE",
           "name":"São Paulo Zona Sul"
        },
        "state":{
           "id":"TUxCUFNBT085N2E4",
           "name":"São Paulo"
        }
     }
  },
  "seller_contact":null,
  "location":{
    
  },
  "geolocation":{
     "latitude":-23.5587498,
     "longitude":-46.6341625
  },
  "coverage_areas":[
    
  ],
  "attributes":[],
  "warnings":[],
  "listing_source":"",
  "variations":[
    
  ],
  "thumbnail_id":"981862-MLA82943132520_032025",
  "thumbnail":"http://mlb-s1-p.mlstatic.com/981862-MLA82943132520_032025-I.jpg",
  "secure_thumbnail":"https://mlb-s1-p.mlstatic.com/981862-MLA82943132520_032025-I.jpg",
  "status":"active",
  "sub_status":[
    
  ],
  "tags":[
     "bundle",
     "cart_eligible",
     "good_quality_thumbnail",
     "immediate_payment",
     "kvs_primary",
     "test_item",
     "user_product_listing"
  ],
  "warranty":null,
  "catalog_product_id":null,
  "domain_id":"MLB-ELECTRIC_CHAINSAWS",
  "seller_custom_field":null,
  "parent_item_id":null,
  "differential_pricing":null,
  "deal_ids":[
    
  ],
  "automatic_relist":false,
  "date_created":"2025-07-24T21:10:46.275Z",
  "last_updated":"2025-07-24T21:10:46.957Z",
  "total_listing_fee":null,
  "health":null,
  "catalog_listing":false,
  "item_relations":[
    
  ],
  "channels":[
     "marketplace"
  ],
  "bundle":{
     "type":"kit",
     "components":[
        {
           "type":"user_product",
           "user_product_id":"MLBU3256534109",
           "quantity":1
        },
        {
           "type":"user_product",
           "user_product_id":"MLBU3235954953",
           "quantity":1
        }
     ]
  }
}

Identify a Kit item

Note:
You can differentiate/identify a kit via the bundle.type field: "kit". The user product will also have a bundle.components node where the user products that make up the kit are listed.

Additional considerations and clarifications:

  • Main component: The first product listed in the components array is considered the kit’s main component. The kit’s domain_id is inherited from this first product.
  • Immutability: Once identified as a kit, its composition (products and quantities within the bundle node) is immutable. You won’t be able to modify this structure after publication.
  • Tags: In addition to the bundle node, a kit item will include the "bundle" tag in its tags list, which is another useful indicator.

Call:

curl -X GET \
https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:


{
    "site_id": "MLA",
    "user_id": 678394720,
    "domain_id": "MLA-FERNET", -- Domain of the main product
    "catalog_product_id": null,
    "family_id": 5896969823350698505,
    "date_created": "2023-09-27T17:32:49.571+0000",
    "last_updated": "2024-02-08T15:54:33.846+0000",
    "id": "MLAU13654585",
    "name": "Fernet + 2 Cokes Kit",
    "attributes": [
        ....
    ],
    "pictures": [
    ],
    "thumbnail": {
        "secure_url": "https://http2.mlstatic.com/D_745037-MLC71731586739_092023-O.jpg",
        "id": "745037-MLA71731586739_092023"
    },
    "tags": ["bundle"],
    "bundle": {
          "type": "kit",
	     "components": [
            {
              "type": "user_product",
              "user_product_id": "MLAU654321" 
 	 	 "quantity": 1           
      	     },
            {
              "type": "user_product",
              "user_product_id": "MLAU654321"
 	  	 "quantity": 2                       
     }
        ]
    }
}
  • To identify that an item is a kit, you must check that it contains the "bundle" tag and also bundle.type = "kit".
  • To identify that a user product is a component of a kit, check that it contains the "kit_component" tag.
  • To identify that an item is a component of a kit, also check that it contains the "kit_component" tag.
  • If the queried item is NOT a kit, you simply won’t find the bundle node in the API response.

Find which Kits a UP is associated with

If you need to know whether one of your products is already part of any kit, this resource lets you easily check it.

Keeping track of which products you’ve included in kits is essential for managing your inventory and sales strategies. For example, if you plan to pause the sale of a product, it’s important to know whether this will affect the stock of any of your active kits.
You’ll be able to consult the Kits in which a component UP is associated at any given time.

Note: This resource only applies to querying the KITs in which that UP is present. It does not apply to Multi-parcel.

The query is performed using the component product’s user_product_id, not a listing’s item_id nor the kit’s user_product_id.


Call:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/bundles \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
  "user_product_id": "MLAU123456",
  "bundles": [
    "MLAU6788181",
    "MLAU6667788"
  ],
  "last_updated": "2024-09-13T12:16:00.000Z"
}

You will receive a 200 OK and a JSON containing the queried user_product_id and the bundles list with the user_product_id of each kit in which it participates.

If that User Product is not associated with any kit, the response will be status code 404:

{
  "error": "not_found",
  "message": "UserProductComponent not found: MLAU30701731699",
  "status": 404
}

If the allowed quota for the client.id is exceeded, the response will be status code 429:

{
  "error": "too_many_requests",
  "message": "client.id over quota",
  "status": 429
}

Modify Kit

Once you’ve published a kit, its main configuration becomes immutable. This means you cannot modify the products that compose it or their quantities. This rule ensures offer consistency for buyers and simplifies stock management.

However, you can modify the kit’s sales conditions, such as the title, price (if manual), description, or main image. Below, we explain in detail what you can and cannot change.

Fields in the Kit that can be modified

Field in the Kit Modifiable by the seller Remarks
Kit composition (products and quantities) No It’s the kit’s main characteristic and cannot be altered. If you try to modify the bundle node, you will receive a 400 Bad Request error with the message: "Updating the bundle node is not allowed".
Title (family_name) Yes You will be able to modify the (family_name) through the following resource, keeping in mind that it can only be modified if it does not have sales yet.
Channels (channels) No Kits are only available for "marketplace" and this field cannot be modified.
Price (price) Yes You can only modify the price if it does not have an automatic_price configuration (discount-based synchronization). If you change it manually, it will apply; if it’s set to synchronize, any manual change will be overwritten.
Stock (quantity / available_quantity) No It’s calculated and synchronized automatically based on the components’ availability. It is not managed manually.
Listing type (listing_type_id) Yes You can change it (e.g., from Classic to Premium) as long as all components allow it.
Shipping methods (shipping_method) No It is inherited from the component products and cannot be changed.
Domain/Category (domain_id) No It’s inherited from the main component product (the first in the list) and cannot be changed.
Description Yes You can edit it to add more details or improve the information for buyers.
Main image (thumbnail) Yes You can update the kit’s main image to enhance its visual appeal.

Updating allowed attributes

If you attempt to modify the kit’s configuration (for example, the bundle node), we will return the following error:

Response:

{
  "message": "Updating the bundle node is not allowed",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

To modify the allowed fields, you must make a PUT call to the items endpoint, specifying the kit’s item_id and the fields you want to change (for example, "price").

Call:

curl -L -X PUT https://api.mercadolibre.com/items/$ITEM_ID \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{"price": 4000}'

Get Kit sale price

To effectively manage your sales and finances, you need to understand not only the final price the buyer pays, but also how that amount is distributed among each of the products that make up the kit.

To obtain this detailed information, you must use the /sale_price resource. This endpoint will provide a complete breakdown of the kit’s price, including the value assigned to each component, the individual selling price of those components, and the impact of possible promotions.

For a kit, the /sale_price resource returns more information for your query. It’s included within the bundle field.

Call:

curl -L -X GET https://api.mercadolibre.com/items/$ITEM_ID/sale_price?context=channel_marketplace \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

without applied promotion

{
  "price_id": "13",
  "amount": 114,
  "regular_amount": 250,
  "currency_id": "BRL",
  "reference_date": "2025-09-17T14:44:19Z",
  "metadata": {},
  "bundle": {
    "components": [
      {
        "user_product_id": "MLBU3397414253",
        "item_id": "MLB4189262175",
        "component_price": 100,
        "quantity": 1,
        "unit_amount": 45.60,
        "total_amount": 45.60
      },
      {
        "user_product_id": "MLBU3438878324",
        "item_id": "MLB4189327103",
        "component_price": 50,
        "quantity": 3,
        "unit_amount": 22.80,
        "total_amount": 68.40
      }
    ],
    "total_components_amount": 250
  }
}

with applied promotion


{
    "price_id": "16",
    "amount": 108.3,
    "regular_amount": 250,
    "currency_id": "BRL",
    "reference_date": "2025-09-17T14:48:44Z",
    "metadata": {
        "campaign_id": "C-MLB2306095",
        "promotion_id": "OFFER-MLB5663868532-11961753068",
        "promotion_type": "custom"
    },
    "bundle": {
        "components": [
            {
                "user_product_id": "MLBU3397414253",
                "item_id": "MLB4189262175",
                "component_price": 100,
                "quantity": 1,
                "unit_amount": 43.32,
                "total_amount": 43.32
            },
            {
                "user_product_id": "MLBU3403878324",
                "item_id": "MLB4189327103",
                "component_price": 50,
                "quantity": 3,
                "unit_amount": 21.66,
                "total_amount": 64.98
            }
        ],
        "total_components_amount": 250
    }
}

If the kit is in a promotional campaign, the amount field will reflect the discounted price, and the response’s metadata will include promotion details (campaign_id, promotion_id, promotion_type).

Response fields

  • amount: Final kit price paid by the buyer. It may include promotional discounts.
  • regular_amount: Original kit price without discounts (strikethrough price). It corresponds to the sum of the components’ individual prices.
  • bundle.components: List detailing the price distribution for each kit product.
  • component_price: Individual selling price of the component, as if sold separately (includes the item’s own promotions).
  • unit_amount: Proportional value assigned to one unit of this component within the kit’s final price. Calculated as a percentage of amount.
  • total_amount: Total value assigned to all units of this component in the kit (unit_amount × quantity).
  • total_components_amount: Sum of the individual selling prices of all components (component_price × quantity). It may differ from amount if the seller set a manual kit price.

Modify a Kit item’s automatic price

To modify a kit’s price automation, use the bundle/prices_configuration endpoint.

Call:

curl -L -X PUT https://api.mercadolibre.com/items/$ITEM_ID/bundle/prices_configuration \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{}'

Sample body:

{
  "bundle": {
    "components": [
      {
        "type": "user_product",
        "user_product_id": "MLAU654321",
        "automatic_price": {
          "discount": 0.30
        }
      },
      {
        "type": "user_product",
        "user_product_id": "MLAU654321",
        "automatic_price": {
          "discount": 0.30
        }
      }
    ]
  }
}

Response:

{
    "id": "MLA12345",
    "prices": [
        {
            "id": "1",
            "type": "standard",
            "amount": 50000,
            "regular_amount": null,
            "currency_id": "ARS",
            "last_updated": "2025-02-17T20:12:11Z",
            "conditions": {
                "context_restrictions": [],
                "start_time": null,
                "end_time": null,
                "eligible": true
            },
            "exchange_rate_context": "DEFAULT",
            "metadata": {}
        }
    ],
    "presentation": {
        "display_currency": "ARS"
    },
    "payment_method_prices": [],
    "reference_prices": [],
    "purchase_discounts": [],
    "last_price_id": 1,
    "version": 4,
    "bundle": {
        "components": [
            {
                "type": "user_product",
                "user_product_id": "MLAU654321",
                "quantity": 1,
                "automatic_price": {
                    "discount": 0.30
                }
            },
            {
                "type": "user_product",
                "user_product_id": "MLAU654321",
                "quantity": 2,
                "automatic_price": {
                    "discount": 0.30
                }
            }
        ],
        "total_components_amount": null
    }
}

Get a Kit item’s price configuration

To query a kit item’s price configuration, you can use the following resource.

Call:

curl -L -X GET https://api.mercadolibre.com/items/$ITEM_ID/bundle/prices_configuration \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
"bundle": {
"components": [
                {
       		"type": "user_product", 
       		"user_product_id": "MLAU654321", 
                "quantity": 1
                },
                {
       		"type": "user_product",
       		"user_product_id": "MLAU654321", 
 	        "quantity": 2
               }
        	     ] // this item does not have automatic pricing
      }
}

For cases like this, where the item does not have automatic pricing, the automatic_price field will not be returned.



Get sales detail

When you sell a kit, the system does not generate a single sales order. Instead, it creates an individual order for each component product that is part of the kit. All these orders are linked to each other, allowing you to have detailed control over inventory and revenue for each product. Kit sales will be reflected in one order per component of the kit.

Call:

curl -L -X GET https://api.mercadolibre.com/orders/$ORDER_ID \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
    "order_items":
    [
        {
            "item": {
                "id": "MLA333", //component item id 
		   "user_product_id": "MLA1245", //component user_product_id
                "title": "Coca",
                "category_id": "MLA111",
                "seller_custom_field": null,
                "warranty": "Sin garantía",
                "condition": "new",
                "seller_sku": null,
                "net_weight": null
            },
            "quantity": 6,
           "unit_price": 100,//component item price
            "full_unit_price": 100,
            "currency_id": "ARS",
            "sale_fee": 35,
            "bundle": {	
                "parent_item": {
                    "id": "MLA666667", //kit item_id
		       "user_product_id": "MLA8907" //kit user_product_id
                },
                "components": null
            },
           ...
        }
           "listing_type_id": "gold_special", //kit item listing_type_id
          "element_id": 1,    ],
          "tags":
                 [
                  "pack_order",
                  "delivered",
                  "paid",
                  "bundle_component"
               ]
}

Retrieve related orders from one order

If you already have the order_id of one of the component items that make up a kit, you can use the /bundle resource to obtain all related orders, i.e., those corresponding to the other components that are part of the same kit sale.

Call:

curl -L -X GET https://api.mercadolibre.com/orders/$ORDER_ID/bundle \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

    "bundles": [
        {
            "pack_id": 2000009088803387,
            "shipment_id": 45452435654,
            "main_orders": [],
            "addons_orders": [],
            "kit_orders": [
                {
                    "order_id": 2000012907378394,
                    "item_id": "MLB4189327103",
                    "variation_id": null,
                    "pack_id": 2000009088803387,
                    "shipment_id": 45452435654,
                    "parent_item_id": "MLB5663868532"
                },
                {
                    "order_id": 2000012907380228,
                    "item_id": "MLB4189262175",
                    "variation_id": null,
                    "pack_id": 2000009088803387,
                    "shipment_id": 45452435654,
                    "parent_item_id": "MLB5663868532"
                }
            ]
        }
    ]
}

Get calculated Kit stock

One of the biggest advantages of kits is that you don’t need to manage their stock manually. The system calculates and synchronizes it automatically, ensuring you never sell a kit if you don’t have enough components to assemble it.

The available stock of your kit is always based on the stock of the products that compose it and the quantity needed of each one. This means that the component with the lowest relative availability will limit how many kits you can sell.

Examples:

The following case represents a kit made up of 1 Fernet and 2 Cokes, used to analyze how the components and their logistic locations are combined when calculating availability.


Fernet Coca Kit
selling_address meli_facility
"network_node_id": "A"		 seller_warehouse
"network_node_id": "X"		 selling_address meli_facility
"network_node_id": "B"		 seller_warehouse
"network_node_id": "Y"		 selling_address meli_facility
"network_node_id": null		 seller_warehouse
"network_node_id": null
4 4 (does not exist) 4 4 (does not exist) 2 2 (does not exist)
2 0 (does not exist) 2 4 (does not exist) 1 0 (does not exist)
3 (does not exist) (does not exist) 6 (does not exist) (does not exist) 3 (we don't create it) (does not exist)
2 (does not exist) (does not exist) 4 2 (does not exist) 2 (we don't create it) 0
(does not exist) (does not exist) 2 (does not exist) (does not exist) 2 (we don't create it) (we don't create it) 1
(does not exist) 4 5 (does not exist) 8 6 (we don't create it) 4 3
(does not exist) 4 5 (does not exist) (does not exist) 4 (we don't create it) 0 2
Note:
This stock represents the total number of kits that can be assembled based on the quantity of their components, without considering their locations. If this stock becomes 0, the kit item is paused.

Call:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

Example: product in Full + seller's warehouse

{
    "locations":
    [
 {
            "type": "meli_facility", // fulfillment
            "quantity": 2
        },
        {
            "type": "selling_address", // flex or base logistics
            "quantity": 2
        }
    ],
    "user_id": 655555555,
    "id": "MLBU3333333333"
}

If the kit item's stock becomes 0, the kit item is paused. In these cases you'll see a sub_status = "out_of_stock". There is nothing special for kits here: it is the normal behavior when an item runs out of stock.



For stock of component UPs we recommend reviewing the stock management documentation.