MercadoLibre Exodus Listing Enrichment

What is MercadoLibre Exodus Listing Enrichment?

MercadoLibre Exodus Listing Enrichment is a private, API-based integration built for Exodus's MercadoLibre Mexico automotive-parts workflow. It returns one validated dataset row per enriched listing, with item ID, title, URL, price, condition, stock, pictures, attributes, category, full description and seller ID, nickname, reputation and location; or one vehicle-compatibility report per MercadoLibre user product; or the verified Mexican compatibility domain as a quick health record. The Exodus catalog and pricing team uses it to enrich known listings or search results in bounded daily batches through MercadoLibre's authenticated API under an Exodus-managed token.

Best fit for this Actor

• Designed for the Exodus workflow. Use it to enrich known MercadoLibre listing URLs with descriptions and seller signals, or to search one LATAM marketplace and enrich the results.
• Authorized vehicle fitment. vehicle_compatibility mode returns the exact matches MercadoLibre's authorized user-product endpoint lists under MLM-CARS_AND_VANS_FOR_COMPATIBILITIES.
• A safe default. The default compatibility_domain mode runs with no token, so scheduled health checks confirm the Actor is ready before a paid batch.
• Bounded batches. maxResults caps persisted records at 150 per run and apiConcurrency caps parallel API calls, which keeps daily cost and token use predictable.
• Listing discovery first. For finding public listings by keyword across MercadoLibre without a token, start with MercadoLibre Search Scraper, then pass the listing URLs into startUrls here.

Modes at a glance

Mode	Input	One dataset row is
compatibility_domain	compatibilityQuery	The verified Mexican vehicle-compatibility domain
listing_enrichment	startUrls or searchQuery with country	One enriched listing with description and seller fields
vehicle_compatibility	startUrls or userProductIds	One compatibility report per user product, with its vehicle matches

Workflow example: a daily parts-catalog refresh

The Exodus team starts each morning with a scheduled compatibility_domain run as a readiness check. They then run listing_enrichment with searchQuery set to a part family such as filtro aire jetta, country set to MX and maxResults set to 150. The dataset returns each listing's price, stock, description and seller reputation. The team exports the rows to the pricing sheet, compares prices and seller signals against yesterday's export, and passes the shortlisted listing URLs to a vehicle_compatibility run to confirm which vehicles each part fits.

Required configuration

Listing enrichment and vehicle compatibility read MercadoLibre's authenticated API with an OAuth token stored as the Actor environment secret MELI_ACCESS_TOKEN. The token lives in the Actor's encrypted environment, stays out of the run input and logs, and needs access to item descriptions and user-product compatibility. The compatibility_domain mode runs without it.

Input

{
  "mode": "listing_enrichment",
  "startUrls": [
    { "url": "https://articulo.mercadolibre.com.mx/MLM-1234567890-example-_JM" }
  ],
  "maxResults": 10,
  "apiConcurrency": 4
}

Field	Type	What it controls
mode	string	compatibility_domain (default), listing_enrichment or vehicle_compatibility.
compatibilityQuery	string	Spanish phrase for Mexican compatibility-domain discovery. Default camioneta.
startUrls	array	MercadoLibre or Mercado Livre listing URLs to enrich or resolve.
searchQuery	string	Keyword for authenticated site search in listing_enrichment mode, such as filtro aire jetta.
country	string	Marketplace for search: MX, BR, AR, CL, CO, PE, UY, EC or DO. Default MX.
maxResults	integer	Persisted records per run, 1 to 150. Default 10.
apiConcurrency	integer	Parallel API requests, 1 to 6. Default 4.
userProductIds	array	MercadoLibre user-product IDs such as MLMU123456 for vehicle compatibility.
maxVehicleMatchesPerProduct	integer	Compatibility entries kept per user product, 1 to 100. Default 50.

Search then enrich:

{
  "mode": "listing_enrichment",
  "country": "MX",
  "searchQuery": "filtro aire jetta",
  "maxResults": 150,
  "apiConcurrency": 4
}

Vehicle compatibility for known user products:

{
  "mode": "vehicle_compatibility",
  "userProductIds": ["MLMU123456"],
  "maxVehicleMatchesPerProduct": 50
}

Output

Field	What it contains
mode, country, siteId	Mode, marketplace and MercadoLibre site
itemId, userProductId, title, url	Listing and user-product identity
price, originalPrice, currencyId, discountPercent	Pricing
condition, soldQuantity, availableQuantity, freeShipping, installments	Listing status and sales signals
thumbnail, pictures, attributes, variations	Media, specs and variants
categoryId, categoryPath	Category
description	Plain-text description from the item-description endpoint
sellerId, sellerName, sellerReputation, sellerLocation, location	Seller signals from the item response
reviewRating, reviewCount	Review summary when available
compatibilityDomain	Domain discovery data in compatibility_domain mode
vehicleCompatibilities	Authorized vehicle matches in vehicle_compatibility mode
dateScraped, source, _warnings	Collection time, API route and notes

Example compatibility_domain record:

