Catalog Items API

Resumen rápido

La Catalog Items API permite buscar y obtener información detallada sobre cualquier producto en el catálogo de Amazon, tanto los tuyos como los de otros vendedores. Puedes buscar por ASIN, keyword, SKU, nombre de marca o ID de clasificación. Es útil para monitorización de competencia, investigación de productos y enriquecer datos de tu catálogo.

---

Conceptos importantes

• SearchCatalogItems: Operación de búsqueda. Devuelve hasta 20 productos por petición. Búsqueda por keywords, identificadores, SKU, marca, etc.
• GetCatalogItem: Obtiene los detalles de un producto específico por su ASIN.
• ASIN (Amazon Standard Identification Number): El identificador único de cada producto en Amazon.
• includedData: Parámetro que especifica qué datos quieres recibir (atributos, imágenes, clasificaciones, resumen, variaciones, etc.).
• Identifiers: Los identificadores del producto. Pueden ser ASIN, EAN, ISBN, UPC, etc.
• Classifications: La categoría del producto en la taxonomía de Amazon.
• Offers: Información sobre las ofertas del producto (precios, vendedores, buybox).
• BuyBox: La caja de compra destacada en la página de producto. El vendedor que la tiene suele llevarse la mayoría de las ventas.

---

Cómo funciona

Rate limits de Catalog Items API

Operación	Tasa (req/s)	Burst
SearchCatalogItems	2 items/s	5
GetCatalogItem	2 items/s	2

Truco de optimización: SearchCatalogItems devuelve hasta 20 items por llamada, lo que equivale a 40 items/segundo de throughput efectivo. GetCatalogItem solo devuelve 1 item por llamada (2 items/segundo). Usa SearchCatalogItems siempre que sea posible para ser más eficiente.

Tipos de búsqueda disponibles

Método	Parámetro	Ejemplo
Por keyword	keywords	"silla ergonómica"
Por ASIN	identifiers + identifiersType=ASIN	"B08XXXXXX"
Por EAN/UPC	identifiers + identifiersType=EAN	"8421206140456"
Por SKU del vendedor	sellerId + identifiers (SKU)	Tu propio SKU
Por nombre de marca	brandNames	"Samsung"
Por categoría	classificationIds	ID de clasificación

---

Pasos prácticos

Búsqueda por keyword con paginación (Python)

import requests

def search_catalog_items(
    access_token: str,
    endpoint: str,
    marketplace_id: str,
    keyword: str,
    max_items: int = 100
) -> list:
    """Busca productos por keyword con paginación."""
    headers = {"x-amz-access-token": access_token}
    params = {
        "marketplaceIds": marketplace_id,
        "keywords": keyword,
        "pageSize": 20,
        "includedData": "summaries,identifiers",
    }

    all_items = []
    next_token = None

    while len(all_items) < max_items:
        if next_token:
            params["pageToken"] = next_token

        response = requests.get(
            f"{endpoint}/catalog/2022-04-01/items",
            headers=headers,
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        all_items.extend(data.get("items", []))
        next_token = data.get("pagination", {}).get("nextToken")

        if not next_token:
            break

    return all_items

Obtener detalles de un ASIN específico

def get_catalog_item(
    access_token: str,
    endpoint: str,
    marketplace_id: str,
    asin: str
) -> dict:
    headers = {"x-amz-access-token": access_token}
    params = {
        "marketplaceIds": marketplace_id,
        "includedData": "summaries,attributes,images,offers",
    }

    response = requests.get(
        f"{endpoint}/catalog/2022-04-01/items/{asin}",
        headers=headers,
        params=params,
    )
    response.raise_for_status()
    return response.json()

Ejemplo de respuesta (GetCatalogItem)

{
  "asin": "B08XXXXXX",
  "summaries": [
    {
      "marketplaceId": "A1RKKUPIHCS9HS",
      "brandName": "Samsung",
      "itemName": "Samsung Galaxy...",
      "color": "Negro",
      "manufacturer": "Samsung Electronics",
      "modelNumber": "SM-XXXX"
    }
  ],
  "offers": [
    {
      "marketplaceId": "A1RKKUPIHCS9HS",
      "offerType": "B2C",
      "listingPrice": {
        "amount": 299.99,
        "currencyCode": "EUR"
      },
      "isBuyBoxWinner": true,
      "sellerId": "A3P5ROKL5A1OLE",
      "feedbackCount": 1542,
      "feedbackRating": 4.7
    }
  ]
}

---

Errores comunes

• No incluir marketplaceIds obligatorio: Todas las operaciones de esta API requieren el marketplace. Sin él, dará error.
• Pedir demasiados includedData: Cuantos más datos pides, más lenta es la respuesta y más información irrelevante procesas. Pide solo lo que necesitas.
• Usar GetCatalogItem para buscar en lote: Es ineficiente. Si tienes 100 ASINs, usa SearchCatalogItems con identifiers para buscar varios a la vez (hasta 20 por petición).
• Confundir las versiones de la API: Hay al menos dos versiones activas de Catalog Items API (v0 y 2022-04-01). Usa la versión 2022-04-01 para nuevos proyectos.

---

Qué debo saber antes de programarlo

• Esta API es ideal para monitorización de competencia: obtén los precios actuales y los vendedores en el buybox de un ASIN.
• Los datos de offers (precios y buybox) no requieren PII y son datos públicos del marketplace.
• Puedes obtener el sellerId de los competidores a través de los offers, lo que es útil para ciertos análisis.
• El campo images en includedData devuelve las URLs de las imágenes del producto.
• Para tus propios productos, puedes buscar por sellerId + SKU para comprobar que están bien indexados.
• Esta API es la base para construir herramientas de tipo Jungle Scout o Helium 10 (aunque las apps comerciales tienen sus propios algoritmos sobre los datos).

---

Pendiente de revisar

• ¿Qué versión de la API está activa como principal en 2026?
• ¿Hay límite de ASINs por petición en SearchCatalogItems usando identifiers?
• ¿Se pueden buscar productos de un marketplace en otro (cross-marketplace)?