VTEX stores API & Scraper
VTEX is the e-commerce platform behind a large share of Latin America's supermarkets, pharmacies, DIY chains and department stores.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
Every VTEX store publishes the same public catalog, so this one API reads many stores: pass the store's domain and you get its products as JSON. `search` takes a keyword, a category, a brand, a price range and seven sorts, returns up to 50 products per page and the exact total the store reports. Every product carries all of its SKUs, each with its EAN barcode, reference id, variations such as size and colour, images and one offer per seller: sale price, list price, price before discount, stock flag, best interest-free instalment plan and active promotions, in the store's own currency. `product` opens one product by id, URL slug, SKU id or EAN; `products` fetches up to 50 products or 50 EANs in one call. `categories`, `facets` and `brands` return the store's own vocabulary with the ids search accepts, and `store_info` tells you whether a domain is a VTEX store and which currency, country and sales channel it uses. On 2026-10-14, 18 of 28 VTEX store domains we tried answered, in Mexico, Colombia, Peru, Argentina and Brazil.
What a VTEX field actually contains
Fields that read differently from how they look. Every row was measured against live VTEX stores on 2026-10-14.
| Field | What it holds |
|---|---|
| price | The default seller's selling price, in the store's currency. On 11 of 11 products where the product page publishes structured data, it matched the page's price exactly (Olímpica, Panamericana, Jumbo, Farmacity, Pague Menos, Zona Sul). |
| list_price, list_price_suspect | The store's struck-through price. Some stores fill this field with something else: on Jumbo Argentina the value is the price without 21 % VAT in cents (8,300 becomes 685,950). When the list price is more than five times the price, list_price is null, the original is kept in list_price_raw and list_price_suspect is true, so no fake 98 % discount is reported. |
| spot_price | The cash or PIX price, returned with search_api=intelligent_search only (the catalog search does not carry it). On Americanas 12 of 12 notebook rows had a spot price below the card price; on Plaza Vea and Pague Menos it equalled the price. |
| available_quantity, stock_quantity_capped | Many stores publish a ceiling instead of a count: 99,999, 10,000 or 100 (Zona Sul showed 100 on 7 of 8 rows). Those are returned with stock_quantity_capped true; in_stock is the flag to rely on. Promart publishes real counts such as 18, 240 and 2,198. |
| in_stock, price | An offer with price 0 or quantity 0 is out of stock, not free. Its price is returned as null and in_stock as false. A product that is out of stock everywhere keeps its last offered price with in_stock false. |
| ean, ean_valid | The SKU's EAN as the store entered it. ean_valid checks length and check digit: one pharmacy reuses the placeholder 123456789101112 on unrelated products, which is returned as is with ean_valid false. |
| currency | Read from the store's own sales-channel record, never guessed from the country: MXN, COP, PEN, ARS and BRL were measured. |
| product_id | VTEX's product id as a string. Every search row carries it and product accepts it unchanged: 79 of 79 round trips matched over two runs, leaving out calls a store's firewall refused and one placeholder EAN shared by several products. |
Prices and stock are the logged-out prices of the store's default sales channel. The same eight products returned identical prices and stock from inside and outside the store's country on Chedraui, Plaza Vea and Jumbo. A sales channel can change the assortment: Plaza Vea's channel 2 listed 1,449 milk products against 1,549.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/vtex/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"store": "www.chedraui.com.mx",
"query": "leche",
"page_size": 10
}
}{
"ok": true,
"meta": {
"api": "vtex",
"endpoint": "search",
"mode": "live",
"latency_ms": 865.9,
"record_count": 10,
"bytes": 169227,
"cache_hit": false,
"upstream_requests": 1,
"store": "www.chedraui.com.mx",
"search_api": "catalog",
"total": 1153,
"page": 1,
"page_size": 10,
"has_more": true,
"last_page": 116,
"total_is_exact": true,
"reachable_rows": 1153,
"currency": "MXN",
"sales_channel": null,
"store_default_sales_channel": 1,
"sort": "relevance",
"charged_credits": 3,
"version": "0.1.0",
"request_id": "2dce43c619594070",
"queue_ms": 1.1,
"fetched_at": "2026-10-14T18:57:32.102Z"
},
"data": {
"products": [
{
"product_id": "3855683",
"name": "Leche Bové Leche con Café Orgánica 330ml",
"brand": "Bové",
"brand_id": 813,
"link_text": "leche-bove-leche-con-cafe-organica-330ml-3855683",
"url": "https://www.chedraui.com.mx/leche-bove-leche-con-cafe-organica-330ml-3855683/p",
"product_reference": "3855683",
"category_id": "10501",
"category_path": "Supermercado > Lacteos y huevo > Leche",
"category_path_ids": "/1/105/10501/",
"categories": [
"/Supermercado/Lacteos y huevo/Leche/",
"/Supermercado/Lacteos y huevo/",
"/Supermercado/"
],
"release_date": "2026-08-18T00:00:00Z",
"description": "La combinación perfecta de leche orgánica y café. Las imágenes del producto son únicamente de referencia, el diseño de etiquetas y el contenido (ml, L, Kg, g, piezas, etc) pueden cambiar y/o variar sin previo aviso.",
"specifications": {
"Benefits": "Sabor balanceado y natural.",
"Tipo de producto": "Leche en polvo y saborizada",
"Contenido del empaque": "1 pz de 330ml",
"Fraud Check": "FALSO",
"Tipo de envío": "Restringido",
"Benefits 3": "Hecho con ingredientes orgánicos de alta calidad.",
"Benefits 2": "Energía para comenzar tu día.",
"Identificador Externo de Categoría": "102003006",
"Máximo de venta": "12",
"Descripción, Larga": "Disfruta el mejor café con Leche Bové Leche con Café Orgánica. Encuentra en Chedraui.com.mx una extensa variedad de productos. Recibe tu despensa en casa gracias al servicio a domicilio. Descarga la app.",
"MultiEan": "7501639313538"
},
"clusters": [
{
"id": "[trimmed-depth]",
"name": "[trimmed-depth]"
}
],
"price": 30,
"list_price": 30,
"spot_price": null,
"discount_pct": null,
"currency": "MXN",
"in_stock": true,
"sku_count": 1,
"items": [
{
"sku_id": "[trimmed-depth]",
"name": "[trimmed-depth]",
"name_complete": "[trimmed-depth]",
"ean": "[trimmed-depth]",
"ean_valid": "[trimmed-depth]",
"ref_id": "[trimmed-depth]",
"measurement_unit": "[trimmed-depth]",
"unit_multiplier": "[trimmed-depth]",
"is_kit": "[trimmed-depth]",
"variations": "[trimmed-depth]",
"images": "[trimmed-depth]",
"sellers": "[trimmed-depth]"
}
]
},
{
"product_id": "3396756",
"name": "Leche Condensada Nestlé La Lechera Dulce de Leche 360g",
"brand": "La Lechera",
"brand_id": 3527,
"link_text": "leche-condensada-nestle-la-lechera-dulce-de-leche-360g-3396756",
"url": "https://www.chedraui.com.mx/leche-condensada-nestle-la-lechera-dulce-de-leche-360g-3396756/p",
"product_reference": "3396756",
"category_id": "10501",
"category_path": "Supermercado > Lacteos y huevo > Leche",
"category_path_ids": "/1/105/10501/",
"categories": [
"/Supermercado/Lacteos y huevo/Leche/",
"/Supermercado/Lacteos y huevo/",
"/Supermercado/"
],
"release_date": "2025-08-25T00:00:00Z",
"description": "Disfruta del delicioso sabor de La Lechera Dulce de Leche, elaborado con 100% leche de vaca e ingredientes naturales, dándole un sabor y consistencia inigualables que garantizan momentos dulces para compartir con los tuyos en todo momento. Ya sea que Las imágenes del producto son únicamente de referencia, el diseño de etiquetas y el contenido (ml, L, Kg, g, piezas, etc) pueden cambiar y/o variar sin previo aviso.",
"specifications": {
"Benefits": "Elaborada con ingredientes naturales y 100% leche de vaca.",
"Contenido energético por envase": "323 kcal",
"Azúcares Totales": "57 g",
"Proteínas": "6.10g",
"Carbohidratos / Hidratos de Carbono": "57 g",
"Grasa Total": "7.8 g",
"Tipo de producto": "Otras leches",
"Contenido del empaque": "0.408 kg",
"Fraud Check": "FALSO",
"Presentación": "Bolsa",
"País de Origen": "México",
"Tipo de envío": "Restringido",
"Benefits 3": "Perfecto para preparar tus postres y platillos favoritos añadiendo un toque de la dulzura característico de La Lechera.",
"Benefits 2": "Sabor y consistencia inigualables, gracias a los sólidos de la leche.",
"Identificador Externo de Categoría": "102012002",
"Máximo de venta": "24",
"Descripción, Larga": "Disfruta del delicioso sabor de La Lechera Dulce de Leche, elaborado con 100% ingredientes naturales, dándole un sabor y consistencia inigualables que garantizan momentos dulces para compartir con los tuyos en todo momento Ya sea que estés buscando darle sabor a unos deliciosos hot cakes durante el fin de semana, preparando un postre para celebrar desde las pequeñas cosas hasta los más grandes momentos, o endulzando tu bebida favorita; le dará un toque único a todos tus platillos La presentación en lata es ideal para satisfacer los antojos dulces del día a día y consentir a tu familia con los ",
"MultiEan": "7506475104746-7501058619563",
"Ingredientes": "Leche entera pasteurizada de vaca, azúcares añadidos (azúcar), agar, bicarbonato de sodio y fosfato disódico.",
"Sodio": "165.00mg",
"Tamaño de la Porción": "30 g"
},
"clusters": [
{
"id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"id": "[trimmed-depth]",
"name": "[trimmed-depth]"
}
],
"price": 40.5,
"list_price": 40.5,
"spot_price": null,
"discount_pct": null,
"currency": "MXN",
"in_stock": true,
"sku_count": 1,
"items": [
{
"sku_id": "[trimmed-depth]",
"name": "[trimmed-depth]",
"name_complete": "[trimmed-depth]",
"ean": "[trimmed-depth]",
"ean_valid": "[trimmed-depth]",
"ref_id": "[trimmed-depth]",
"measurement_unit": "[trimmed-depth]",
"unit_multiplier": "[trimmed-depth]",
"is_kit": "[trimmed-depth]",
"variations": "[trimmed-depth]",
"images": "[trimmed-depth]",
"sellers": "[trimmed-depth]"
}
]
},
{
"product_id": "3366707",
"name": "Dona Chocolate de Leche",
"brand": "Panadería",
"brand_id": 4843,
"link_text": "dona-chocolate-de-leche-3366707",
"url": "https://www.chedraui.com.mx/dona-chocolate-de-leche-3366707/p",
"product_reference": "3366707",
"category_id": "10907",
"category_path": "Supermercado > Panaderia y tortilleria > Pan dulce",
"category_path_ids": "/1/109/10907/",
"categories": [
"/Supermercado/Panaderia y tortilleria/Pan dulce/",
"/Supermercado/Panaderia y tortilleria/",
"/Supermercado/"
],
"release_date": "2025-12-03T00:00:00Z",
"description": "Dona cubierta de chocolate con trocitos de chocolate de leche. *Las imágenes del producto son únicamente de referencia, el diseños de etiquetas y el contenido (ml, L, Kg, g, piezas, etc) pueden cambiar y/o variar sin previo aviso.",
"specifications": {
"Benefits": "Pan elaborado al día",
"Tipo de producto": "Pan dulce",
"Contenido del empaque": "1 pz",
"Fraud Check": "FALSO",
"Tipo de envío": "Restringido",
"Benefits 3": "Trozos de chocolate",
"Benefits 2": "1 Pieza",
"Identificador Externo de Categoría": "303007001",
"Máximo de venta": "20",
"Descripción, Larga": "Deliciosa dona cubierta de chocolate y decorada con trocitos de chocolate kinder. Tú repostería favorita a la puerta de tu casa, gran variedad de pan solo en Chedraui.com.mx",
"MultiEan": "2355951000004-2355951-000002355951"
},
"clusters": [],
"price": 21,
"list_price": 21,
"spot_price": null,
"discount_pct": null,
"currency": "MXN",
"in_stock": true,
"sku_count": 1,
"items": [
{
"sku_id": "[trimmed-depth]",
"name": "[trimmed-depth]",
"name_complete": "[trimmed-depth]",
"ean": "[trimmed-depth]",
"ean_valid": "[trimmed-depth]",
"ref_id": "[trimmed-depth]",
"measurement_unit": "[trimmed-depth]",
"unit_multiplier": "[trimmed-depth]",
"is_kit": "[trimmed-depth]",
"variations": "[trimmed-depth]",
"images": "[trimmed-depth]",
"sellers": "[trimmed-depth]"
}
]
}
]
}
}What the VTEX stores API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search or browse any VTEX store's catalog: keyword, category, brand, price range and sort, with every SKU's EAN, each seller's sale/list price, stock flag and the exact total result count. | Pricing teams call search to search or browse any VTEX store's catalog. | store, query, category_id, brand_id, min_price, ... |
| product | Full detail of one VTEX product by product id, slug/URL, SKU id or EAN: every SKU with EAN and variations, every seller's offer (sale, list and pre-discount price, stock, best interest-free instalment), specifications, categories and images. | Marketplace operators call product to get full detail of one VTEX product by product id, slug/URL, SKU id or EAN. | store, product_id, link_text, sku_id, ean, ... |
| products | Up to 50 VTEX products in ONE upstream request, by product ids or by EAN barcodes — same full shape as product, plus the list of ids/EANs the store did not return. | Catalog enrichment teams call products to get up to 50 VTEX products in ONE upstream request, by product ids or by EAN barcodes. | store, product_ids, eans, sales_channel |
| categories | The store's category tree, flattened: id, name, depth, parent, full name path and the id path you pass to search as category_id. | Retail analysts call categories to get the store's category tree, flattened. | store, depth |
| facets | Filter vocabulary and counts for a search term: departments, categories (with ids and counts), brands with counts, price ranges and specification filters. | Pricing teams call facets to get filter vocabulary and counts for a search term. | store, query |
| brands | Every brand registered in the store with its VTEX brand id (the id search accepts as brand_id), optionally filtered by name. | Marketplace operators call brands to get every brand registered in the store with its VTEX brand id (the id search accepts as brand_id…. | store, name_contains, page, limit |
| store_info | Confirms a domain is a VTEX store and returns its currency, locale, country, time zone, default sales channel, total catalog size and which search APIs are open. | Catalog enrichment teams call store_info to get confirms a domain is a VTEX store and. | store, sales_channel |
Call search from your stack
curl -X POST https://api.reefapi.com/vtex/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"store":"www.chedraui.com.mx","query":"leche","page_size":10}'import requests
r = requests.post(
"https://api.reefapi.com/vtex/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"store": "www.chedraui.com.mx",
"query": "leche",
"page_size": 10
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/vtex/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"store": "www.chedraui.com.mx",
"query": "leche",
"page_size": 10
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.vtex.search with {"store":"www.chedraui.com.mx","query":"leche","page_size":10}.Who uses this API and why
- Compare supermarket and pharmacy prices across Mexico, Colombia, Peru, Argentina and Brazil by EAN.
- Track a brand's shelf price, list price and promotions across every VTEX retailer that sells it.
- Monitor stock and sellers of marketplace listings on department-store sites.
- Build a product catalog with EAN, images, specifications and categories from a retailer's own data.
- Map a store's assortment by category and brand with exact product counts.
Questions developers ask before integrating
Which stores does it work with?
Any VTEX store whose public catalog is open. On 2026-10-14 these answered: Chedraui (Mexico), Olímpica and Panamericana (Colombia), Plaza Vea, Promart, Oechsle, Metro and Wong (Peru), Jumbo, Disco, Vea, Carrefour, Farmacity and Día (Argentina), Frávega search (its firewall refused some product lookups), Pague Menos, Zona Sul and Americanas (Brazil). Stores that put a firewall in front of the catalog return a clear error instead of data.
Do I need an account or an API key from the store?
No. Everything is the store's public, logged-out catalog. You only need your reefapi.com key.
How do I know if a site runs on VTEX?
Call store_info with the domain. It answers with the currency, country, locale, default sales channel, the size of the catalog and which search APIs are open, or a not-found error when the domain is not a VTEX store.
Which search filters work?
Keyword, category id, brand id, price range, seven sorts and page. Each was checked against the unfiltered count in the same run: Chedraui 'leche' 1,154 → milk category 427, department 1,041, brand Bové 14, 10 to 50 pesos 597, from 100 pesos 272; Plaza Vea 'arroz' 1,119 → category 33, brand 15, 10 to 50 soles 296. An unknown brand id returns zero results, never the whole catalog.
How deep can I page?
VTEX serves the first 2,550 rows of any one search, 50 per page. When a search matches more, the answer says so and deeper pages are refused rather than billed; narrow the search with a category, brand or price range to reach the rest.
Can I look products up by barcode?
Yes. product accepts an EAN, and products accepts up to 50 EANs or 50 product ids in one call and lists the ones the store did not return.
Are marketplace sellers included?
Yes. Every SKU lists one offer per seller with its own price, list price and stock, and marks the store's default offer. The product-level price uses the default offer, so a placeholder offer with price 0 never becomes the product's price.
Is this the same as the Shopify API?
It is the same idea for a different platform: one API, any store on it. Shopify stores are read with the shopify API; VTEX stores with this one.
What is the VTEX stores API?
VTEX stores API is a ReefAPI endpoint group for any public vtex store in latin america: products, every sku with ean, each seller's sale and list price, stock, categories and brands. It returns live JSON through POST requests under /vtex/v1.
Is the VTEX stores API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. VTEX stores calls use the same shared credit balance as every other ReefAPI engine.
Do I need a VTEX stores login or account?
No login to VTEX stores is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the VTEX stores data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the VTEX stores API use?
VTEX stores actions currently cost 2-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call VTEX stores from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call vtex actions with the same key, credit pool and JSON envelope used by normal REST requests.