Product identifiers

Identifiers are unique codes (PI or product identifier) whose purpose is to locate a publication and define the article that is being sold globally. Manufacturers associate unique identifiers with each article, so identical articles share the same PI. Learn more about how to identify the universal product code.

The most common product IP include, commercial article numbers (GTIN), manufacturer part numbers (MPN), and brand names. Not all articles have product identifiers. However, if the article has one, we recommend uploading it in the publication to improve quality and make it easier to find in the main search.

GTIN types

GTIN (Global Trade Item Number) is the globally recognized code number of a commercial item. Next you will see in detail the different types that can be included in the GTIN attribute:

• UPC (in North America / GTIN-12): 12-digit number (8-digit UPC-E codes must be converted to 12-digit UPC-A codes).
• EAN (in Europe / GTIN-13): 13-digit number.
• JAN (in Japan / GTIN-13): 8 or 13-digit number.
• ISBN (for books): 13-digit number (ISBN-10 values must be converted to ISBN-13).
• ITF-14 (for multiple packages / GTIN-14): 14-digit number.
• Part Number: codes used to locate automotive replacement parts uniquely, defining the compatibility of the replacement, among other details that help us know what type of car the part applies to.

Logic for the use of the GTIN attribute:

When the category has the GTIN attribute:

• If it has the required tag, it will need to be completed at all times.
• If it has the conditional_required tag, you should prioritize the use of the GTIN, but in situations where it is not available, you can choose to add the EMPTY_GTIN_REASON.

In order to use the EMPTY_GTIN_REASON attribute, it is important to follow the rules established for the reasons for not submitting the GTIN.

Listing with identifiers

You can send this information just like you post attributes, regardless of the category. Know more about how to list a product.

Example of a listing without variations and with GTIN:

curl -L -X POST 'https://api.mercadolibre.com/items' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
   "title": "Bicicleta Mtb Totem By Topmega R29 Producto Test",
   "category_id": "MLA6143",
   "price": 99999,
   "currency_id": "ARS",
   "available_quantity": 2,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "6 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía de fábrica"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "condition": "new",
   "pictures": [
       {
           "source": "http://http2.mlstatic.com/D_608172-MLA53351140125_012023-O.jpg"
       },
       {
           "source": "http://http2.mlstatic.com/D_714634-MLA53351124241_012023-O.jpg"
       },
       {
           "source": "http://http2.mlstatic.com/D_878513-MLA53351118304_012023-O.jpg"
       }
   ],
   "attributes": [
       {
           "id": "BICYCLE_FRAME_MATERIALS",
           "value_name": "aluninio"
       },
       {
           "id": "BICYCLE_TYPE",
           "value_name": "Mountain bike"
       },
       {
           "id": "BRAND",
           "value_name": "Totem"
       },
       {
           "id": "FRONT_BRAKE_TYPE",
           "value_name": "Disco mecánico"
       },
       {
           "id": "GENDER",
           "value_name": "Sin género"
       },
       {
           "id": "MODEL",
           "value_name": "Totem"
       },
       {
           "id": "REAR_BRAKE_TYPE",
           "value_name": "Disco mecánico"
       },
       {
           "id": "GTIN",
           "value_name": "7898945080293"
       }
   ]
}'

EExample of a listing with variations and with GTIN:

curl -L -X POST 'https://api.mercadolibre.com/items' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
   "title": "Bicicleta Mtb Totem By Topmega R29 Producto Test Variaciones",
   "category_id": "MLA6143",
   "price": 99999,
   "currency_id": "ARS",
   "available_quantity": 2,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "6 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía de fábrica"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "condition": "new",
   "pictures": [
       {
           "source": "http://http2.mlstatic.com/D_608172-MLA53351140125_012023-O.jpg"
       },
       {
           "source": "http://http2.mlstatic.com/D_714634-MLA53351124241_012023-O.jpg"
       },
       {
           "source": "http://http2.mlstatic.com/D_878513-MLA53351118304_012023-O.jpg"
       }
   ],
   "attributes": [
       {
           "id": "BICYCLE_FRAME_MATERIALS",
           "value_name": "aluninio"
       },
       {
           "id": "BICYCLE_TYPE",
           "value_name": "Mountain bike"
       },
       {
           "id": "BRAND",
           "value_name": "Totem"
       },
       {
           "id": "FRONT_BRAKE_TYPE",
           "value_name": "Disco mecánico"
       },
       {
           "id": "GENDER",
           "value_name": "Sin género"
       },
       {
           "id": "MODEL",
           "value_name": "Totem"
       },
       {
           "id": "REAR_BRAKE_TYPE",
           "value_name": "Disco mecánico"
       }
   ],
   "variations": [
       {
           "price": 99999,
           "attribute_combinations": [
               {
                   "id": "COLOR",
                   "value_name": "Gris"
               },
               {
                   "id": "FRAME_SIZE",
                   "value_name": "M"
               }
           ],
           "available_quantity": 2,
           "picture_ids": [
               "811782-MLA53283867805_012023"
           ],
           "attributes": [
               {
                   "id": "MAIN_COLOR",
                   "value_name": "Gris"
               },
               {
                   "id": "GTIN",
                   "value_name": "7898945080293"
               }
           ]
       }
   ]
}'

