Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 16/08/2024

Compatibility between items and vehicle accessories

Important:
This resource is available only in Argentina, México, Brazil, Uruguay, Chile and Colommbia.

The compatibilities allow you to add the items published with the compatible products on the marketplace. For example, if you have a published “Corven Plus Shock Absorber”, you can define attributes such as Brand, Model, Year and Engine for which this spare part is compatible. In this way, you improve the quality of the listings and reduce the number of publications per item.
For this, you must access the dump and verify that the domain of the items and the domain of the products are compatible. Then, you can add the compatibilities in 3 (three) different ways and finally, list them.
If the compatibility is not correct, you will be able to eliminate those defined by the users (sellers).


Check cross domain compatibility

Note:
- As of February 5 it will be mandatory for MLM, MLA, MLB and MLU sites to report compatibilities in all publications, and from March 25 it will be mandatory for MLC and MCO. So before publishing, we recommend you to validate if the category of the item contains the attribute categories.required = true .

- Once the publication is created, you will be able to identify the items where it is mandatory to report compatibilities with the tag incomplete_compatibilities. You can see more details in identify items that require compatibilities.

Before creating compatibility between items and products, you should check that the category item and product domains are compatible.

By consulting the next dump, you get the list of domains and categories in which you can or need to report compatibility by site..

Request:

curl -X GET http://api.mercadolibre.com/catalog/dumps/domains/$SITE_ID/compatibilities

Request example:

curl -X GET https://api.mercadolibre.com/catalog/dumps/domains/MLM/compatibilities

Response example:

[
    {
        "domain_id": "MLM-AUTOMOTIVE_SHOCK_ABSORBERS",
        "main": false,
        "compatibilities": [
            {
                "compatible_domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
                "type": "EXTENSION",
                "required": false,
                "restrictions": [],
                "categories": [
                    {
                        "id": "MLM45878",
                        "required": true,
                        "note_status": "ENABLED",
                        "restrictions_status": "DISABLED",
                        "universal_status": "DISABLED"
                    }
                ]
            }
        ]
    },
    …
}]

The new fields indicate:

  • categories: categories that support loading compatibilities..
  • required: categories in which it is mandatory to load compatibilities.
  • type: type of compatibility. Only the EXTENSION type supports loading compatibilities.
  • note_status and restrictions_status: indicate if the category allows reporting notes and positions.
  • universal_status: indicates if the category allows the communication of universal compatibilities. ENABLED: allows the communication of universal compatibilities or DISABLED : does not allow the communication of universal compatibilities.

Get more information about Domains, products and attributes vehicle accessories references.


Count products from a domain

To check the number of existing products per domain (product family) that meet certain attributes and values, you can perform the following POST. This will allow you to validate, prior to associating the compatibilities, the number of products and avoid errors in the assignment of compatibilities.
This is important as only a maximum of 200 products can be assigned per request.

Note:
The traffic limit per APP_ID is 100 rpm.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
  "domain_id": "$domainId",
  "attributes": [{
    "id": "$attributeId1",
    "value_id": "$valueId1"
  }, {
    "id": "$attributeId2",
    "value_name": "$valueName2"
  }]
}

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
  "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
  "attributes": [{
      "id": "BRAND",
      "value_name": "Volkswagen"
    },
    {
      "id": "CAR_AND_VAN_MODEL",
      "value_name": "VENTO"
    }
  ]
}

Response:

{
   "count":141
}

Identify items requiring compatibilities

With the following resource through the incomplete_compatibilities tag you can identify items that require mandatory compatibilities reporting to avoid moderations.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910

Response:

{
  "id": "MLA743626587",
  "site_id": "MLA",
  "title": "Paragolpe Trasero Peugeot 307 Linea Nueva 5 Puertas",
  "seller_id": 65711207,
  "category_id": "MLA60954",
  "official_store_id": null,
.
.
.
.

  "tags": [
    "good_quality_picture",
    "brand_verified",
    "loyalty_discount_eligible",
    "good_quality_thumbnail",
    "ahora-paid-by-buyer",
    "incomplete_compatibilities",
    "immediate_payment"
  ],
  "warranty": "CON GARANTIA DEL FABRICANTE",
  "catalog_product_id": null,
  "domain_id": "MLA-VEHICLE_REAR_BUMPERS",
  "parent_item_id": null,
  "deal_ids": [
  ],
  "automatic_relist": false,
  "date_created": "2018-08-17T20:36:54.000Z",
  "last_updated": "2023-12-15T17:18:35.000Z",
  "health": 0.83,
  "catalog_listing": false
}

