Catalog eligibility

Contents

→Identify an eligible publication for catalogue
→Filtering of items per seller
    ↳Ítems elegibility tag
    ↳Eligibility of an existing publication with associated catalog_product_id
→Verify eligible multiple publications with multiget


Identify an eligible publication for catalogue

It is important that before publishing, you recognize which publications created are eligible or can be published in the catalog. For this, you can use the catalog_listing_eligible tag and recognize the posts easily or opt for the eligibility resources of a post or the multiget to verify a set of posts.

Note:
At the moment, only certain publications can participate in the catalog that meet certain requirements such as being new and in the CELLPHONES domain it is necessary for the phone to be released.

Filtering of items per seller

This filter will distinguish between catalog and traditional publications. For that, you must use the catalog_listing parameter in the search with the value true or false, depending on what you want to consult.
First, we identify all the catalog items of a seller. Keep in mind that you must pass the corresponding status parameter in case you want to add a filter such as status="active".

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?catalog_listing=true

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=true

Catalog items shot response:

{
  "seller_id": "123456789",
  "query": null,
  "paging": {
    "limit": 50,
    "offset": 0,
    "total": 8
  },
  "results": [
    "MLA123456789",
    "MLA234567890",
    "MLA345678912",
    "MLA456789123",
    "MLA567891234",
    "MLA678912345",
    "MLA789123456",
    "MLA891234567"
  ],
  "filters": [
  ],
  "available_filters": [],
  "orders": [],
  "available_orders": []
}

Also, you can use the same filter to identify all the seller´s non-catalog items.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?catalog_listing=false

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=false

marketplace ítems´ short response:

{
  "seller_id": "123456789",
  "query": null,
  "paging": {
    "limit": 50,
    "offset": 0,
    "total": 2902
  },
  "results": [
    "MLA987654321",
    "MLA123789456",
    "MLA456789123",
    "MLA132465798",
    "MLA978645312",
    "MLA312645978",
    "MLA654987321",
    "MLA123789654",
      ],
  "filters": [
  ],
  "available_filters": [],
  "orders": [],
  "available_orders": []
}

Ítems elegibility tag

Through the search resource, you will be able to identify all the items of the sellers that are eligible for the catalog with the catalog_listing_eligible tag and that are not yet participating in it. Make the following request to consult them:

Request:

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

Example:

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

Response:

{
   "seller_id":"658869707",
   "query":null,
   "paging":{
      "limit":50,
      "offset":0,
      "total":0
   },
   "results":[
      
   ],
   "orders":[
      {
         "id":"stop_time_asc",
         "name":"Order by stop time ascending"
      }
   ],
   "available_orders":[
      {
         "id":"stop_time_asc",
         "name":"Order by stop time ascending"
      },
      {
         "id":"stop_time_desc",
         "name":"Order by stop time descending"
      },
      {
         "id":"start_time_asc",
         "name":"Order by start time ascending"
      },
      {
         "id":"start_time_desc",
         "name":"Order by start time descending"
      },
      {
         "id":"available_quantity_asc",
         "name":"Order by available quantity ascending"
      },
      {
         "id":"available_quantity_desc",
         "name":"Order by available quantity descending"
      },
      {
         "id":"sold_quantity_asc",
         "name":"Order by sold quantity ascending"
      },
      {
         "id":"sold_quantity_desc",
         "name":"Order by sold quantity descending"
      },
      {
         "id":"price_asc",
         "name":"Order by price ascending"
      },
      {
         "id":"price_desc",
         "name":"Order by price descending"
      },
      {
         "id":"last_updated_desc",
         "name":"Order by lastUpdated descending"
      },
      {
         "id":"last_updated_asc",
         "name":"Order by last updated ascending"
      },
      {
         "id":"total_sold_quantity_asc",
         "name":"Order by total sold quantity ascending"
      },
      {
         "id":{
            "id":"total_sold_quantity_desc",
            "field":"sold_quantity",
            "missing":"_last",
            "order":"desc"
         },
         "name":"Order by total sold quantity descending"
      },
      {
         "id":{
            "id":"inventory_id_asc",
            "field":"inventory_id",
            "missing":"_last",
            "order":"asc"
         },
         "name":"Order by inventory id ascending"
      }
   ]
}

The search response returns all seller´s items with the catalog_listing_eligible tag.

Eligible item example:

