DEV Community: Ricardo Cuba

VTEX, Magento, and Retail APIs — A Developer's Guide to Commerce Data

Ricardo Cuba — Wed, 24 Jun 2026 00:12:58 +0000

What we learned integrating 41 LATAM retailers — and how you can do it without losing your mind.

If you've ever tried to integrate a VTEX or Magento store's API, you know the drill: read the docs (which may or may not be current), get an API key (which may or may not work), figure out the product schema (which is different for every store), handle rate limits (undocumented), and pray nothing breaks when the retailer updates their frontend next week.

We've done this 41 times. Here's what we learned.

VTEX: The Good, The Bad, and The API

VTEX powers most major retailers in LATAM — Wong, Metro, Plaza Vea, Carrefour, Éxito, and dozens more. It has a well-documented REST API.

What works

Search API (/api/catalog_system/pub/products/search) — reliable, structured product data
Pagination — cursor-based, predictable
Product details — consistent schema for price, name, description

What doesn't

Auth varies by store — some use X-VTEX-API-AppKey + token, others custom headers
Rate limits are undisclosed — you discover them by getting 429'd
Product IDs are not globally unique — same SKU, different IDs across stores
Image URLs expire — cached URLs break after hours/days

Code: querying VTEX search

python
import httpx

async def search_vtex(domain: str, query: str, key: str, token: str):
    url = f"https://{domain}/api/catalog_system/pub/products/search/{query}"
    headers = {"X-VTEX-API-AppKey": key, "X-VTEX-API-AppToken": token}
    async with httpx.AsyncClient() as client:
        resp = await client.get(url, headers=headers, timeout=30)
        return resp.json()

Magento: GraphQL When It Works

Magento stores expose a GraphQL endpoint. Flexible in theory, fragmented in practice:

