Orders API

Resumen rápido

La Orders API permite obtener todos los pedidos de una cuenta de vendedor con filtros por fecha, estado, marketplace, etc. Es una de las APIs más usadas. Devuelve hasta 100 pedidos por página; si hay más, usa el NextToken para paginar. Si vendes FBM y necesitas la dirección de envío completa, necesitas acceso PII.

---

Conceptos importantes

• GetOrders: Operación principal. Devuelve una lista de pedidos filtrados por parámetros.
• GetOrder: Operación para obtener los detalles de un pedido específico por su AmazonOrderId.
• GetOrderItems: Operación para obtener los artículos de un pedido concreto.
• NextToken: Token de paginación. Si hay más de 100 pedidos, la respuesta incluye un NextToken que debes usar en la siguiente petición para obtener la siguiente página.
• AmazonOrderId: El identificador único de cada pedido en Amazon (ej: 114-3734687-1234567).
• OrderStatus: Estado del pedido. Los más comunes: Pending, Unshipped, PartiallyShipped, Shipped, Canceled, Unfulfillable.
• CreatedAfter / CreatedBefore: Parámetros de fecha en formato ISO 8601 para filtrar pedidos.
• MarketplaceIds: Array con los IDs de los marketplaces de los que quieres obtener pedidos.

---

Cómo funciona

Rate limits de Orders API

Operación	Tasa (req/s)	Burst
GetOrders	0.0167 (1/min)	20
GetOrder	0.5	30
GetOrderItems	0.5	30

Importante: Si tu app hace muchas peticiones, Amazon puede aumentar automáticamente tu límite (hasta 3x en cuentas con alto volumen). Consulta siempre el header x-amz-rate-limit en la respuesta para saber tu límite actual.

Estructura de la respuesta de GetOrders

{
  "payload": {
    "Orders": [
      {
        "AmazonOrderId": "114-3734687-1234567",
        "PurchaseDate": "2024-01-15T10:30:00Z",
        "LastUpdateDate": "2024-01-15T11:00:00Z",
        "OrderStatus": "Shipped",
        "FulfillmentChannel": "AFN",
        "MarketplaceId": "A1RKKUPIHCS9HS",
        "OrderTotal": {
          "CurrencyCode": "EUR",
          "Amount": "29.99"
        },
        "NumberOfItemsShipped": 1,
        "NumberOfItemsUnshipped": 0,
        "PaymentMethod": "Other",
        "ShipmentServiceLevelCategory": "Standard",
        "OrderType": "StandardOrder",
        "BuyerInfo": {
          "BuyerEmail": "hash@marketplace.amazon.com"
        },
        "ShippingAddress": {
          "StateOrRegion": "Madrid",
          "PostalCode": "28001",
          "City": "Madrid",
          "CountryCode": "ES"
        }
      }
    ],
    "NextToken": "XXXXXXXXXX"
  }
}

Nota: El email del comprador siempre está hasheado. Con acceso PII y FBM, ShippingAddress incluye nombre y dirección completa.

---

Pasos prácticos

Obtener pedidos de los últimos 30 días (Python)

import requests
from datetime import datetime, timedelta
from urllib.parse import urlencode

def get_orders(access_token: str, endpoint: str, marketplace_id: str) -> list:
    """Obtiene todos los pedidos de los últimos 30 días con paginación."""
    created_after = (datetime.utcnow() - timedelta(days=30)).strftime("%Y-%m-%dT%H:%M:%SZ")

    headers = {
        "x-amz-access-token": access_token,
        "Content-Type": "application/json",
    }
    params = {
        "MarketplaceIds": marketplace_id,
        "CreatedAfter": created_after,
    }

    all_orders = []
    next_token = None

    while True:
        if next_token:
            params["NextToken"] = next_token

        response = requests.get(
            f"{endpoint}/orders/v0/orders",
            headers=headers,
            params=params,
        )
        response.raise_for_status()
        data = response.json()["payload"]

        all_orders.extend(data.get("Orders", []))
        next_token = data.get("NextToken")

        if not next_token:
            break

    return all_orders

Obtener detalles de un pedido específico

def get_order(access_token: str, endpoint: str, order_id: str) -> dict:
    headers = {"x-amz-access-token": access_token}
    response = requests.get(
        f"{endpoint}/orders/v0/orders/{order_id}",
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["payload"]

Obtener artículos de un pedido

def get_order_items(access_token: str, endpoint: str, order_id: str) -> list:
    headers = {"x-amz-access-token": access_token}
    response = requests.get(
        f"{endpoint}/orders/v0/orders/{order_id}/orderItems",
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["payload"]["OrderItems"]

---

Errores comunes

• Exceder el rate limit: Con burst de 20, puedes hacer 20 peticiones de golpe y luego tienes que esperar ~60 segundos (o ~22 segundos si Amazon te ha dado un límite mayor). Implementa un rate limiter. Ver 12-rate-limits-y-throttling.md.
• Olvidar la paginación: Si tienes más de 100 pedidos, la primera respuesta solo trae los primeros 100. Siempre comprueba si hay NextToken.
• Filtros de fecha incorrectos: Las fechas deben estar en formato ISO 8601 con zona horaria UTC.
• Usar GetOrder para iterar todos los pedidos: Es ineficiente y consume más rate limit. Usa GetOrders para obtener todos y GetOrder solo cuando necesites un pedido específico.

---

Qué debo saber antes de programarlo

Dos formas de obtener datos de pedidos

Hay dos enfoques distintos y cada uno tiene sus ventajas:

Enfoque	Cuándo usarlo	Ventajas	Inconvenientes
Orders API (GetOrders)	Cuando necesitas datos en tiempo real, histórico completo, o PII	Control total, datos históricos ilimitados	Consume más rate limit, código más complejo
Reports API (Order Report)	Cuando necesitas datos periódicos (diario, semanal)	Eficiente, pocos llamadas	No es tiempo real, periodicidad limitada

Para apps optimizadas, combina: usa Reports API para datos históricos y Notifications API para nuevos pedidos en tiempo real. Ver 08-reports-api.md y 09-notifications-api.md.

Respecto a los datos disponibles

• FulfillmentChannel: AFN = FBA (Amazon gestiona el envío), MFN = FBM (vendedor gestiona el envío).
• BuyerEmail: Siempre hasheado. No puedes contactar al comprador directamente.
• ShippingAddress: Con FBA, dirección parcial. Con FBM y PII, dirección completa.
• Las órdenes históricas están disponibles sin límite de tiempo. Puedes recuperar pedidos de hace años.

---

Pendiente de revisar

• ¿Cuál es el límite máximo de días en un filtro de CreatedAfter / CreatedBefore?
• ¿Qué pasa con los pedidos de B2B (ventas a empresas)? ¿Tienen campos distintos?
• Verificar si GetOrderBuyerInfo sigue siendo un endpoint separado o está integrado en GetOrder.