{
  "mode": "compatibility_domain",
  "country": "MX",
  "siteId": "MLM",
  "itemId": null,
  "title": "Carros y camionetas para compatibilidades",
  "url": null,
  "price": null,
  "originalPrice": null,
  "currencyId": "MXN",
  "discountPercent": null,
  "condition": null,
  "soldQuantity": null,
  "availableQuantity": null,
  "freeShipping": null,
  "installments": null,
  "thumbnail": null,
  "pictures": null,
  "attributes": [
    {
      "id": "REGION",
      "name": "Región",
      "value": "México"
    },
    {
      "id": "ASPIRATION",
      "name": "Aspiración",
      "value": "Aspirado"
    }
  ],
  "variations": null,
  "categoryId": "MLM456252",
  "categoryPath": "Auto y Camioneta para Compats",
  "description": null,
  "sellerId": null,
  "sellerName": null,
  "sellerReputation": null,
  "sellerLocation": null,
  "location": null,
  "reviewRating": null,
  "reviewCount": null,
  "compatibilityDomain": {
    "id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
    "name": "Carros y camionetas para compatibilidades",
    "categoryId": "MLM456252",
    "categoryName": "Auto y Camioneta para Compats",
    "attributes": [
      {
        "id": "REGION",
        "name": "Región",
        "value": "México"
      },
      {
        "id": "ASPIRATION",
        "name": "Aspiración",
        "value": "Aspirado"
      }
    ]
  },
  "dateScraped": "2026-10-01T01:27:09.274Z",
  "source": "mercadolibre-domain-discovery-api",
  "_warnings": null
}

Listing rows fill the listing, description and seller fields from the authenticated item API, and a description MercadoLibre leaves empty stays null with a note in _warnings. Fitment always comes from MercadoLibre's compatibility response rather than from titles or attributes. Every run writes OUTPUT and RUN_SUMMARY with an outcome of COMPLETE, PARTIAL, VALID_EMPTY, INVALID_INPUT, UPSTREAM_FAILED or CONFIG_ERROR.

Pricing

This Actor uses Pay per event with Apify platform usage included in the event price. Two events apply: Actor Start once per run, and Enriched listing or compatibility domain for each validated record saved, with the description and seller fields included in the same listing event. For example, a listing_enrichment run that saves 150 listings creates 150 enrichment events plus one Actor Start event, and maxResults sets that ceiling. The live Pricing tab on this page shows the current event prices and which record types are charged.

API example

curl -X POST "https://api.apify.com/v2/acts/khadinakbar~mercadolibre-exodus-enrichment-private/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "compatibility_domain", "compatibilityQuery": "camioneta"}'

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("khadinakbar/mercadolibre-exodus-enrichment-private").call(run_input={
    "mode": "listing_enrichment",
    "country": "MX",
    "searchQuery": "filtro aire jetta",
    "maxResults": 25,
})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["itemId"], row["title"], row["price"], row["sellerName"])

Use with AI agents through Apify MCP

Connect this Actor to an MCP client such as Claude through Apify MCP, then ask:

Run listing enrichment on MercadoLibre Mexico for "filtro aire jetta" with up to 25 results. Return item ID, title, price, stock, seller nickname and seller reputation level, and report the run outcome.

Agent checklist:

1. Pick the mode that matches the request and set maxResults as the cost ceiling.
2. Start with compatibility_domain when you want a readiness check with no token.
3. Read OUTPUT.outcome; CONFIG_ERROR means the environment token needs attention before listing modes.
4. Read rows with get-dataset-items and keep url, source and dateScraped as provenance.

Best results

Starting situation	Helpful action	Expected outcome
A known list of listings	Pass them in startUrls	One enriched row per listing
A part family to price	Use searchQuery with country and maxResults	Up to 150 enriched results per run
Known user-product IDs	Use userProductIds in vehicle_compatibility mode	Compatibility reports with no extra lookup
A daily schedule	Start with a compatibility_domain check	A quick readiness signal before the paid batch
Large batches	Keep apiConcurrency at the default	Steady throughput within token limits

Builder's note

I built this to replace a slow browser verification loop with bounded calls to MercadoLibre's own API, because Exodus needed descriptions, seller signals and fitment in one daily pass. I learned that fitment is only trustworthy when it comes from MercadoLibre's authorized compatibility response, so the Actor reports those matches as returned and never infers them. My goal was a predictable daily budget, which is why record caps, concurrency caps and a no-token health mode are all part of the input.

FAQ

Who is this Actor for?

It is a private integration designed for Exodus's MercadoLibre workflow and its managed API token.

Which marketplaces can listing search use?

Mexico, Brazil, Argentina, Chile, Colombia, Peru, Uruguay, Ecuador and the Dominican Republic, selected with country.

Does the default input need a token?

No. The default compatibility_domain mode runs without one and suits health checks.

Responsible use

Use the results for legitimate ecommerce research in line with MercadoLibre's API terms, applicable law and your organization's data-governance rules. Seller fields can include personal data, so handle them with a lawful basis. MercadoLibre is a trademark of its owner, and this independent Actor is not affiliated with or endorsed by MercadoLibre.