{
  "id": "MLA123456789",
  "site_id": "MLA",
  "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
  "subtitle": null,
  "seller_id": 123456987,
  "category_id": "MLA3530",
  "official_store_id": null,
  "price": 50,
  "base_price": 50,
  "original_price": null,
  "currency_id": "ARS",
  "initial_quantity": 1,
  "available_quantity": 1,
  "sold_quantity": 0,
  "sale_terms": [
  ],
  "buying_mode": "buy_it_now",
  "listing_type_id": "free",
  "start_time": "2020-02-17T16:30:39.000Z",
  "stop_time": "2020-04-17T04:00:00.000Z",
  "condition": "used",
  "permalink": "https://articulo.mercadolibre.com.ar/MLA-839616438-item-de-testeo-por-favor-no-ofertar-kcoff-_JM",
  "thumbnail": "http://mla-s1-p.mlstatic.com/951410-MLA40807113659_022020-I.jpg",
  "secure_thumbnail": "https://mla-s1-p.mlstatic.com/951410-MLA40807113659_022020-I.jpg",
  "pictures": [],
  "video_id": null,
  "descriptions": [
  ],
  "accepts_mercadopago": true,
  "non_mercado_pago_payment_methods": [
  ],
  "shipping": {},
  "international_delivery_mode": "none",
  "seller_address": {},
  "seller_contact": null,
  "location": {
  },
  "geolocation": {},
  "coverage_areas": [
  ],
  "attributes": [],
  "warnings": [
  ],
  "listing_source": "",
  "variations": [
  ],
  "status": "active",
  "sub_status": [
  ],
  "tags": [
    "catalog_listing_eligible",
    "good_quality_picture",
    "test_item",
    "immediate_payment"
  ],
  "warranty": null,
  "catalog_product_id": null,
  "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
  "parent_item_id": null,
  "differential_pricing": null,
  "deal_ids": [
  ],
  "automatic_relist": false,
  "date_created": "2020-02-17T16:30:40.000Z",
  "last_updated": "2020-02-17T16:34:12.000Z",
  "health": 0.4,
  "catalog_listing": false
}

Eligibility of an existing publication with associated catalog_product_id

The following examples show how to validate the eligibility of an existing publication to link to a new catalog publication with synchronized stock that has an associated catalog_product_id.

Request:

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

Example with variations:

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

Response:

{
    "id": "MLA123456789",
    "site_id": "MLA",
    "domain_id": "MLA-CELLPHONES",
    "status": null,
    "buy_box_eligible": null,
    "variations": [
        {
            "id": 1312323,
            "status": "READY_FOR_OPTIN",
            "buy_box_eligible": true
        },
        {
            "id": 1312444,
            "status": "READY_FOR_OPTIN",
            "buy_box_eligible": true
        }
    ]
}

Example without variations:

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

Response:

{
    "id": "MLB1234",
    "site_id": "MLB",
    "domain_id": "MLB-MICROWAVES",
    "status": "READY_FOR_OPTIN",
    "buy_box_eligible": true,
    "variations": []
}

Considerations

  • If the item does not have variations, the eligibility will be expressed through the first level buy_box_eligible field in the JSON of the response and the variations section will be empty.
  • If the item has variations, the eligibility of each of them will be expressed within the variations section, which will contain an array per variation with a buy_box_eligible field for each of them.

Description of fields

id: ID of the publication we are consulting.
site_id: ID of the site to which the item belongs.
domain_id: ID of the domain to which the item belongs.
buy_box_eligible: indicates whether the item/variation is enabled or not to participate in the catalog.
variations: are all the variations that an item has. Each one will have associated a status and a value for the buy_box_eligible field.
status: defines the situation of the traditional item with respect to the catalog. The different states may be:

Eligible:

  • READY_FOR_OPTIN: the item can be published in the catalog.

Not eligible:

  • ALREADY_OPTED_IN: the traditional item being queried already has an associated catalog item.
  • CLOSED: the item is in a condition that can no longer be sold.
  • PRODUCT_INACTIVE: the item is associated with a product that has not yet been catalog-enabled or the item does not yet have a catalog_product_id assigned.
  • NOT_ELIGIBLE: There is a business rule that prevents the item from applying to the catalog. (ex: a used cellphone, a cellphone without releasing).

If you query for a competing catalog item, the status will be COMPETING.


Verify eligible multiple publications with multiget

To check if multiple publications are eligible for catalog, make a single request. You must incorporate the ids parameter in the url, in addition to request the multiget resource, as follows:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/multiget/catalog_listing_eligibility?ids=$ITEM_ID,$ITEM_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/multiget/catalog_listing_eligibility?ids=MLA818878419,MLA820167922

Response:

[
    {
        "code": 200,
        "body": {
            "buy_box_eligible": null,
            "domain_id": "MLA-CELLPHONES",
            "id": "MLA818878419",
            "site_id": "MLA",
            "status": null,
            "variations": [
                {
                    "buy_box_eligible": true,
                    "id": 44612657634,
                    "status": "READY_FOR_OPTIN"
                },
                {
                    "buy_box_eligible": false,
                    "id": 44890704657,
                    "status": "ALREADY_OPTED_IN"
                }
            ]
        }
    },
    {
        "code": 200,
        "body": {
            "buy_box_eligible": null,
            "domain_id": "MLA-CELLPHONES",
            "id": "MLA820167922",
            "site_id": "MLA",
            "status": null,
            "variations": [
                {
                    "buy_box_eligible": true,
                    "id": 44931385066,
                    "status": "READY_FOR_OPTIN"
                },
                {
                    "buy_box_eligible": true,
                    "id": 44931385069,
                    "status": "READY_FOR_OPTIN"
                }
            ]
        }
    }
]

Fields description

code: it´s the HTTP status code that the query returns with each item_id, if there is no error it must be 200.
body: body of the message that returns this request to the eligibility API.


Next: Product search.

or register to recieve the latest news about our API