Filter items that require matching

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilities

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilities

Response:

{
   "seller_id": "1373279576",
   "results": [
       "MLA1417560910",
       "MLA1373565211",
       "MLA1371734513",
       "MLA1396609243"
   ],
   "paging": {
       "limit": 50,
       "offset": 0,
       "total": 4
   },
   "query": null,
.
.
.
.
}

Identifique itens com sugestões de compatibilidade

With the following resource you will be able to know the list of all the items of the seller that have compatibilities suggestions, that is to say that they have the tag "pending_compatibilities".

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=pending_compatibilities

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1695976736/items/search?tags=pending_compatibilities

Request:

{
   "seller_id": "1373279576",
   "results": [
      "MLB4462690924"
   ],
   "paging": {
       "limit": 50,
       "offset": 0,
       "total": 4
   },
   "query": null,
.
.
.
.
}

With the following call and through the pending_compatibilities tag found in the response, you can identify for a specific item if it has compatibilities suggestions.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB4462690924

Response:

{
  "id": "MLB4462690924",
  "site_id": "MLB",
  "title": "Pastilha Freio Dianteira Gm Blazer 4.3 V6 Mpfi 1996 À 2003 ",
  "seller_id": 1695976736,
  "category_id": "MLB439261",
  "official_store_id": null,

.
.
.
.
.
  "tags": [
    "pending_compatibilities"
  ],
 "catalog_product_id": "MLB31779615",
  "domain_id": "MLB-VEHICLE_BRAKE_PADS",
  "parent_item_id": null,
  "deal_ids": [
  ],
  "automatic_relist": false,
  "date_created": "2024-02-22T16:51:37.577Z",
  "last_updated": "2024-03-22T20:49:39.772Z",
  "health": 0.75,
  "catalog_listing": false
}

Filter items that have suggested compatibilities.


Get the number of suggestions and complaints

With the following resource you will be able to know the number of compatibility suggestions and complaints that a specific publication has..

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_domains/$DOMAIN_ID/compatibilities/cards

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d 
{
"item_id": "MLB4462690924",
"product_id": "MLB31779615",
"filters":   ["REPUTATION",   "SUGGESTED"]
}
https://api.mercadolibre.com/catalog_domains/MLB-CARS_AND_VANS/compatibilities/cards

Attributes request

  • item_id: mandatory attribute corresponding to the item identifier.
  • product_id: attribute corresponding to the product that is associated to the item, it is optional, however performance and response times are improved when this attribute is informed.
  • filters: mandatory attribute to indicate whether you want to obtain the number of complaints ["REPUTATION"], the number of compatibility suggestions ["SUGGESTED"] that the item has; or both ["REPUTATION", "SUGGESTED"].

Response:

[
   {
       "title": "Tienes 293 vehículos sugeridos pendientes por agregar",
       "subtitle": "Identificamos vehículos compatibles con tu producto que te ayudarán a vender más",
       "filter": "SUGGESTED",
       "quantity": 293
   },
   {
       "title": "Vehículos con reclamos por incompatibilidad",
       "subtitle": "Revisalos y eliminalos para evitar nuevos reclamos.",
       "filter": "REPUTATION",
       "quantity": 1
   }
]

Reputation: all the compatibilities that are generating complaints.

Suggested: all new compatibility cases suggested to your publications.


If you want to know how to obtain the suggested compatibilities for each item you can see more details in identifying suggested compatibilities.

SIf you want to know which are the problematic compatibilities that are generating complaints and affecting the seller's reputation you can see more details in know compatibilities that generate complaints.


Add compatibilities

Nota:
- We provide all compatibility functionalities in the auto parts publications of categories MLA1747, MLM1748, MLB22693, MLU1748 , MLC1748 and MCO87919.

- On the MLA, MLM, MLB, MLU, MLC and MCO sites, compatibilities must be reported on a mandatory basis on items marked with the incomplete_compabilities tag to prevent auto part publications from being paused.