Add identifiers

Example of a listing without variations, adding the GTIN field:

curl -L -X PUT 'https://api.mercadolibre.com/items/MLA1363353921' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
   "attributes": [
       {
           "id": "GTIN",
           "value_name": "7898945080293"
       }
   ]
}'

Example of a listing with variations, adding the GTIN field. You must send the complete list of variations you want to remain (indicating the ID of each variation):

curl -L -X PUT 'https://api.mercadolibre.com/items/MLA1378022956' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
   "variations": [
       {
           "id": 177163823616,
           "attributes": [
               {
                   "id": "GTIN",
                   "value_name": "7898945080293"
               }
           ]
       }
   ]
}'

If the listing has the GTIN attribute as its main attributes, you will not be able to specify it as a variable again. In this case, you must first delete it and then specify it as a variable.

curl -L -X PUT 'https://api.mercadolibre.com/items/MLA1363353921' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
   "attributes": [
       {
           "id": "GTIN",
           "value_name": null
       }
   ]
}'

Reasons for not sending the GTIN

In some categories the GTIN attribute is marked as conditional_required, if you do not send it, it is allowed to add the reason why. To do this, we create the attribute EMPTY_GTIN_REASON.

The EMPTY_GTIN_REASON attribute is conditionally required conditional_required: true and it will only be allowed to send in cases that do not have GTIN loaded in brands of these domains. Always remember to prioritize the sending of the GTIN.

This new attribute will allow to load from a list of reasons previously available in the datasheet, the reason why the publication has no GTIN, by request /categories/$CATEGORY_ID/attributes:

{
    "id": "EMPTY_GTIN_REASON",
    "name": "Motivo de GTIN vacío",
    "tags": {
      "conditional_required": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "17055158",
        "name": "Artesanal"
      },
      {
        "id": "17055159",
        "name": "Kit"
      },
      {
        "id": "17055160",
        "name": "No registrado"
      },
      {
        "id": "17055161",
        "name": "Otro"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  }

LList of allowed values

• Artesanal: the article is a handicraft, self-made.
• Kit: the article is a set of products or a kit.
• No registrado: the item is not yet registered.
• Otro: there is another reason (different from Handmade, Kit and Unregistered) that prevents the seller from uploading the GTIN.

Example of validation when the GTIN is not being sent and it is required to be sent:

"message": "Validation error",
"error": "validation_error",
"status": 400,
"cause": [
{
"department": "supply",
"cause_id": 7810,
"type": "error",
"code": "item.attribute.missing_conditional_required",
"references": [
"item.attributes"
],
"message": "The attributes [GTIN] are required for category [MLB11172]. Check the attribute is present in the attributes list or in all variation's attributes_combination or attributes."
}
]
}

Example of validation when the GTIN is not being sent and a reason is required to be specified:

{
   "message": "Validation error",
   "error": "validation_error",
   "status": 400,
   "cause": [
       {
           "department": "supply",
           "cause_id": 7810,
           "type": "error",
           "code": "item.attribute.missing_conditional_required",
           "references": [
               "item.attributes"
           ],
           "message": "The attributes [EMPTY_GTIN_REASON] are required for category [MLA455058]. Check the attribute is present in the attributes list or in all variation's attributes_combination or attributes."
       }
   ]
}

Consult the listing

To get this data, you must do a GET to the API from /items/ adding the ?include_attributes=all call to get the full item detail.

Request example:

curl -L -X GET 'https://api.mercadolibre.com/items/$ITEM_ID?include_attributes=all' -H 'Authorization: Bearer Bearer $ACCESS_TOKEN'

Response example:

