Listings API

Resumen rápido

La Listings API permite gestionar listings individuales de forma directa: actualizar precios, cantidades, atributos del producto, etc. Es la opción recomendada para actualizaciones de un solo producto o de pocos productos. Para actualizaciones masivas de muchos productos, usa la Feeds API.

---

Conceptos importantes

• Listing: La oferta de un producto en Amazon. Combina los datos del producto (título, descripción) con los datos de la oferta (precio, cantidad).
• SKU: El identificador interno del vendedor para el producto.
• ASIN: El identificador de Amazon del producto en el catálogo.
• putListingsItem: Operación para crear o actualizar completamente un listing.
• patchListingsItem: Operación para actualizar campos específicos de un listing (parcial).
• deleteListingsItem: Operación para eliminar un listing.
• getListingsItem: Operación para obtener los detalles actuales de un listing.
• productType: El tipo de producto en el sistema de Amazon (ej. SHIRT, ELECTRONICS, BOOK). Define los atributos válidos.
• Issues: Problemas detectados por Amazon en un listing (precios incorrectos, imágenes faltantes, etc.).

---

Cómo funciona

Cuándo usar Listings API vs Feeds API

Situación	Herramienta recomendada
Actualizar 1-10 productos	Listings API (directo, inmediato)
Actualizar 50+ productos	Feeds API (más eficiente en lote)
Crear nuevos listings	Listings API o Feeds API
Cambiar precio de un producto	Listings API (endpoint de precio)

Rate limits de Listings API

Operación	Tasa (req/s)	Burst
getListingsItem	5	10
putListingsItem	5	10
patchListingsItem	5	10
deleteListingsItem	5	10

---

Pasos prácticos

Actualizar el precio de un producto (PATCH)

import requests

def update_listing_price(
    access_token: str,
    endpoint: str,
    seller_id: str,
    marketplace_id: str,
    sku: str,
    new_price: float,
    currency: str = "EUR"
) -> dict:
    headers = {
        "x-amz-access-token": access_token,
        "Content-Type": "application/json",
    }
    params = {
        "marketplaceIds": marketplace_id,
    }
    body = {
        "productType": "PRODUCT",
        "patches": [
            {
                "op": "replace",
                "path": "/attributes/purchasable_offer",
                "value": [
                    {
                        "marketplace_id": marketplace_id,
                        "currency": currency,
                        "our_price": [
                            {
                                "schedule": [
                                    {
                                        "value_with_tax": new_price
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }

    response = requests.patch(
        f"{endpoint}/listings/2021-08-01/items/{seller_id}/{sku}",
        headers=headers,
        params=params,
        json=body,
    )
    response.raise_for_status()
    return response.json()


# Ejemplo de uso
result = update_listing_price(
    access_token=token,
    endpoint="https://sellingpartnerapi-eu.amazon.com",
    seller_id="TU_SELLER_ID",
    marketplace_id="A1RKKUPIHCS9HS",
    sku="MI-SKU-001",
    new_price=24.99,
    currency="EUR"
)
print(result)

Obtener los detalles de un listing

def get_listing(
    access_token: str,
    endpoint: str,
    seller_id: str,
    marketplace_id: str,
    sku: str
) -> dict:
    headers = {"x-amz-access-token": access_token}
    params = {
        "marketplaceIds": marketplace_id,
        "includedData": "summaries,attributes,issues,offers,fulfillmentAvailability",
    }

    response = requests.get(
        f"{endpoint}/listings/2021-08-01/items/{seller_id}/{sku}",
        headers=headers,
        params=params,
    )
    response.raise_for_status()
    return response.json()

Actualizar cantidad de inventario (FBM)

def update_inventory_quantity(
    access_token: str,
    endpoint: str,
    seller_id: str,
    marketplace_id: str,
    sku: str,
    quantity: int
) -> dict:
    headers = {
        "x-amz-access-token": access_token,
        "Content-Type": "application/json",
    }
    params = {"marketplaceIds": marketplace_id}
    body = {
        "productType": "PRODUCT",
        "patches": [
            {
                "op": "replace",
                "path": "/attributes/fulfillment_availability",
                "value": [
                    {
                        "fulfillment_channel_code": "DEFAULT",
                        "quantity": quantity,
                    }
                ]
            }
        ]
    }

    response = requests.patch(
        f"{endpoint}/listings/2021-08-01/items/{seller_id}/{sku}",
        headers=headers,
        params=params,
        json=body,
    )
    response.raise_for_status()
    return response.json()

---

Errores comunes

• Usar el formato de precio incorrecto: La estructura del body para actualizar precios puede ser confusa. El path /attributes/purchasable_offer es el correcto para listings de vendedor.
• No conocer el productType: Para hacer un PUT completo, necesitas conocer el productType exacto (ej. SHIRT, WATCH). Para hacer un PATCH parcial sobre precio o cantidad, "PRODUCT" funciona como genérico.
• Confundir seller_id con app_id: El seller_id en la URL es el ID del vendedor (cuenta de Seller Central), no el ID de tu app.
• Actualizar en el marketplace incorrecto: Debes especificar el marketplaceId correcto. Un listing en amazon.es tiene un SKU diferente al de amazon.de aunque sea el mismo producto físico.
• No verificar Issues: La respuesta de patchListingsItem puede tener éxito (HTTP 200) pero incluir issues que indican problemas en el listing (precio demasiado bajo, fuera de rango, etc.).

---

Qué debo saber antes de programarlo

• Las actualizaciones de precio mediante Listings API tardan menos tiempo en reflejarse que mediante Feeds API (generalmente segundos en lugar de minutos).
• Para actualizaciones de precio en tiempo real (repricing competitivo), Listings API es la opción preferida.
• Si vas a construir un repricer automático que actualice precios cada pocos minutos para muchos productos, considera el impacto en rate limits. Con burst de 10, puedes actualizar 10 productos de golpe y luego esperar.
• La Listings API 2021-08-01 es la versión actual. La versión anterior (v2020-09-01) está siendo deprecada.
• Para crear listings nuevos en marketplaces donde aún no vendes un producto, necesitas conocer el productType y proporcionar todos los atributos obligatorios.

---

Pendiente de revisar

• ¿Cuál es la estructura exacta del body para putListingsItem (creación completa)?
• ¿Cómo se actualizan las imágenes de un listing a través de la API?
• ¿Qué productTypes están disponibles y cómo obtener los atributos requeridos para cada uno?