To add compatibility of an item with a product and / or domain, you can check up to a maximum of 200 products per request (including those defined in the domains) and do it in 3 different ways:

  • By product: To add new compatibility to an item, you must send the compatibility you want to add. It is not necessary to send existing ones to keep current ones.
  • By product domain: you can specify a set of attributes that define the product domain. For each domain, you must specify its domain and for each attribute, a value made up of id and / or name.
  • By product and domain: You can add compatibility with a published item of another product and a product domain, that is, it allows you to add the first 2 together.
Note:
The traffic limit per APP_ID is 100 RPM (request per minute).

Get the possible values for a restriction

When associating a compatibility you can also indicate the position restriction of the same, with the following request you will be able to know the possible values to inform it.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/restrictions/values?main_domain_id=MLA-CARS_AND_VANS&secondary_domain_id=MLA-VEHICLE_SHOCK_ABSORBERS

Response:

{
      "attributes_values": [   
          {
               "attribute_id": "POSITION",
               "values":
                [
                    {
                        "value_id": "23536",
                        "value_name": "Superior",
                    },
                    {
                        "value_id": "23537",
                        "value_name": "Inferior"
                    }
               ]
         }
    ]
}

Add by product

To add a compatibility to one or more individual products, you can use the product search.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products": [{
       "id": "$PRODUCT_ID",
       "note": "texto",
       "restrictions": [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]
                }]
   }]
}'

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products": [{
       "id": "MLB155254",
       "note": "Modelos posteriores a Mayo de 2018",
       "restrictions": [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "12456","value_name": "Delantero"}]
                      },
                      {
                        "values":[{"value_id": "65432","value_name": "Trasero"}, 
                                  {"value_id": "87675","value_name": "Inferior"}]
                      }
                    ]
                }]
   }]
}

Response:

{
 "created_compatibilities_count": 72
}

It is also possible to add a note and position to more than one compatibility, for this it is necessary to replace the products node by products_group, example:

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products_group": [{
       "ids": ["MLB155254", "MLB155255"],
       "note": "texto",
       "restrictions": [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]
                }]
   }]
}

Add by product domain

To add compatibilities defined by a group of attributes that determine a domain, learn more about vehicle accessories domains and attributes.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products_families": [{
       "domain_id": "$DOMAIN_ID",
       "attributes": [{
               "id": "$ATTRIBUTE_ID",
               "value_id": "$VALUE_ID"
           },
           {
               "id": "$ATTRIBUTE_ID",
               "value_id": "$VALUE_ID"
           },
       ],
     "note": "Texto",
     "restrictions":
                [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]
                }]
}

Example (except MLM):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA794706391/compatibilities
{
   "products_families": [{
       "domain_id": "MLA-CARS_AND_VANS",
       "attributes": [{
               "id": "BRAND",
               "value_id": "60249"
           },
           {
               "id": "YEAR",
               "value_name": "2010"
           },
       ],
     "note": "Solamente para vehículos de fabricación Europea",
     "restrictions":
                [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]

                }]
}

Response:

{
 "created_compatibilities_count": 23
}

Ejemplo MLM:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
   "products_families": [{
           "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
           "attributes": [{
                   "id": "DRIVE_TYPE",
                   "value_id": "8182649"
                  
               },
               {
                   "id": "CAR_AND_VAN_BODY_TYPE",
                   "value_id": "8183109"
                  
               },
               {
                   "id": "YEAR",
                   "value_name": "2010"
                  
               }
           ],
     "note": "Solamente para vehículos de fabricación Europea",
     "restrictions":
                [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "12456","value_name": "Delantero"}]
                      },
                      {
                        "values":[{"value_id": "65432","value_name": "Trasero"}, 
                                  {"value_id": "87675","value_name": "Inferior"}]
                      }
                    ]
       }
   ]
}

Response:

{
 "created_compatibilities_count": 23
}

