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 https://api.mercadolibre.com/users/$USER_ID/items/search?catalog_listing=true&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=true&access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/users/$USER_ID/items/search?catalog_listing=false&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=false&access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/users/$USER_ID/items/search?tags=catalog_listing_eligible&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/123456987/items/search?tags=catalog_listing_eligible&access_token=$ACCESS_TOKEN

Short response:

{
    "seller_id": "123456987",
    "query": null,
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 1
    },
    "results": [
        "MLA123456789"
    ],
    "filters": [],
    "available_filters": [
            ]
}

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 https://api.mercadolibre.com/items/$ITEM_ID/catalog_listing_eligibility?access_token=$ACCESS_TOKEN

Example with variations:

curl -X GET https://api.mercadolibre.com/items/MLA123456789/catalog_listing_eligibility?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/items/MLB1234/catalog_listing_eligibility?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/multiget/catalog_listing_eligibility?ids=$ITEM_ID,$ITEM_ID&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/multiget/catalog_listing_eligibility?ids=MLA818878419,MLA820167922&access_token=$ACCESS_TOKEN

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