Listar pedidos

Este endpoint devuelve un listado paginado de los pedidos de tu tenant. Admite un conjunto amplio de filtros (estado, canal, fechas, cliente, envío, etiquetas) y una búsqueda de texto libre vía q.

Úsalo cuando necesites:

Mostrar una tabla o tablero de pedidos en tu aplicación.
Sincronizar pedidos nuevos o modificados hacia un sistema externo (combinando startDate/endDate).
Filtrar pedidos por canal, estado o estado de entrega antes de procesarlos en lote.
Obtener conteos rápidos por grupo de estado o por estado individual sin traer los registros completos.

Endpoint

Lista los pedidos del tenant autenticado, con filtros y paginación

pagenumber

Número de página.

limitnumber

Cantidad de resultados por página.

orderStatusstring

Filtra por estado exacto de pedido. Alias: status. Ver los estados reales en Transiciones de estado.

statusGroupstring

Filtra por grupo visual de estado: pending, preparing, completed, cancelled, problematic, all.

channelIdsstring

Uno o más IDs de canal de venta. Alias: channelId.

salesChannelstring

Filtra por tipo de canal (ej. shopify, amazon, manual). Alias: origin.

salesChannelsstring

Variante que acepta múltiples tipos de canal. Alias: origins.

locationstring

Filtra por ubicación/sucursal del pedido.

startDatestring

Fecha mínima del rango (ISO 8601), sobre la fecha de creación del pedido.

endDatestring

Fecha máxima del rango (ISO 8601), sobre la fecha de creación del pedido.

paymentStatusstring

Filtra por estado de pago.

tagsstring

Filtra por etiqueta(s) asignada(s) al pedido.

deliveryStatusstring

Filtra por estado de entrega.

hasShipmentboolean

Filtra pedidos que tienen (o no) un envío asociado.

fulfillmentModestring

Filtra por modalidad de cumplimiento.

deliveryCarrierstring

Filtra por paquetería/carrier de entrega.

customerIdstring

Filtra los pedidos de un cliente específico.

qstring

Búsqueda de texto libre. El mismo mecanismo que expone GET /orders/search.

extendstring

Controla la inclusión de datos relacionados adicionales en la respuesta.

metafieldsstring

Filtra por metafields personalizados. Recibe un objeto JSON serializado.

200

{
  "data": [
    {
      "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
      "externalId": "FEN-10042",
      "handle": "fen-10042",
      "locationId": "65f2a0b1c4d5e6f7a8b9c0aa",
      "origin": "manual",
      "channelId": "manual",
      "orderStatus": "accepted",
      "paymentStatus": "paid",
      "currency": "MXN",
      "totalAmount": 1986.26,
      "subtotal": 1798.50,
      "tax": 287.76,
      "orderCreated": "2026-04-11T14:23:11.000Z",
      "items": [
        {
          "sku": "CAM-ROJO-M",
          "title": "Camisa Roja Talla M",
          "quantity": 2,
          "totalAmount": 998.00
        }
      ],
      "customerInfo": { "name": "María González" },
      "customerId": "65f3a1b2c4d5e6f7a8b9c0d2",
      "_links": {
        "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
        "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

Permiso requerido: orders:read

Grupos de estado reales

statusGroup solo acepta pending, preparing, completed, cancelled, problematic o all. Es una capa visual distinta de la máquina de estados fina que usan las transiciones — ver Transiciones de estado.

Tip

orderStatus/status, channelIds/channelId, salesChannel/origin y salesChannels/origins son pares de alias: usa el nombre que prefieras, ambos resuelven al mismo filtro.

Ejemplos

curl "https://api.fenicia.io/orders?statusGroup=preparing&limit=20&page=1" \
  -H "Authorization: Bearer fkapi_tu_api_key"

Conteo de pedidos

Tres endpoints devuelven conteos sin traer los registros completos. Aceptan el mismo conjunto de filtros que el listado (orderStatus, statusGroup, channelIds, salesChannel, startDate, endDate, etc.); no aplican page/limit porque no paginan resultados.

Conteo total

Cuenta los pedidos que cumplen los filtros indicados

200

{ "data": { "count": 143 } }

Permiso requerido: orders:read

Conteo por grupo de estado

Cuenta los pedidos agrupados por grupo visual de estado

200

{
  "data": {
    "pending": 12,
    "preparing": 34,
    "completed": 89,
    "cancelled": 6,
    "problematic": 2
  }
}

Permiso requerido: orders:read

all no es un grupo contable independiente: representa la ausencia de filtro por grupo, no una categoría con su propio conteo.

Conteo por estado individual

Cuenta los pedidos agrupados por estado individual de la máquina de estados

200

{
  "data": {
    "pending": 12,
    "accepted": 20,
    "processing": 14,
    "preparing": 34,
    "packaging": 8,
    "fulfilled": 40,
    "delivered": 49,
    "cancelled": 6,
    "returned": 3
  }
}

Permiso requerido: orders:read

Las claves posibles son los estados individuales de la máquina de estados (ver Transiciones de estado); el ejemplo muestra un subconjunto representativo, no los 23 estados completos.

Errores

Código	Status	Descripción
`validation:invalid_pagination`	400	`page` o `limit` tienen un valor inválido.
`validation:invalid_date_range`	400	`startDate`/`endDate` forman un rango inválido.
`validation:invalid_value`	400	Algún filtro recibió un valor con formato incorrecto.
`auth:invalid_token`	401	La API key es inválida o fue revocada.
`auth:permission_denied`	403	La API key no tiene el permiso `orders:read`.

Consulta el catálogo completo de errores para el resto de los códigos posibles.

Aislamiento por tenant

El listado solo incluye pedidos de tu propio tenant. No existe forma de consultar pedidos de otro tenant desde este endpoint.