> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riqra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leer pedidos

> Filtrar, ordenar y sincronizar pedidos de forma incremental.

El endpoint `GET /orders` devuelve los pedidos de tu organización, paginados por cursor y
ordenados del más reciente al más antiguo por defecto. Requiere el scope `orders:read`.

## Filtros

Combina cualquiera de estos parámetros de query:

| Parámetro                       | Descripción                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `status`                        | Estado del pedido: `PLACED`, `CANCELLED`.                                      |
| `paymentStatus`                 | Estado de pago: `UNPAID`, `PARTIALLY_PAID`, `PAID`, `ERROR`.                   |
| `fulfillmentStatus`             | Estado de preparación: `UNFULFILLED`, `IN_PROGRESS`, `FULFILLED`, `DELIVERED`. |
| `source`                        | Origen del pedido: `STOREFRONT`.                                               |
| `customerId`                    | Pedidos de un cliente (UUID).                                                  |
| `number`                        | Número de pedido. Acepta el entero o el formato `#123`.                        |
| `createdAfter`, `createdBefore` | Rango por fecha de creación (ISO-8601 con zona horaria).                       |
| `updatedAfter`, `updatedBefore` | Rango por fecha de actualización (ISO-8601 con zona horaria).                  |

## Orden

| Parámetro | Valores                  | Por defecto |
| --------- | ------------------------ | ----------- |
| `sort`    | `createdAt`, `updatedAt` | `createdAt` |
| `order`   | `asc`, `desc`            | `desc`      |

<Note>
  Las fechas deben incluir zona horaria (offset o `Z`). Una fecha sin zona se rechaza con `400`
  para que un punto de sincronización no se corra por la zona horaria del servidor.
</Note>

## Sincronización incremental

Para mantener una copia al día sin volver a leer todo, ordena por `updatedAt` ascendente y filtra
desde la última fecha que procesaste (tu *watermark*).

```bash theme={null}
curl "https://api-v2.riqra.com/public/v1/orders?sort=updatedAt&order=asc&updatedAfter=2026-06-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer rq_live_tu_api_key"
```

En cada corrida:

1. Lee desde tu watermark con `updatedAfter`.
2. Recorre todas las páginas con `nextCursor` (revisa [Paginación](/new-api/pagination)).
3. Guarda el `updatedAt` más alto que viste como nuevo watermark.

El campo `updatedAt` se expone justamente para este patrón.

## Líneas de paquetes (bundles)

Cuando una línea corresponde a un paquete, su campo `components` trae la composición del paquete
congelada al momento del pedido — aunque el paquete cambie después, el pedido conserva lo que se
vendió. En líneas de productos normales, `components` es un arreglo vacío.

Cada componente incluye `quantityPerBundle`: las unidades dentro de un paquete. Para saber las
unidades totales a preparar para la línea, multiplícalo por el `quantity` de la línea (en el
ejemplo: 6 × 2 = 12 gaseosas).

```json theme={null}
{
  "productName": "Six-pack Gaseosa",
  "quantity": 2,
  "components": [
    {
      "productName": "Gaseosa 500ml",
      "variantSku": "GAS-500",
      "quantityPerBundle": 6
    }
  ]
}
```

## Un pedido

`GET /orders/{id}` devuelve un solo pedido por su UUID. Si no existe en tu organización, responde
`404` con `code` `RESOURCE_MISSING`.