{
   "id": "MLA1378022956",
   "site_id": "MLA",
   "title": "Bicicleta Mtb Totem By Topmega R29 Producto Test Variaciones",
   "subtitle": null,
   "seller_id": 1108966308,
   "category_id": "MLA6143",
   "official_store_id": null,
   "price": 99999,
   "base_price": 99999,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "ARS",
   "initial_quantity": 2,
   "available_quantity": 2,
   "sold_quantity": 0,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "name": "Tiempo de garantía",
           "value_id": null,
           "value_name": "6 meses",
           "value_struct": {
               "number": 6,
               "unit": "meses"
           },
           "values": [
               {
                   "id": null,
                   "name": "6 meses",
                   "struct": {
                       "number": 6,
                       "unit": "meses"
                   }
               }
           ],
           "value_type": "number_unit"
       },
       {
           "id": "WARRANTY_TYPE",
           "name": "Tipo de garantía",
           "value_id": "2230279",
           "value_name": "Garantía de fábrica",
           "value_struct": null,
           "values": [
               {
                   "id": "2230279",
                   "name": "Garantía de fábrica",
                   "struct": null
               }
           ],
           "value_type": "list"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "start_time": "2023-03-22T16:00:07.138Z",
   "stop_time": "2043-03-17T04:00:00.000Z",
   "end_time": "2043-03-17T04:00:00.000Z",
   "expiration_time": "2023-06-10T16:00:07.234Z",
   "condition": "new",
   "permalink": "https://articulo.mercadolibre.com.ar/MLA-1378022956-bicicleta-mtb-totem-by-topmega-r29-producto-test-variaciones-_JM",
   "thumbnail_id": "811782-MLA53283867805_012023",
   "thumbnail": "http://http2.mlstatic.com/D_811782-MLA53283867805_012023-I.jpg",
   "secure_thumbnail": "https://http2.mlstatic.com/D_811782-MLA53283867805_012023-I.jpg",
   "pictures": [
       {
           "id": "867579-MLA54548045653_032023",
           "url": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "secure_url": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "size": "500x500",
           "max_size": "500x500",
           "quality": ""
       },
       {
           "id": "799020-MLA54548045651_032023",
           "url": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "secure_url": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "size": "500x500",
           "max_size": "500x500",
           "quality": ""
       },
       {
           "id": "644762-MLA54548045655_032023",
           "url": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "secure_url": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-ES.jpg",
           "size": "500x500",
           "max_size": "500x500",
           "quality": ""
       },
       {
           "id": "811782-MLA53283867805_012023",
           "url": "http://http2.mlstatic.com/D_811782-MLA53283867805_012023-O.jpg",
           "secure_url": "https://http2.mlstatic.com/D_811782-MLA53283867805_012023-O.jpg",
           "size": "500x329",
           "max_size": "1080x711",
           "quality": ""
       }
   ],
   "video_id": null,
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "shipping": {
       "mode": "me2",
       "methods": [],
       "tags": [
           "mandatory_free_shipping"
       ],
       "dimensions": null,
       "local_pick_up": false,
       "free_shipping": true,
       "logistic_type": "drop_off",
       "store_pick_up": false
   },
   "international_delivery_mode": "none",
   "seller_address": {
       "comment": "10 Referencia: Cerca al parque",
       "address_line": "av petit thouars 12",
       "zip_code": "3730",
       "city": {
           "name": "Charata"
       },
       "state": {
           "id": "AR-H",
           "name": "Chaco"
       },
       "country": {
           "id": "AR",
           "name": "Argentina"
       },
       "search_location": {
           "neighborhood": {
               "id": "TUxBQkNIQTk4Mzha",
               "name": "Charata"
           },
           "city": {
               "id": "TUxBQ0NIQTMzNjQw",
               "name": "Chacabuco"
           },
           "state": {
               "id": "TUxBUENIQW8xMTNhOA",
               "name": "Chaco"
           }
       },
       "latitude": -27.2179902,
       "longitude": -61.18736169999999,
       "id": 1277144929
   },
   "seller_contact": null,
   "location": {},
   "geolocation": {
       "latitude": -27.2179902,
       "longitude": -61.18736169999999
   },
   "coverage_areas": [],
   "attributes": [
       {
           "id": "ITEM_CONDITION",
           "name": "Condición del ítem",
           "value_id": "2230284",
           "value_name": "Nuevo",
           "value_struct": null,
           "values": [
               {
                   "id": "2230284",
                   "name": "Nuevo",
                   "struct": null
               }
           ],
           "attribute_group_id": "",
           "attribute_group_name": "",
           "value_type": "list"
       },
       {
           "id": "BICYCLE_FRAME_MATERIALS",
           "name": "Materiales del cuadro de la bicicleta",
           "value_id": null,
           "value_name": "aluninio",
           "value_struct": null,
           "values": [
               {
                   "id": null,
                   "name": "aluninio",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "BICYCLE_TYPE",
           "name": "Tipo de bicicleta",
           "value_id": "240445",
           "value_name": "Mountain bike",
           "value_struct": null,
           "values": [
               {
                   "id": "240445",
                   "name": "Mountain bike",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "BRAND",
           "name": "Marca",
           "value_id": null,
           "value_name": "Totem",
           "value_struct": null,
           "values": [
               {
                   "id": null,
                   "name": "Totem",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "FRONT_BRAKE_TYPE",
           "name": "Tipo de freno delantero",
           "value_id": "8117600",
           "value_name": "Disco mecánico",
           "value_struct": null,
           "values": [
               {
                   "id": "8117600",
                   "name": "Disco mecánico",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "GENDER",
           "name": "Género",
           "value_id": "110461",
           "value_name": "Sin género",
           "value_struct": null,
           "values": [
               {
                   "id": "110461",
                   "name": "Sin género",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "list"
       },
       {
           "id": "MODEL",
           "name": "Modelo",
           "value_id": null,
           "value_name": "Totem",
           "value_struct": null,
           "values": [
               {
                   "id": null,
                   "name": "Totem",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "REAR_BRAKE_TYPE",
           "name": "Tipo de freno trasero",
           "value_id": "6440294",
           "value_name": "Disco mecánico",
           "value_struct": null,
           "values": [
               {
                   "id": "6440294",
                   "name": "Disco mecánico",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       }
   ],
   "warnings": [],
   "listing_source": "",
   "variations": [
       {
           "id": 177163823616,
           "price": 99999,
           "attribute_combinations": [
               {
                   "id": "COLOR",
                   "name": "Color",
                   "value_id": "283165",
                   "value_name": "Gris",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "283165",
                           "name": "Gris",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               },
               {
                   "id": "FRAME_SIZE",
                   "name": "Tamaño del cuadro",
                   "value_id": "454143",
                   "value_name": "M",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "454143",
                           "name": "M",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               }
           ],
           "available_quantity": 2,
           "sold_quantity": 0,
           "sale_terms": [],
           "picture_ids": [
               "811782-MLA53283867805_012023"
           ],
           "seller_custom_field": null,
           "catalog_product_id": null,
           "attributes": [
               {
                   "id": "MAIN_COLOR",
                   "name": "Color principal",
                   "value_id": "2450294",
                   "value_name": "Gris",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "2450294",
                           "name": "Gris",
                           "struct": null
                       }
                   ],
                   "value_type": "list"
               },
               {
                   "id": "GTIN",
                   "name": "Código universal de producto",
                   "value_id": null,
                   "value_name": "7898945080293",
                   "value_struct": null,
                   "values": [
                       {
                           "id": null,
                           "name": "7898945080293",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               }
           ],
           "inventory_id": null,
           "item_relations": []
       }
   ],
   "status": "active",
   "sub_status": [],
   "tags": [
       "good_quality_thumbnail",
       "test_item",
       "immediate_payment"
   ],
   "warranty": "Garantía de fábrica: 6 meses",
   "catalog_product_id": null,
   "domain_id": "MLA-BICYCLES",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [],
   "automatic_relist": false,
   "date_created": "2023-03-22T16:00:07.408Z",
   "last_updated": "2023-03-22T16:00:18.722Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": [],
   "channels": [
       "marketplace"
   ]
}

Considerations

• They are not internal SKUs.
• You can send more than one identification code for the same listing for the same product. In this case, you must send in the GTIN attribute all the product code identifiers separated by commas.
• Remember to check /attributes if the attributes are marked with the following tags:
  - required, the attribute is required.
  - new_required, the attribute is mandatory if the publication condition is new.
  - conditional_required, the attribute is mandatory following certain conditions in the publication.
  
• The number of characters varies by code type: they can have 8, 10, 12, 13 or 14 characters. You can even rewrite the same code with left zero padding and it will still be valid.
• GTINs sent are validated and, if not valid, the POST will not be allowed. You can see the details of the validation.