# VTEX Store Scraper — LatAm Supermarket Prices, EAN & Stock (`yugenox/vtex-retail-catalog-scraper`) Actor

Scrape product catalogs from any VTEX store (plazaVea, Jumbo, Disco, Carrefour AR, Chedraui, Wong …): name, brand, EAN, price, list price, discount, stock, seller, category, images and specs per SKU. Many stores per run; keywords, EANs, categories or links. No login.

- **URL**: https://apify.com/yugenox/vtex-retail-catalog-scraper.md
- **Developed by:** [Yugenox Corp](https://apify.com/yugenox) (community)
- **Categories:** E-commerce, Business, Automation
- **Features:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 products

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## VTEX Store Scraper: LatAm supermarket prices, EAN and stock

Scrape the product catalog of **any store built on VTEX**, the e-commerce platform behind most big Latin American supermarkets and retailers: **plazaVea** and **Wong** (Peru), **Jumbo**, **Disco** and **Carrefour** (Argentina), **Chedraui** (Mexico) and hundreds more. Get one row per product variant (SKU) with the **name, brand, EAN barcode, price, list price, discount, stock, seller, category, images, specifications and promotions**. Search **many stores in one run** by keyword, by **EAN** (the quickest way to compare one product's price across retailers), by category, or read a store's **whole catalog**. No login, no cookies, no browser.

### What you get

| | |
|---|---|
| **Product** | Name, product name, variant name, brand, product / SKU / reference ids, link to the product page |
| **Barcode** | EAN / GTIN of each SKU, so the same product can be matched across stores |
| **Price** | Selling price, list price, price without discount, discount %, currency (PEN, ARS, MXN, CLP, COP, BRL …), price valid until |
| **Stock** | In stock yes / no and the available quantity the store reports |
| **Seller** | The seller of the offer (the store itself or a marketplace seller), and every seller's offer when there are several |
| **Category** | Category, full category path (e.g. `Abarrotes > Chocolatería > Tabletas de Chocolate`) and category ids |
| **Details** | Images, unit of measure, variant attributes (size, color …), specifications (net content, ingredients, nutrition …), promotions and badges, description, release date |
| **Context** | Store, country, which search found it and its position in the store's results, scrape time |

### How to use it

1. Add one or more stores to **Stores**, e.g. `www.plazavea.com.pe`, `www.jumbo.com.ar`, `www.chedraui.com.mx`.
2. Add **Keywords** (`leche`, `arroz`, `coca cola 2 l` …) and/or **EANs**. Every search runs on every store.
3. Set **Max products per store** and run.

Leave Keywords and EANs empty to read each store's **whole catalog**, category by category. You can also paste store links into **Store links**: a product page (`…/tableta-con-leche-hersheys-82g/p`), a category page (`www.plazavea.com.pe/abarrotes/chocolateria`) or a search page. Each link adds its store to the run.

#### Input examples

"leche" in two supermarkets, 10 products each:

```json
{
  "stores": ["www.plazavea.com.pe", "www.jumbo.com.ar"],
  "keywords": ["leche"],
  "maxItemsPerStore": 10
}
```

One product's price in five stores, by barcode:

```json
{
  "stores": ["www.jumbo.com.ar", "www.disco.com.ar", "www.carrefour.com.ar", "www.plazavea.com.pe", "www.wong.pe"],
  "eans": ["7790742141101", "7622300990114"]
}
```

The cheapest rice in stock at Chedraui:

```json
{
  "stores": ["www.chedraui.com.mx"],
  "keywords": ["arroz"],
  "sort": "priceAsc",
  "onlyAvailable": true,
  "maxItemsPerStore": 100
}
```

A store's whole catalog (all categories):

```json
{
  "stores": ["www.wong.pe"],
  "maxItemsPerStore": 0
}
```

### Output example

```json
{
  "store": "www.plazavea.com.pe",
  "country": "PE",
  "currency": "PEN",
  "productId": "101032439",
  "skuId": "11400873",
  "name": "Tableta con Leche HERSHEY'S 82g",
  "brand": "HERSHEYS",
  "ean": "7899970402982",
  "refId": "20423026",
  "category": "Tabletas de Chocolate",
  "categoryPath": "Abarrotes > Chocolatería > Tabletas de Chocolate",
  "categoryIdPath": "431/1439/1634",
  "url": "https://www.plazavea.com.pe/tableta-con-leche-hersheys-82g/p",
  "imageUrl": "https://plazavea.vteximg.com.br/arquivos/ids/29042011/20423026.jpg?v=638508770663170000",
  "price": 10.9,
  "listPrice": 10.9,
  "priceWithoutDiscount": 10.9,
  "discountPercent": 0,
  "available": true,
  "availableQuantity": 61,
  "sellerId": "1",
  "sellerName": "Plaza Vea",
  "sellerCount": 1,
  "offers": [{ "sellerId": "1", "sellerName": "Plaza Vea", "price": 10.9, "listPrice": 10.9, "available": true, "availableQuantity": 61, "isDefault": true }],
  "measurementUnit": "un",
  "unitMultiplier": 1,
  "specifications": {
    "Presentación unitarios vitrina": "Tableta 82g",
    "Contenido Neto": "82g",
    "Alérgenos Declarados": "Maní",
    "Calorías Por Porción": "103/433 Kcal/KJ",
    "Porciones Por Envase": "4"
  },
  "promotions": null,
  "releaseDate": "2024-05-28T00:00:00Z",
  "searchType": "keyword",
  "searchTerm": "leche",
  "position": 5,
  "scrapedAt": "2026-11-02T07:28:21.905Z"
}
```

Every row has the same columns (trimmed above); a value the store doesn't publish is `null`. Prices are in the store's own currency, shown in `currency`.

### Pricing

Pay per event, no subscription:

- **$0.80 per 1,000 products** (one row per SKU saved to your dataset).
- **$0.0002 per search that gives no new product** (a keyword or EAN a store doesn't carry, one whose products were all saved earlier in the run, or one with only out-of-stock products while **Only products in stock** is on). Searches that find at least one new product cost nothing extra.
- **$0.002 per run** (Actor start).

Stores that refuse, don't answer or aren't VTEX stores are never charged. Rows over your **Max products** or your run's spending limit are never saved, so you never pay for them.

### Use cases

- **Price monitoring and price indexes**: track grocery and retail prices across Latin American chains, daily or weekly.
- **Brand and CPG analytics**: where your products are listed, at what price, with which promotions, and whether they're in stock.
- **Cross-retailer comparison by EAN**: the same barcode in every store in one run.
- **Assortment and category research**: complete catalogs with category paths, brands and specifications.
- **E-commerce and marketplace research**: which marketplace sellers sell what, and at what price.

### Tips

- **Store addresses**: use the address you see in the browser, with or without `www.` and `https://`. A store that moved to another domain is reported with its new address.
- **Max products per store** is shared fairly between your searches, so 4 keywords with a maximum of 100 get about 25 products each (a search with fewer matches leaves its share to the next one). Set it to 0 for everything.
- **2,550 products per search**: VTEX stores list at most 2,550 products for any one search. A broader keyword is cut there and the status message says so; split it into narrower keywords or category links. The whole-catalog mode goes past it by walking the store's sub-categories.
- **Only products in stock** leaves out SKUs that are out of stock; they're not saved and not charged.
- **Sales channel**: some stores price by region or channel; enter the store's sales channel number to get those prices.
- **Several stores at once**: up to 4 stores are read side by side, so 4 stores take about as long as one.

### FAQ

**Which stores work?** Any store running on VTEX that keeps its public product catalog open, which is most of them. Verified: plazavea.com.pe, wong.pe, jumbo.com.ar, disco.com.ar, carrefour.com.ar and chedraui.com.mx. A site that isn't built on VTEX is skipped with a plain message and isn't charged.

**Why did a store return nothing?** The run's status message says why for every store: it refused automated requests, asks crawlers not to read its catalog (robots.txt), didn't answer, moved, or isn't a VTEX store. None of these are charged. The full details per store and per search are in the `RUN_REPORT` record of the run's key-value store.

**Why does one product give several rows?** One row per SKU: a T-shirt in three sizes has three SKUs, each with its own EAN, price and stock. Supermarket products usually have one SKU.

**Do I need a proxy?** Keep the default (Apify Proxy, datacenter). It comes with every Apify plan, including the free one.

**Is it legal to scrape VTEX stores?** This Actor only collects publicly available data: product listings that any visitor can see on the store's website without an account, such as names, prices, barcodes, stock and images. Collecting publicly available data is generally legal, but you're responsible for how you use it. You must follow privacy laws such as GDPR, PIPEDA, CCPA and Latin American data-protection laws, as well as each store's terms. If you're unsure, check with a lawyer. More on this: [Is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/)

**Does it access any private data?** No. It reads only the stores' public product catalogs, the same data their product pages show to anyone. It never logs in, never touches carts, accounts or orders, and it follows each store's robots.txt. Product listings describe products, not people; a personal e-mail address in a product description is removed.

*This Actor is not affiliated with, endorsed by or sponsored by VTEX or any of the stores named above.*

# Actor input Schema

## `stores` (type: `array`):

Websites of VTEX stores, e.g. www.plazavea.com.pe, www.jumbo.com.ar, www.disco.com.ar, www.carrefour.com.ar, www.chedraui.com.mx, www.wong.pe. Every search below runs on every store. A store with nothing to search is read whole, category by category.

## `keywords` (type: `array`):

Words to search for in each store, e.g. "leche", "arroz", "coca cola 2 l". Each keyword is a separate search. Leave empty (with no EANs or links) to read each store's whole catalog.

## `eans` (type: `array`):

Look up products by barcode (EAN-13, EAN-8, UPC or GTIN-14) in every store — the quickest way to compare one product's price across retailers.

## `startUrls` (type: `array`):

Optional: product pages (…/leche-gloria-entera/p), category pages (www.plazavea.com.pe/lacteos-y-huevos/leche) or search pages from any VTEX store. Each link adds its store to the run.

## `maxItemsPerStore` (type: `integer`):

Maximum rows (SKUs) per store, shared fairly between your searches. 0 = everything (VTEX serves up to 2,550 products per search; the whole-catalog mode walks the categories to go further).

## `maxItems` (type: `integer`):

Optional cap for the whole run, across all stores. Empty or 0 = no cap beyond the per-store maximum.

## `sort` (type: `string`):

Order in which each store returns products (matters when Max products cuts the list).

## `onlyAvailable` (type: `boolean`):

Leave out SKUs that are out of stock (they are not saved and not charged).

## `categoryIds` (type: `array`):

Advanced: VTEX category IDs from the department down, e.g. "1503" or "1503/24" (see categoryIdPath in the results). IDs differ between stores, so use this with one store; for several stores paste category links instead.

## `salesChannel` (type: `integer`):

Advanced: VTEX sales channel (sc) for stores that price by channel or region. Leave empty for the store's default.

## `proxyConfiguration` (type: `object`):

Apify Proxy (datacenter) is the default and comes with every Apify plan.

## Actor input object example

```json
{
  "stores": [
    "www.plazavea.com.pe",
    "www.jumbo.com.ar"
  ],
  "keywords": [
    "leche"
  ],
  "maxItemsPerStore": 10,
  "sort": "relevance",
  "onlyAvailable": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped products (one row per SKU per store).

## `run` (type: `string`):

Status and statistics for this run.

## `report` (type: `string`):

RUN_REPORT: how the run ended, per store and per search: totals, rows saved, requests and any store that refused.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "stores": [
        "www.plazavea.com.pe",
        "www.jumbo.com.ar"
    ],
    "keywords": [
        "leche"
    ],
    "maxItemsPerStore": 10,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("yugenox/vtex-retail-catalog-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "stores": [
        "www.plazavea.com.pe",
        "www.jumbo.com.ar",
    ],
    "keywords": ["leche"],
    "maxItemsPerStore": 10,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("yugenox/vtex-retail-catalog-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "stores": [
    "www.plazavea.com.pe",
    "www.jumbo.com.ar"
  ],
  "keywords": [
    "leche"
  ],
  "maxItemsPerStore": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call yugenox/vtex-retail-catalog-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yugenox/vtex-retail-catalog-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/md0hvKUjnAQQlhkMm/builds/GmXrd4LB8lM2Ffq6Y/openapi.json
