Items & Searches

Summary of available resources

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

{
    "seller_id": "2560656533",
    "results": [
        "CBT2518294370"
    ],
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 1
    }
}

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

{
    "seller_id": "2560656533",
    "results": [
        "CBT2518294370"
    ],
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 1
    }
}

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?nickname=$NICKNAME

{
    "results": [
        {
            "id": "MLM12345678"
        }
    ]
}

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/2560656533/items/search

{
    "seller_id": "2560656533",
    "results": [
        "CBT2518294370",
        "CBT2777715207"
    ],
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 2
    }
}

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=CBT2518294370

[
    {
        "code": 200,
        "body": {
            "id": "CBT2518294370",
            "site_id": "CBT",
            "title": "Game Test Play Toy",
            "price": 83
        }
    }
]

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users?ids=2560656533

[
    {
        "code": 200,
        "body": {
            "id": 2560656533,
            "nickname": "TESTUSER667696975",
            "site_id": "CBT"
        }
    }
]

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=CBT2518294370&attributes=id,title,price,category_id

[
    {
        "code": 200,
        "body": {
            "id": "CBT2518294370",
            "title": "Game Test Play Toy",
            "category_id": "CBT11625",
            "price": 83
        }
    }
]

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

{
    "scroll_id": "eyJpZCI6IkNCVDI3Nzc3MTUyMDciLCJ...",
    "seller_id": "2560656533",
    "results": ["CBT2518294370"],
    "paging": {
        "limit": 50,
        "total": 2
    }
}

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

{
    "item_id": "CBT2518294370",
    "marketplace_items": [
        {
            "item_id": "MLM2374731499",
            "site_id": "MLM"
        }
    ]
}

Values in sold_quantity and available_quantity fields

In the public resources of Items and Searches, the information of the "sold_quantity" and "available_quantity" fields will be referential with the following values:

Get user listings

Retrieve all listings from your seller account. This is the recommended method for CBT integrations.

Call

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

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/2560656533/items/search

Response

{
  "seller_id": "2560656533",
  "results": [
    "CBT2518294370",
    "CBT2777715207"
  ],
  "paging": {
    "limit": 50,
    "offset": 0,
    "total": 2
  }
}

Search with status filter

Listings linked to a user can be filtered by status type, both Global Listings (CBT) and Site Listings.

Required Parameters

• user_id: The user ID (merchant) for whom the search will be performed.
• offset and limit: Parameters used to paginate results. Optional fields, defaults are 0 and 50.
• status: The listing status to filter by (a list), such as: status=pending, active, paused, deleted (inactive).
• search_type: The type of search to perform (e.g., search, scan). Optional field, defaults to search.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/$MERCHANT_ID

{
  "user_id": 471826944,
  "site_id": "CBT",
  "marketplaces": [
    {
      "user_id": 471828584,
      "site_id": "MLM",
      "logistic_type": "remote"
    },
    {
      "user_id": 471830260,
      "site_id": "MLB",
      "logistic_type": "remote"
    },
    {
      "user_id": 538932857,
      "site_id": "MLC",
      "logistic_type": "fulfillment"
    }
  ]
}

Global Listings (CBT) by status

To consult Global Listings, it is necessary to use the parent user_id (merchant).

Call

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/{merchant_id}/items/search?status=paused

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/1684344969/items/search?status=paused

Site Listings by status

To consult specific marketplace listings, it is necessary to use the child user_id (seller_id).

Call (MLM listings)

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/users/625822648/items/search?status=active

By SKU

• Seller_custom_field: If the item contains a SKU in the "seller_custom_field" field, you can try as follows:

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

• Seller_sku: If the item contains a SKU in the "SELLER_SKU" field, you can try like this:

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

With/without product identifier

Using the parameters:

• missing_product_identifiers=true: get items that do not have a Product Identifier loaded or submitted.
• missing_product_identifiers=false: get the list of listings with PIs uploaded or sending.

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

Items with loss of exposure

Identify listings losing exposure due to claims or cancellations:

• unhealthy: listings already losing exposure.
• warning: listings that could lose exposure.
• healthy: listings not impacted.

Parameters

Filter and sort the results of the seller's listings

Inside the resource /users/(user_id)/items/search? there are the "available_orders" and "available_filters" fields.

How to order? Add "orders" with the available ID, for example: "start_time_desc."

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

How to filter? For example, to filter listings with listing_type "gold_pro":

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

Filter by free shipping

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

Errors