Pros: GraphQL introspection, single endpoint, field selection.
Cons: Version fragmentation (2.3 vs 2.4), OAuth 2.0 complexity, some stores disable introspection, nested pricing (price_range.minimum_price.regular_price.value — yes, that's a real path).

The normalization problem

The hardest part isn't querying 41 APIs. It's normalizing the results:

"1kg arroz" ≠ "arroz 1000g" ≠ "arroz x1kg" ≠ "Arroz Extra 1Kg"

Our normalizer handles unit conversion (kg/g/lb/oz/L/mL), fuzzy product matching across Spanish/Portuguese/English, brand extraction, and always returns price_per_kg.

Error handling across 41 stores

When you query 41 stores, something is always broken:

Failure mode Frequency Our handling

Timeout (>30s) ~5% Retry 3x with exponential backoff

429 Rate Limit ~3% Queue and retry after Retry-After

503/502 Error ~2% Skip store, log, retry next cycle

Schema change ~1%/week Alert → manual fix → update collector

Auth expired ~1%/month Rotate tokens, alert ops

Failure mode	Frequency	Our handling
Timeout (>30s)	~5%	Retry 3x with exponential backoff
429 Rate Limit	~3%	Queue and retry after Retry-After
503/502 Error	~2%	Skip store, log, retry next cycle
Schema change	~1%/week	Alert → manual fix → update collector
Auth expired	~1%/month	Rotate tokens, alert ops

The collector runs every 4 hours. Even with 5% failure rate, 95% of data is fresh. 7-day coverage: 100%.

What we'd do differently

Start with GraphQL introspection — saves hours of doc-reading for Magento
Build the normalizer first — collection is easy, normalization is hard
Assume auth will break — build token rotation from day 1
Log everything — when a retailer changes their schema at 3am, you want logs
One async HTTP client, many stores — httpx.AsyncClient with connection pooling

Self-serve retailer onboarding (coming soon)

We're building a flow where retailers register their VTEX/Magento store and appear in CLI Market searches within 24 hours. No technical integration — just your domain and API credentials.

If you run a VTEX or Magento store in LATAM: cli-market.dev/retailers

CLI Market — Commerce infrastructure for AI agents. 41 retailers. 8 countries. One API.

Your AI agent can now call market_search, market_compare, market_basket autonomously. No human in the loop for search + compare. What would you build on top of that? Procurement bot? Price alert system? Basket optimizer? Drop your idea 👇

Ricardo Cuba — Wed, 17 Jun 2026 17:10:53 +0000

Why AI agents can't shop today — and what we're building to change that

Ricardo Cuba — Tue, 16 Jun 2026 23:00:45 +0000

AI agents are getting smarter every week. They can browse the web, write code, analyze data. But there's a glaring gap in their capabilities: they can't interact with real commerce.

Ask your favorite AI agent "what's the cheapest 5kg bag of rice I can buy in Lima right now?" and watch it struggle. It doesn't have access to real-time retail prices. It doesn't know which stores carry rice. It can't compare prices, let alone complete a purchase.

This isn't a model capability problem. It's an infrastructure problem.

The commerce fragmentation problem

E-commerce today is 38 different APIs wearing 38 different costumes. Each one has different authentication, product schemas, rate limits, pagination, and error handling.

What Stripe did for payments, CLI Market does for commerce data

One API → 38 retailers across 8 countries
One auth token → instead of 38
Normalized data → price_per_kg, not raw retailer strings
Structured for agents → JSON output, 22 curated MCP tools, CLI-first

Current scale (June 2026)

Metric -> Value

Retailers indexed -> 38
Countries -> PE, AR, BR, MX, CO, CL, IT, FR
Prices indexed -> 53,000+
Refresh rate -> Every 4 hours
7-day coverage -> 100%
MCP tools -> 22 curated (46 legacy)

Get started

pip install cli-market-world
market login
market search "rice" --country PE --json

MCP tools:
[https://cli-market.dev/tools?utm_source=devto&utm_campaign=art1]

Your AI Agent Can't Buy What It Can't See

Ricardo Cuba — Sat, 13 Jun 2026 18:43:38 +0000

Most retailers are still optimizing for humans.

Better websites.
Better mobile apps.
Better UX.

But there's a problem.

The next billion purchasing decisions won't be made by humans.

They'll be made by agents.

An AI agent doesn't browse websites.
It doesn't compare products across 20 tabs.
It doesn't scroll endlessly through e-commerce catalogs.

It consumes structured data.

Today, retail pricing data is fragmented across hundreds of retailers, formats, and countries.

That's why we built CLI Market.

A simple terminal interface that transforms retail pricing data into machine-readable intelligence.

market search "arroz" --country PE --json

A few seconds later:

{
  "retailers": 12,
  "prices_found": 248,
  "country": "PE"
}

No scraping.
No browser automation.
No manual comparison.

Just real retail prices delivered in a format your agents can use immediately.

We're building infrastructure for a world where:

→ AI agents negotiate purchases
→ Autonomous systems optimize procurement
→ Applications make real-time buying decisions
→ Retail becomes machine-accessible

The internet was built for humans.

The next layer will be built for agents.

CLI Market is helping bridge that gap.

pip install cli-market-world

From shelf to data.
From data to decisions.
From decisions to autonomous commerce.

#AI #Agents #RetailTech #DeveloperTools #MachineReadableWeb #CLI #ArtificialIntelligence #DataInfrastructure #AgenticAI #Retail

Add Commerce to Your AI Agent in 4 Lines

Ricardo Cuba — Wed, 10 Jun 2026 19:48:43 +0000

4 commands. 38 retailers. 8 countries. Your agent just learned how to shop.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The problem
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

You're building an AI agent. It can search the web, reason about complex topics, generate code. But when it needs to answer a simple question like "how much does rice cost in Lima today?" — it hits a wall.

Not because it's dumb. Because every retailer has a different API, auth mechanism, schema, and checkout flow. There's no Stripe for commerce data.

Until now.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4 lines. That's it.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

'''bash
# 1. Install
pip install cli-market-world

# 2. Guided first search + interactive tutorial
market init           # login + first query
market tutorial       # 3 exercises: search, compare, export — 60 seconds

# 3. Search — your agent just queried 38 retailers in <1s
market search "leche" --country PE --json

# 4. Connect to your AI agent via MCP
# Add to Cursor / Claude / any MCP client:
# → https://cli-market.dev/tools?utm_source=devto&utm_campaign=spike-jun09
'''

That's the entire integration. No API keys per retailer. No HTML scraping. No schema mapping.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What happens under the hood
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When your agent runs market search "rice" --country PE --json, CLI Market:

Normalizes the query — "arroz", "rice", "arroz blanco" all map to the same product
Queries our collector — 38 active retailers, refreshed every 4 hours
Returns structured JSON — price per kg/L, store name, country, timestamp
Handles auth — one CLI Market token, not 38 retailer tokens

What it looks like in your terminal:

![CLI Market terminal output — 60 seconds, real prices]

'''json
{
  "query": "arroz",
  "country": "PE",
  "results": [
    {
      "product": "Arroz Extra 5kg",
      "price": 18.90,
      "price_per_kg": 3.78,
      "store": "Wong",
      "country": "PE",
      "refreshed_at": "2026-06-10T08:00:00Z"
    }
  ]
}
'''

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MCP: the missing piece
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CLI Market exposes 22 curated MCP tools (46 legacy) — search, compare, basket, checkout paths — so your agent can:

Search products across all retailers
Compare prices between stores
Filter by country, category, or price range
Get historical price data (Pro tier)

Connect in Cursor or any MCP client in 30 seconds. Configuration at cli-market.dev/tools.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What you can build with this
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Price monitoring agents — track commodity prices across LATAM
Shopping assistants — "find the cheapest 5kg rice in Lima"
Competitive intelligence — benchmark your retail prices against the market
Supply chain optimization — auto-reorder when prices drop below threshold

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What's next
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

We're working on cart + checkout — so your agent doesn't just search, it buys. One API call to add to cart across any supported retailer.

Start building:

'''bash
pip install cli-market-world
market init
'''

**MCP tools:** [cli-market.dev/tools](https://cli-market.dev/tools?utm_source=devto&utm_campaign=spike-jun09)

**Docs for agents:** [cli-market.dev/llms.txt](https://cli-market.dev/llms.txt)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pricing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Tier | Price | Best for |
|------|-------|----------|
| Free | $0 | 1,000 req/day — prototype with `market init` |
| **Pro** | **$39/mo** | Alerts, full MCP tools, checkout, 20k req/day, 30d history — [activate](https://cli-market.dev//#pricing?utm_source=devto&utm_campaign=week2) |

CLI Market — Commerce infrastructure for AI agents. 38 retailers. 8 countries. MIT on PyPI.

Add Commerce to Your AI Agent in 4 Lines

Ricardo Cuba — Tue, 09 Jun 2026 15:05:42 +0000

4 commands. 38 retailers. 8 countries. Your agent just learned how to shop.

The problem

Not because it's dumb. Because every retailer has a different API, auth mechanism, schema, and checkout flow. There's no Stripe for commerce data.

Until now.

4 lines. That's it.

# 1. Install
pip install cli-market-world

# 2. Guided first search + interactive tutorial
market init           # login + first query
market tutorial       # 3 exercises: search, compare, export — 60 seconds

# 3. Search — your agent just queried 38 retailers in <1s
market search "leche" --country PE --json

# 4. Connect to your AI agent via MCP
# Add to Cursor / Codex/ Claude / any MCP client:
# → https://cli-market.dev/tools?utm_source=devto&utm_campaign=spike-jun10

That's the entire integration. No API keys per retailer. No HTML scraping. No schema mapping.

What happens under the hood

When your agent runs market search "rice" --country PE --json, CLI Market:

Normalizes the query — "arroz", "rice", "arroz blanco" all map to the same product
Queries our collector — 38 active retailers, refreshed every 4 hours
Returns structured JSON — price per kg/L, store name, country, timestamp
Handles auth — one CLI Market token, not 38 retailer tokens.

What it looks like in your terminal:

CLI Market terminal output — 60 seconds, real prices

  {
    "query": "arroz",
    "country": "PE",
    "results": [
      {
        "product": "Arroz Extra 5kg",
        "price": 18.90,
        "price_per_kg": 3.78,
        "store": "Wong",
        "country": "PE",
        "refreshed_at": "2026-06-10T08:00:00Z"
      }
    ]
  }

MCP: the missing piece

CLI Market exposes 22 curated MCP tools (46 legacy) — search, compare, basket, checkout paths — so your agent can:

Search products across all retailers
Compare prices between stores
Filter by country, category, or price range
Get historical price data (Pro tier)

Connect in Cursor or any MCP client in 30 seconds.
Configuration at:
https://cli-market.dev/tools?utm_source=devto&utm_campaign=spike-jun10.

What you can build with this

Price monitoring agents — track commodity prices across LATAM
Shopping assistants — "find the cheapest 5kg rice in Lima"
Competitive intelligence — benchmark your retail prices against the market
Supply chain optimization — auto-reorder when prices drop below threshold

What's next

We're working on cart + checkout — so your agent doesn't just search, it buys. One API call to add to cart across any supported retailer.

Start building:

  pip install cli-market-world
  market init

MCP tools:
https://cli-market.dev/tools?utm_source=devto&utm_campaign=spike-jun10

Docs for agents:
https://cli-market.dev/llms.txt

Pricing:
https://cli-market.dev/#pro-checkout?utm_source=devto&utm_campaign=week2

*CLI Market — Commerce infrastructure for AI agents. 38 retailers. 8 countries. MIT on PyPI.
*

CLI Market — Mi agente compra en 36 tiendas de 11 países. Una sola API.

Ricardo Cuba — Thu, 28 May 2026 14:41:41 +0000

Los agentes de IA no pueden comparar precios en el retail físico. Cada tienda tiene su propio sistema de autenticación, lógica de búsqueda y flujo de compra. Los agentes fallan antes de la primera consulta.

CLI Market resuelve esto: un solo pip install, una API unificada para 36 retailers verificados en 11 países. 43 herramientas MCP. Más de 45.000 precios reales actualizados cada 4 horas. Checkout por PayPal (API) o QR (Yape/Plin).

🇬🇧 AI agents can't comparison-shop in physical retail. Every store has its own auth, search logic, and checkout flow. **CLI Market* fixes this: one pip install, one API across 36 verified retailers in 11 countries. 43 MCP tools. 45,000+ real prices refreshed every 4 hours.*

Cómo funciona

Buscar

market search "leche" --country PE
# → precios de Metro, Wong, Plaza Vea en <2s

Comparar

market basket leche:2 arroz:1
# → compara el carrito completo en 9 supermercados

Pagar

market checkout --payment yape
# → genera QR, confirma vía webhook

🇬🇧 How it works — Search: get prices from multiple retailers in <2s. Compare: full cart comparison across 9 supermarkets. Checkout: generates QR code, confirms via webhook.

Por qué lo construí

El cuello de botella para los agentes de compras con IA no es el LLM — es la capa de datos de comercio. Cada agente que construí necesitaba scrapear 36 sitios web solo para responder "¿dónde está la leche más barata cerca de mí?"

El proyecto comenzó como un conector VTEX y creció hasta cubrir 36 retailers en Perú, Argentina, Brasil, México, Colombia, Chile, EE.UU. y más. Tenemos conectores VTEX, Shopify y Magento corriendo un daemon colector cada 4 horas. ~45K precios indexados actualmente, creciendo a más de 200K con descargas de catálogo completo.

También estamos trabajando en un archivo histórico de precios de 90 días para seguimiento de inflación.

🇬🇧 The bottleneck for AI shopping agents isn't t LM — it's the commerce data layer. Started as a single VTEX connector, now covering 36 retailers across 11 countries. Working on 200K+ prices and a 90-day historical price archive for inflation tracking.

Abierto a todos

Construido en Python. Licencia MIT. Los retailers pueden listarse gratis — si tenés una tienda en Shopify o Magento, solo necesitamos un token de API de solo lectura. Sin lock-in.

📦 Repositorio: https://github.com/Treevu-ai/cli-market-world
🌐 Demo: https://cli-market.dev (GIF de terminal de 60s mostrando un checkout completo con agente)

¡Me encantaría recibir feedback de quienes estén construyendo agentes de IA o trabajando en infraestructura de retail!

🇬🇧 Built in Python. MIT licensed. Retailers can list for free — Shopify or Magento store, read-only API token is all we need. No lock-in. Would love feedback from anyone building AI agents or working on retail infrastructure!

Shipping an MCP server: parallel search, JSON output, and what broke along the way

Ricardo Cuba — Thu, 21 May 2026 01:57:06 +0000

CLI Market hit 3,760 retailers this week. With that scale came problems.

Here's what we fixed and what we learned.

[Problem 1: Search timeout][...]

[Problem 2: --json flag that didn't work][...]

[Problem 3: Session loss on cloud deploys][...]

[What we learned about Render vs Railway][...]

[Full changelog + code links]

pip install cli-market
github.com/Treevu-ai/cli-market-world

How I registered an MCP server for 3,760 retailers — and what I learned

Ricardo Cuba — Wed, 20 May 2026 00:08:56 +0000

Yesterday CLI Market was a PyPI package.
This week it's an official MCP Registry server:

Here's what it took to get listed, what the registry validation looks like, and why MCP is the missing layer between e-commerce and AI agents.

The MCP Registry: what it took to get listed

**
The Model Context Protocol Registry at registry.modelcontextprotocol.io is the canonical
directory of MCP servers. Getting listed isn't just about having a working server — the registry validates ownership, checks schema compliance, and verifies that the package actually exists.

*Step 1: The mcp.json file
*
Every MCP server needs a mcp.json at the repo root. Ours:
{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json" , "name": "io.github.Treevu-ai/cli-market", "title": "CLI Market", "version": "1.0.1", "description": "12 MCP tools for search, compare, purchase across 3,760 retailers in 67 c ountries", "repository": { "url": "https://github.com/Treevu-ai/cli-market-world", "source": "github" }, "packages": [{ "registryType": "pypi", "identifier": "cli-market", "version": "1.0.17", "transport": { "type": "stdio" } }] }

Key decisions:

Name format: io.github.{org}/{project} — reverse-DNS, org-scoped
registryType: pypi — CLI Market is a Python package on PyPI
transport: stdio — the MCP server communicates over standard input/output
version locked — no ranges, exact version matching

*Step 2: Proving ownership
*
The registry doesn't trust that cli-market on PyPI belongs to Treevu-ai on GitHub. It validates by scanning the PyPI package README for a specific HTML comment:

<!-- mcp-name: io.github.Treevu-ai/cli-market -->

This line must appear in the README that renders on PyPI. The registry fetches the package, parses the README, and checks that the annotation matches the server name. If it doesn't match — rejected.

We added this to our README, bumped the version to 1.0.17, and uploaded to PyPI. The registry validated it in under a second.

*Step 3: Schema validation
*
The publish endpoint runs the full ServerJSON schema validator. Every field is checked:

description max 100 characters, name must match ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$,
packages[].identifier must resolve in the registry, packages[].transport.type must be stdio/
streamable-http/sse.

One thing that tripped us up: the schema changed between mcp.json (the repo-side format) and ServerJSON (the registry API format). In the repo, you declare command, args, type. In the registry API, those go inside packages[].transport and packages[] requires registryType + identifier + transport. Getting this right took a few rounds.

*Step 4: Authentication
*
The registry uses GitHub OAuth. We exchanged a GitHub token for a registry JWT:
POST /v0.1/auth/github-at → { registry_token: "eyJ..." }

Then published:
POST /v0.1/publish → { server: {...}, _meta: { status: "active" } }

The token expires, so for updates you re-authenticate. The whole flow is scriptable in under 10 lines of bash.

The 12 tools: architecture

All 12 tools sit on top of a unified VTEX connector that normalizes 3,760 retailer APIs into a single JSON schema.

_Four tools deserve special attention:
_

- market_compare — Not a simple price fetch. It first normalizes SKUs across retailers (the same product has different internal IDs at Carrefour Brazil and Sainsbury's UK), deduplicates, and returns a canonical price set. Three steps under one MCP call.
market_checkout — Chains: cart validation → stock verification → payment method resolution → order confirmation. All in one invocation. But it never completes autonomously — V1 requires explicit human approval before execution.
market_ask — The most composite tool. Natural language input → semantic search → cross-retailer comparison → cart building → checkout readiness. "Buy rice" walks the full pipeline.

The composition pattern — Tools are atomic enough to compose, composite enough to not drown the agent. 12 tools. Not 1 mega-tool. Not 100 individual REST endpoints.

───

What I'd do differently

Read the OpenAPI spec first. The publish endpoint schema is documented at /docs. I guessed from the mcp.json format and hit 5 validation errors before getting it right.
Set up the PyPI annotation early. The mcp-name comment is the ownership proof. Add it to your README before you publish to the registry.
Script the auth flow. GitHub token → registry JWT → publish. Three curl calls. Wrap them in a Makefile target and forget about it.

───

CLI Market is on the registry.
The agent can now search, compare, and buy across 3,760 retailers in 67 countries — all via structured tool calls with zero scraping.

pip install cli-market
io.github.Treevu-ai/cli-market
github.com/Treevu-ai/cli-market-world

Ricardo Cuba
Founder & Product Lead | CLI Market
CEO Sinapsis Innovadora
Trujillo, Perú

The VTEX public API is the same for 3,760 retailers — but no one aggregated it. Until now.

Ricardo Cuba — Tue, 19 May 2026 01:15:27 +0000

VTEX runs e-commerce for Nike, Carrefour, Samsung, Motorola, and 3,760+ other brands. Every one exposes the same search and catalog API endpoints. Same JSON schema. Same pagination rules.

For years, if you wanted to query products across retailers, you had to scrape or make separate API calls per store. There was no aggregation layer.

VTEX powers e-commerce for Nike, Carrefour, Samsung, and 3,760+ brands.
All share the same public API — but no one had built the aggregation layer for programmatic access. Until now.

pip install cli-market and your terminal becomes a commerce engine across 67 countries.

So I built one.
gifsicle --optimize=3 --lossy=80 demo.gif -o demo-small.gif

Technical details:

Single Python connector that maps VTEX's public search/catalog/checkout endpoints
Each retailer = one config line: {domain, country, currency, line}
SQLite price snapshots for historical data
Rich terminal UI + REST API + MCP server (12 tools)
JSON output saves ~85% context window tokens vs raw HTML

Everything is indexed and queryable cross-retailer. Search "milk" and get results from Carrefour Brazil, Sainsbury's UK, Wong Peru, in one response.

GitHub: https://github.com/Treevu-ai/cli-market-world
Live: https://cli-market.dev

Stack: Python, FastAPI, Rich, SQLite, Next.js. MIT license.

Curious what the community thinks about e-commerce APIs being still optimized for browsers instead of programmatic access.

Conecta tus agentes de IA a +2000 retailers de LATAM con una sola API

Ricardo Cuba — Mon, 18 May 2026 04:14:09 +0000

En este post te presento CLI Market, una infraestructura de comercio open source que conecta 100 retailers en 12 países de LATAM a través de una sola API y una CLI para agentes de IA.

¿Qué es CLI Market?
CLI Market unifica catálogos, precios y disponibilidad de múltiples retailers para que tus agentes de IA puedan buscar, comparar y simular compras sin integrar tienda por tienda.

2000+ retailers conectados
40+ países en el mundo
Una API y una CLI open source

👉 Sitio: https://cli-market.dev/
👉 Repo: https://github.com/Treevu-ai/cli-market-world

Cómo empezar?

git clone https://github.com/Treevu-ai/cli-market-latam.git
cd cli-market-latam
npm install
npm run cli

Ejemplo rápido para listar retailers por país:

cli-market retailers list --country=PE

Con esto ya puedes exponer catálogos como herramientas para tus agentes (HTTP, JSON, MCP) y construir asistentes que optimicen compras en retail sobre una sola capa de infraestructura.

first create post dev test

Ricardo Cuba — Mon, 11 May 2026 02:41:34 +0000

One of the most powerful things I've learned a few days ago is the possibilities to vibe coding from ubuntu and docker containers