Add by product and domain product

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products": [{
       id": "$PRODUCTIID",
       "note": "texto",
       "restrictions": [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]
   }],
   "products_families": [{
       "domain_id": "$DOMAIN_ID",
       "attributes": [{
               "id": "ATTRIBUTE_ID",
               "value_id": "$VALUE_ID"
           },
           {
               "id": "ATTRIBUTE_ID",
               "value_id": "$VALUE_ID"
           },
       ],
     "note": "Texto",
     "restrictions":
                [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      },
                      {
                        "values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}, 
                                  {"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
                      }
                    ]
                }]
}

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
   "products": [{
       "id": "MLB155254",
       "note": "Modelos posteriores a Mayo de 2018",
       "restrictions": []
   }],
   "products_families": [{
       "domain_id": "MLB-CARS_AND_VANS",
       "attributes": [{
               "id": "BRAND",
               "value_id": "60249"
           },
           {
               "id": "YEAR",
               "value_name": "2010"
           },
       ],
     "note": "Solamente para vehículos de fabricación Europea",
     "restrictions":
                [{
                    "attribute_id": "POSITION",
                    "attribute_values":
                    [{
                        "values":[{"value_id": "12456","value_name": "Delantero"}]
                      },
                      {
                        "values":[{"value_id": "65432","value_name": "Trasero"}, 
                                  {"value_id": "87675","value_name": "Inferior"}]
                      }
                    ]
                }]
}

In the note

Response:

{
 "created_compatibilities_count": 23
}

Possible errors

400: consistency validations:

  • Required fields are incomplete.
  • The format of the ids is wrong.
  • More than 200 products were found and / or specified for the product domains.
  • More than 10 product domains were specified.
  • The products and / or domains do not belong to the same site as the item.
  • The products must all be children.
  • The item's domain is compatible with the specified product domains and / or with the specified domains in the specified product domains.

403: Invalid token or lack of permissions on the item.
404: the specified item, products or domains do not exist.


To add a universal compatibility

In order to improve the quality of auto parts publications for car and truck accessories categories ( MLA6520, MLM5320, MLU1747, MLB1747), compatibilidades universales can be reported to indicate that an item is compatible with any product.

To indicate that an item is compatible with any product, in the request, the universal field is available, which shall be informed in true. This indicates that this item is universal (none of the compatibilities should be add to it since it is compatible with all products from the same domain).


When indicating a universal compatibility, it is not possible to specify products or families. If both fields are sent, an error will be returned.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
   "products": [],
   "products_families": [],
   "products_group": [],
   "universal": true
}

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities
{
   "products": [],
   "products_families": [],
   "products_group": [],
   "universal": true,
}

Response:

{
 "created_compatibilities_count": 1
}

Possible errors when assigning universal compatibilities

400: consistency validations:

  • In case products and families are shipped at the same time a universal compatibility is reported, it will be obtained:
      • Message: "Invalid arguments for specific request. Please check details to satisfy validations".
      • Details: "at least one of products, products_groups, products_families or universal must be specified, if universal no products can be specified".
  • In case you have any compatibility in the previously registered item and you try to make it universal, you will get it:
    • Message: Item has compatibilities and these must be removed before setting it as universal.
  • When you try to generate a universal item but the category is not enabled for this experience, you will get:
    • Message: There is no configured compatibility for the category $CATEGORY_ID
  • If the item above is universal and you try to load some compatibility, you will get it:
    • Message: Item has universal setting and must be removed before creating compatibilities.

    403: invalid token or lack of permissions on the item.

    404: the item does not exist.

    Update Compatibilities

    With this method, it is possible to create, update, and delete compatibilities, notes, and restrictions for an item using the same data structure as for creating compatibilities. This action can be performed for one or multiple compatibilities.

    Important:
    - This PUT is different from the other ones used for items; in this case, the information is not overwritten. It is necessary to clearly specify the desired action: create, update, or delete.
    - The examples below include "create," "update," and "delete." It is not necessary to specify all actions together; they can also be indicated separately.
    - For this method, only 200 products can be specified per request.

    Request:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
    https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?/code>

    Example for Creating and Deleting Compatibilities:

    Note:
    When deleting compatibilities, you can choose to do so through a product list (products) or by product families (products_families). Both options are available in the example below so you can select the one that best fits your needs and see how to send the data correctly.
    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d 
    '{
       "create": {
           "products": [
               {
                   "id": "MLB22015088"
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60249"
                       },
                       {
                           "id": "MODEL",
                           "value_name": "Gol"
                       },
                       {
                           "id": "YEAR",
                           "value_name": "2023"
                       }
                   ]
               }
           ]
       },
       "delete": {
           "products": [
               {
                   "id": "MLB22015074"
               },
               {
                   "id": "MLB7427549"
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60249"
                       },
                       {
                           "id": "MODEL",
                           "value_id": "62109"
                       },
                       {
                           "id": "YEAR",
                           "value_name": "2023"
                       }
                   ]
               }
           ]
       }
    }
    

    Response:

    {
       "create": {
           "products": [
               {
                   "id": "MLB22015088"
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60249"
                       },
                       {
                           "id": "MODEL",
                           "value_name": "Gol"
                       },
                       {
                           "id": "YEAR",
                           "value_name": "2023"
                       }
                   ]
               }
           ],
           "universal": false
       },
       "delete": {
           "products": [
               {
                   "id": "MLB22015074"
               },
               {
                   "id": "MLB7427549"
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60249"
                       },
                       {
                           "id": "MODEL",
                           "value_id": "62109"
                       },
                       {
                           "id": "YEAR",
                           "value_name": "2023"
                       }
                   ]
               }
           ],
           "universal": false
       }
    }
    
    

    Example for Creating and Updating Compatibilities with Notes and/or Restrictions:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d 
    '{
       "create": {
           "products": [
               {
                   "id": "MLB28049481",
                   "note": "nota para teste",
                   "restrictions": []
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60395"
                       },
                       {
                           "id": "MODEL",
                           "value_ids": [
                               "389577",
                               "16696"
                           ]
                       }
                   ]
               }
           ]
       },
       "update": {
           "products": [
               {
                   "id": "MLB22567898",
                   "note": "nota para teste 10",
                   "restrictions": [
                       {
                           "attribute_id": "POSITION",
                           "attribute_values": [
                               {
                                   "values": [
                                       {
                                           "value_id": "13701104",
                                           "value_name": "Dianteira"
                                       }
                                   ]
                               }
                           ]
                       }
                   ]
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "67781"
                       },
                       {
                           "id": "MODEL",
                           "value_name": "ARGO"
                       }
                   ],
                   "note": "somente as versões de freios traseiros",
                   "restrictions": [
                       {
                           "attribute_id": "POSITION",
                           "attribute_values": [
                               {
                                   "values": [
                                       {
                                           "value_id": "13701104",
                                           "value_name": "Dianteira"
                                       }
                                   ]
                               }
                           ]
                       }
                   ]
               }
           ]
       }
    }
    

    Response:

    {
       "create": {
           "products": [
               {
                   "id": "MLB28049481",
                   "note": "nota para teste",
                   "restrictions": []
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "60395"
                       },
                       {
                           "id": "MODEL",
                           "value_ids": [
                               "389577",
                               "16696"
                           ]
                       }
                   ]
               }
           ],
           "universal": false
       },
       "update": {
           "products": [
               {
                   "id": "MLB22567898",
                   "note": "nota para teste 10",
                   "restrictions": [
                       {
                           "attribute_id": "POSITION",
                           "attribute_code": 1,
                           "attribute_values": [
                               {
                                   "values": [
                                       {
                                           "value_id": "13701104",
                                           "value_name": "Dianteira",
                                           "value_code": 5
                                       }
                                   ]
                               }
                           ]
                       }
                   ]
               }
           ],
           "products_families": [
               {
                   "domain_id": "MLB-CARS_AND_VANS",
                   "attributes": [
                       {
                           "id": "BRAND",
                           "value_id": "67781"
                       },
                       {
                           "id": "MODEL",
                           "value_name": "ARGO"
                       }
                   ],
                   "note": "somente as versões de freios traseiros",
                   "restrictions": [
                       {
                           "attribute_id": "POSITION",
                           "attribute_code": 1,
                           "attribute_values": [
                               {
                                   "values": [
                                       {
                                           "value_id": "13701104",
                                           "value_name": "Dianteira",
                                           "value_code": 5
                                       }
                                   ]
                               }
                           ]
                       }
                   ]
               }
           ],
           "universal": false
       }
    }
    
    
    Note:
    If you want to delete notes and/or restrictions, you should send them in the 'update' section with note: "" or restrictions: [].

    Possible Errors:

    400 - Consistency Validations:

    • Completeness of required fields.
    • Correctness of ID formats.
    • Products and/or domains belong to the same site as the item.
    • The item's domain is compatible with the domains of the specified products.
    • The maximum of 200 products for a single request has been exceeded.
    • 403: Caller ID does not have permissions for the item.

      404: Item or one of the products does not exist.


      Modify or delete notes and position restrictions

      To modify or delete a note and position constraint, execute a PUT on the compatibility reporting resource changing the information you need in the update field. To delete one or both of them, just send the note field and/or the empty restrictions array, as in the example below, where both fields are deleted.


      Example:

      curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
      {
        "update": {
          "products": [{
                  "id": "MLB155254",
                  "note": "",
                  "restrictions":[]
                  }
              ]
          }
      }
      

      Identify compatible items

      With the following resource you can identify that an item is already compatibilized through the attribute id = “HAS_COMPATIBILITIES”. If this attribute is not observed in the output of the call, it means that the item does not have compatibilities reported.

      Request:

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

      Example:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910

      Response:

      {
        "id": "MLA1417560910",
        "site_id": "MLA",
        "title": "Interruptor Columna (palanca) Tamatel 15104 - No Ofertar",
        "seller_id": 1373279576,
        "category_id": "MLA435058",
      .
      .
      .
      .
       "attributes": [
          {
            "id": "HAS_COMPATIBILITIES",
            "name": "Tiene compatibilidades",
            "value_id": "242085",
            "value_name": "Sí",
            "values": [],
            "value_type": "boolean"
          },
          {},
          {}
        ],
      .
      .
      .
      }
      

      List compatibilities

      With this resource, you can list all the compatibilities for a particular item.

      Nota:
      The “reputation” object with the attributes “level” and “total_claims” (color and total number of vehicles that generated claims) were added to the resource response, which will help identify the vehicles that are causing incompatibility claims.

      Get all compatibilities for an item

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?extended=true

      Request example:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities?extended=true

      Response example:

      {
         "products": [
              {
                  "id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
                  "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
                  "catalog_product_id": "MLM15847548",
                  "catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
                  "source": "SELLER",
                  "note": "Solo modelos de caja automática"
              },
              {
                  "id": "58bd413f-cd65-a719-9570-2ca8f2b528af",
                  "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
                  "catalog_product_id": "MLM15847546",
                  "catalog_product_name": "Volkswagen Jetta 2010 GLI Automática 6",
                  "source": "SELLER",
                  "note": "Modelos posteriores a Junio 2010",
                  "restrictions":
                      [{
                          "attribute_id": "POSITION",
                          "attribute_values":
                          [{
                              "values":[{"value_id": "12456","value_name": "Delantero"}]
                            },
                            {
                              "values":[{"value_id": "65432","value_name": "Trasero"}, 
                                        {"value_id": "87675","value_name": "Inferior"}]
                          }]
                   }],
                  "reputation:" {
                  "level": "RED",
                  "total_claims": 2
                  }
      
              }
      
         ],
          "catalog_compatibilities_count": 15
      }
      
      Note:
      - In case the compatibility has no incompatibility claims, the reputation object will not be returned in the response.
      - Only claims with a reason_id of PDD9575 or PDD9967 are calculated.

      Response fields

      • products: array arreglo con todos los vehículos (compatibilidades) informadas por el vendedor.
        • ID: compatibility ID.
        • domain_id: main product domain.
        • catalog_product_id: product ID of the primary domain.
        • catalog_product_name: product name of the primary domain.
        • source: source flow of compatibility.
        • note: specification of compatibility conditions between the item and the main product.
        • restrictions: compatibility restrictions between item and main product (ex. installation position of the part).
        • reputation: color and total number of vehicles that generated complaints.
        • level: will take the RED value for compatibilities with a high number of incompatibility complaints.
        • total claims: number of incompatibility complaints related to compatibility.
    • catalog_compatibilities_count: attribute has the number of compatibilities from the Mercado Libre catalog, that is, the latter compatibility will not be listed due to limitations in intellectual property licenses.
    • Note:
      If a compatibility uploaded by the seller is already available in the Mercado Libre catalog, it will not be shown in the product's field of the response.

      Obtain compatibilities of a universal item

      In case the item is configured as universal, an additional field called universal is added in the response, containing a list of top domains with which the item is compatible..

      Ejemplo respuesta:

      {
                "universal": {
                    “domain_ids”:  [“MLM_CARS_AND_VANS_FOR_COMPATIBILITIES”]
                  }
      }
      

      Get a specific compatibility of an item by its id

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$compatibility_id

      Example:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/$compatibility_id

      Response:

      {
        "id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
        "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
        "catalog_product_id": "MLM15847548",
        "catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
        "note": "Solo para versiones con frenos a disco en las ruedas traseras",
        "note_status": "PENDING",
        "restrictions": [{
                          "attribute_id": "POSITION",
                          "attribute_values":
                          [{
                              "values":[{"value_id": "12456","value_name": "Delantero"}]
                            }]
                     }] ,
                  "reputation:" {
                  "level": "RED",
                  "total_claims": 2
                  }
      
              }
      

      The notes only appear on the front of the item in the APPROVED or CHECKED status.

      A 404 error means that the item does not exist.


      Identifying if an item has notes or restrictions position

      The endpoint allows to identifying if the item has notes or restrictions:

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/extended/check

      Example:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities/extended/check

      Resonse:

      {
          "note": "true",
          "restrictions": "false"
      }
      

      Obtain a compatibility note

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_ID/note
      

      Example:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities/bcbd413f-cd65-0e0f-88c9-5eb4aebb5372/note

      Response:

      {
          "note": "Solo para versiones con frenos a disco en las ruedas traseras"
      }
      

      Delete compatibilities

      In case of having add an incorrect compatibility with the item, you can eliminate it as long as it has been made by the seller.

      Delete a specific compatibility for the indicated item

      Request:

      curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_ID

      Example:

      curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/4cb9af35-8e9b-ebfd-9e7f-2245ac363d10

      The response will be http 200.


      Delete compatibilities for an item

      Request:

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

      Example:

      curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities

      Response:

      {
        "deleted_compatibilities": [
          "d0ba2aeb-7409-0037-7b23-0b91266fd00e",
          "72ba233d-16d8-218b-4062-7a97dab166c8"
        ]
      }

      Delete compatibilities by product domain for an item

      Request:

      curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
      {
      "products_families": [{
        "domain_id": "$domain_id",
        "attributes": [{
          "id": "$attribute_id1",
          "values":[{
            "id": "$value_id1",
            "name": "$value_name1"
          }]
        },{
          "id": "$attribute_id2",
          "values":[{
            "id": "$value_id1",
            "name": "$value_name1"
          }]
        }]
      }]
      }
      

      Example:

      curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
        {
        "products_families": [{
                "domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
                "attributes": [{
                        "id": "DRIVE_TYPE",
                        "value_id": "8182649"
                    },
                    {
                        "id": "CAR_AND_VAN_BODY_TYPE",
                        "value_id": "8183109"
                    },
                    {
                        "id": "YEAR",
                        "value_name": "2010"
                    }]
            }]
      }
      

      Response:

      {
         "deleted_compatibilities": [
             "d0ba2aeb-7409-0037-7b23-0b91266fd00e",
             "72ba233d-16d8-218b-4062-7a97dab166c8"
         ]
      }

      Possible errors

      400: incorrect format / more than 200 products for the domain / more than 10 domains specified.
      403: inválid token or lack of permits on the ítem.
      404: the ítem or the compatibility not exist.


      How to report exceptions

      In cases of car and truck parts, in which the category requires compatibility information,but cannot find any available vehicle, model or version in the catalog. These items are part of the exceptions flow and to inform them, we provide the following resource:


      Request:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exception
      {
        "comment": “free text with a maximum of 255 characters” 
      }
      

      Example:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
      {
        "comment": “free text with a maximum of 255 characters” [Required]
      }
      

      Response:

      200 OK

      Possible errors

      400: item is closed or inactive.
      400: item has existing compatibilities.
      400: item category has no compatibilities.
      400: item has existing compatibilities exception.
      400: comment is required.


      Check if an item has an exception

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exception

      Example

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
      

      Response

      {
         "has_exception": true/false
      }
      

      - Returns true only when the item has no compatibility loaded and an exception has been reported.
      - Returns false whenever an item has at least one vehicle reported as compatible (regardless of whether an exception was reported or not).


      Identify compatibilities that generate complaints

      In order for you to correct incorrectly indicated compatibilities, with the following endpoint you can identify the car that the buyer chose from the moment a claim for incompatibility was generated.

      Request:

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

      Example:

      Order with claim where the buyer selected different filters during the purchase of the product and it was confirmed that the selected product “Yes was indeed compatible” with the item (compatibility_status.compatibility = CONFIRMED).

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967416

      Response:

      {
          "item_id": "MLM2187940074",
          "product_id": "MLM15879678",
          "seller_id": "61597650",
          "user_selection": {
              "label_values": [
                  {
                      "label": "Marca",
                      "value_name": "Jeep",
                      "values": [
                          {
                              "attribute_id": "BRAND",
                              "value_id": "60395"
                          }
                      ]
                  },
                  {
                      "label": "Modelo",
                      "value_name": "Grand Cherokee",
                      "values": [
                          {
                              "attribute_id": "CAR_AND_VAN_MODEL",
                              "value_id": "8236932"
                          }
                      ]
                  },
                  {
                      "label": "Año",
                      "value_name": "1998",
                      "values": [
                          {
                              "attribute_id": "YEAR",
                              "value_id": "60500"
                          }
                      ]
                  },
                  {
                      "label": "Versión",
                      "value_name": "Limited - SUV 4 Puertas",
                      "values": [
                          {
                              "attribute_id": "CAR_AND_VAN_SUBMODEL",
                              "value_id": "8238101"
                          },
                          {
                              "attribute_id": "CAR_AND_VAN_BODY_TYPE",
                              "value_id": "8183114"
                          },
                          {
                              "attribute_id": "BODY_DOORS_NUMBER",
                              "value_id": "8239302"
                          }
                      ]
                  },
                  {
                      "label": "Mecánica",
                      "value_name": "5.2L V8 Gasolina Aspirado Caja Automática 4 Marchas - Tracción RWD",
                      "values": [
                          {
                              "attribute_id": "CAR_AND_VAN_ENGINE",
                              "value_id": "8753511"
                          },
                          {
                              "attribute_id": "ASPIRATION",
                              "value_id": "8183201"
                          },
                          {
                              "attribute_id": "TRANSMISSION_CONTROL_TYPE",
                              "value_id": "8183158"
                          },
                          {
                              "attribute_id": "TRANSMISSION_SPEEDS_NUMBER",
                              "value_id": "8239312"
                          },
                          {
                              "attribute_id": "DRIVE_TYPE",
                              "value_id": "8182651"
                          }
                      ]
                  }
              ]
          },
          "compatibility_status": {
              "compatibility": "CONFIRMED", 
          "compatibility_id": "bec40b54-c7de-1ad2-a7e2-00a5e34376a4"
          },
          "compatibility_deleted": true,
          "date_created": "2023-08-31T20:08:41Z",
          "date_updated": "2023-08-31T22:37:39Z"
      }
      

      Order with claim where the buyer did not select a vehicle during the purchase of the product.

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967424

      Response:

      {
          "item_id": "MLM2038068352",
          "seller_id": "186880296",
          "compatibility_status": {
            "compatibility": "NO_USER_SELECTION",
            "note": "We don't have the compatibility information for this order. The user made the order without completing the widget. ",
            "restrictions": []
          },
          "date_created": "2023-08-23T12:30:57Z"
        }
      

      Order with claim where prior to purchase it was confirmed to the buyer that the product selected "was not compatible" with the item (compatibility_status.compatibility = INCOMPATIBLE).

      Request:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967684

      Response:

      {
          "item_id": "MLM693204319",
          "seller_id": "56493851",
          "compatibility_status": {
              "compatibility": "INCOMPATIBLE"
          },
          "compatibility_deleted": true,
          "date_created": "2023-08-25T14:45:48Z"
      }
      

      The fields indicate:

      • compatibility_id: identifier of the compatibility selected during purchase.
      • product_id: ID of the selected vehicle prior to purchase.
      • user_selection: detail of the filters selected by the buyer at the time of purchase.
      • compatibility_status.compatibility:
        • CONFIRMED: indicates that it was confirmed to the buyer that the selected vehicle was compatible with the purchased item.
        • INCOMPATIBLE: indicates that it was confirmed to the buyer that the selected vehicle was not compatible with the purchased item.
        • compatibility_deleted::
          • "true" indicates that the compatibility for the vehicle selected by the buyer has already been deleted by the item at the time of the query.
        • Note:
          As of February 19 to obtain the detail of incompatibility claims, consult the endpoint GET /v1/claims/search?reason_id=$reason_id and identify the attribute "reason_id": "PDD9967" or "reason_id": "PDD9571".

          Possible mistakes:

          Error_code Error message Description
          400 Compatibility snapshot for order with id $ORDER_ID not found. The order is not valid.
          401 Invalid access token. Invalid Access Token.
          403 The compatibility snapshot can only be retrieved for orders with claims. The order has no associated claim.
          403 Caller must be the seller of the item. An attempt is being made to query the order of a seller that does not correspond to the Access Token provided.
          Important:
          To keep the compatibilities updated you can find out which vehicles have been added to the catalog by getting to the resource /catalog_compatibilities/products_search/new?categoryId=$CATEGORY_ID.