# Pedidos API

> Envía los pedidos de tu tienda para atribuir los ingresos a los emails y crear perfiles de compras.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear o actualizar un pedido — POST /orders

> Envía un pedido desde tu tienda. Emailit atribuye los pedidos nuevos al último email en el que el comprador hizo clic o que abrió, actualiza su perfil de compras y emite order.placed. Alfa: solo para el equipo de Emailit.

# Crear o actualizar un pedido

Envía un pedido desde el backend de tu tienda. El pedido se identifica por su `id` en tu tienda: si vuelves a enviar el mismo `id`, se actualiza el pedido guardado. Requiere una clave de API con el permiso `full` o `events`. Con una clave `events`, la respuesta solo contiene `object`, `id` y `external_id`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

Cuando un pedido se guarda por primera vez, Emailit:

- lo atribuye al último email de campaña o de automatización en el que el comprador hizo clic dentro de la ventana de clic anterior a `placed_at` o, si no hay ningún clic, al último que abrió dentro de la ventana de apertura. Las ventanas están en la [configuración de Comercio electrónico](/es/docs/api-reference/commerce/get-settings/). Consulta [Cómo se atribuyen los pedidos a los emails](/es/docs/commerce/#how-orders-are-credited-to-emails).
- lo vincula al contacto del comprador y crea el contacto si hace falta (consulta `create_contact`).
- marca como convertido el carrito indicado en `cart_id`, y también los demás carritos abiertos del comprador que se actualizaron por última vez antes del pedido.
- marca como canjeados los códigos de cupón que coinciden.
- actualiza las métricas de compra del contacto.
- emite [`order.placed`](/es/docs/webhooks/events/order/placed/), que reciben los webhooks y las automatizaciones.

Si envías un pedido que ya está guardado, se actualiza y se emite [`order.updated`](/es/docs/webhooks/events/order/updated/), con `previous_status` si el estado ha cambiado. La atribución no cambia. Solo cambian los campos que envías: `status`, `placed_at`, `currency`, los importes, `coupon_codes`, `cart_id` e `items` conservan sus valores guardados si no los envías, `metadata` se combina con el objeto guardado y `total` no es obligatorio. Si envías `items`, se sustituyen todos los artículos. Para cambiar solo el estado o un reembolso, también puedes usar [Actualizar un pedido](/es/docs/api-reference/orders/update/).

Para importar pedidos antiguos sin atribuirlos a los emails ni iniciar automatizaciones, usa [Importar pedidos en bloque](/es/docs/api-reference/orders/batch/).

`POST /orders`

## Cuerpo de la petición

- `id` (string | number, obligatorio): El ID del pedido en tu tienda, de hasta 255 caracteres. Los números se guardan como cadenas. Se guarda como `external_id`. También puedes enviarlo como `external_id` u `order_id`.

- `email` (string): La dirección de email del comprador. Se guarda en minúsculas. Emailit la usa para encontrar el contacto y para atribuir el pedido a un email enviado a esa dirección. También se acepta `customer.email`.

- `contact_id` (string): El contacto del comprador (`con_...`). Si ningún contacto tiene este ID, Emailit busca el contacto por `email`.

- `first_name` (string): El nombre del comprador, de hasta 191 caracteres. Se usa cuando Emailit crea el contacto. También se acepta `customer.first_name`.

- `last_name` (string): Los apellidos del comprador, de hasta 191 caracteres. Se usan cuando Emailit crea el contacto. También se acepta `customer.last_name`.

- `status` (string): `placed` (por defecto), `paid`, `fulfilled`, `canceled` o `refunded`. La primera vez que un pedido tiene `paid`, `fulfilled`, `canceled` o `refunded`, Emailit asigna la hora actual al campo correspondiente: `paid_at`, `fulfilled_at`, `canceled_at` o `refunded_at`. Los pedidos cancelados no cuentan para los ingresos.

- `currency` (string): El código ISO 4217 de tres letras. Por defecto, la moneda del espacio de trabajo en la [configuración de Comercio electrónico](/es/docs/api-reference/commerce/get-settings/). Los importes nunca se convierten: los informes agrupan los ingresos por moneda.

- `total` (number | string): El total del pedido. Obligatorio en un pedido nuevo sin artículos. Si no lo envías, Emailit calcula la suma de los totales de los artículos, menos `discount`, más `shipping` y `tax`, y nunca por debajo de 0. Los importes son números o cadenas numéricas, no pueden ser negativos y se guardan con hasta 4 decimales.

- `subtotal` (number | string): El importe antes de descuentos, envío e impuestos. Por defecto, la suma de los totales de los artículos si el pedido tiene artículos.

- `discount` (number | string): El importe del descuento, como número positivo.

- `shipping` (number | string): El importe del envío.

- `tax` (number | string): El importe de los impuestos.

- `refunded_amount` (number | string): El importe reembolsado. Por defecto, `0`, o `total` si `status` es `refunded`. Los ingresos son `total` menos `refunded_amount`.

- `coupon_codes` (string[]): Hasta 20 códigos de cupón o de descuento usados en el pedido. Un código que coincide con un [código de cupón](/es/docs/api-reference/coupons/list-codes/) del espacio de trabajo, sin distinguir entre mayúsculas y minúsculas, se marca como canjeado por este pedido. También se aceptan `coupon_code` y `discount_codes`.

- `cart_id` (string): El ID del carrito o del pago en tu tienda del que procede el pedido. El [carrito](/es/docs/api-reference/carts/upsert/) con este ID pasa a `converted`.

- `placed_at` (string | number): Cuándo se realizó el pedido: una fecha y hora en formato ISO 8601 o una marca de tiempo Unix en segundos (también funcionan los milisegundos). Por defecto, la hora actual. No puede estar más de 24 horas en el futuro. También se acepta `created_at`.

- `items` (object[]): Hasta 250 artículos. También se acepta `line_items`. Cada artículo tiene: - `product_id` (cadena o número): el ID del producto en tu tienda. Los artículos sin `title`, `url`, `image_url` o `categories` los toman del [catálogo](/es/docs/api-reference/products/create/). También se acepta `id`. - `variant_id`, `sku` (cadena): hasta 255 caracteres. - `title` (cadena): hasta 500 caracteres. Obligatorio si el artículo no tiene `product_id` ni `sku`. También se acepta `name`. - `quantity` (entero): 1 o más. Por defecto, 1. - `price` (número o cadena): el precio unitario. Por defecto, 0. También se acepta `unit_price`. - `total` (número o cadena): el total de la línea. Por defecto, `price` por `quantity`. - `categories` (array de cadenas): hasta 50 nombres de categoría. - `url`, `image_url` (cadena): URL `http` o `https`.

- `metadata` (object): Tus propios datos de clave y valor, de hasta 16 KB en JSON. En las actualizaciones, las claves que envías se combinan con el objeto guardado.

- `create_contact` (boolean): Por defecto, `true`: si ningún contacto coincide con `contact_id` o `email`, Emailit crea uno a partir de `email`, `first_name` y `last_name` y emite `contact.created`. El contacto nuevo no se suscribe a ninguna lista de contactos, así que las campañas no le llegan. Con `false`, nunca se crea un contacto: el pedido solo se vincula a un contacto que ya existe.

- `accepts_marketing` (boolean): Pon `true` junto con `audience_id` si el comprador ha aceptado recibir marketing. Entonces Emailit suscribe el contacto a esa lista de contactos, salvo que ya esté en ella. Por defecto, `false`.

- `audience_id` (string): La lista de contactos (`aud_...`) a la que se suscribe al comprador si `accepts_marketing` es `true`. Si la lista no existe o se ha alcanzado el límite de suscriptores de tu plan, el pedido se guarda igualmente y el contacto no se suscribe.

- `email_id` (string): El email de campaña (`eml_...`) del que procede el comprador, si tu tienda lo registra. Solo se usa en los pedidos nuevos, y solo se leen los ID que empiezan por `eml_`. El pedido se atribuye a este email si es un email de campaña del espacio de trabajo y tiene un clic dentro de la ventana de clic anterior al pedido o se envió dentro de esa ventana. Si no, Emailit atribuye el pedido como de costumbre. También se acepta `attribution.email_id`.

## Devuelve

`201 Created` con el [objeto de pedido](/es/docs/api-reference/orders/get/) si el pedido es nuevo, o `200 OK` si se ha actualizado un pedido existente. Devuelve `422` si un campo no es válido.
**Petición** `POST /orders`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1042",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "paid",
    "currency": "USD",
    "discount": 10.7,
    "shipping": 5,
    "tax": 0,
    "coupon_codes": ["WELCOME-7KQ2M9XA"],
    "cart_id": "c-58f1a2",
    "placed_at": "2026-10-08T14:32:10Z",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "title": "Trail running shoe", "quantity": 1, "price": 89 },
      { "product_id": "8123456790", "title": "Merino running socks", "quantity": 2, "price": 9 }
    ],
    "metadata": { "channel": "web" },
    "accepts_marketing": true,
    "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV"
  }'
```

**201**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**422**

```json
{
  "message": "Validation failed. items.1.quantity: must be a positive integer",
  "errors": {
    "items.1.quantity": [
      "must be a positive integer"
    ]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/create/

## Obtener un pedido — GET /orders/{id}

> Obtén un pedido con sus artículos y el email de campaña o de automatización al que se atribuye. Alfa: solo para el equipo de Emailit.

# Obtener un pedido

Obtén un pedido por su ID de Emailit o por el ID del pedido en tu tienda, con sus artículos y su atribución. Requiere una clave de API con el permiso `full`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del pedido (`ord_...`) o el ID del pedido en tu tienda (`external_id`). Codifica para URL los ID de tienda que contengan caracteres especiales.

## Objeto de pedido

- `object` (string): Siempre `order`.

- `id` (string): El ID de Emailit del pedido (`ord_...`).

- `external_id` (string): El ID del pedido en tu tienda: el `id` que enviaste.

- `contact_id` (string | null): El contacto del comprador (`con_...`), o `null` si el pedido no está vinculado a ningún contacto.

- `email` (string | null): La dirección de email del comprador, en minúsculas.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` o `refunded`.

- `currency` (string): El código ISO 4217 de tres letras de los importes.

- `subtotal` (number | null): La suma de los artículos antes de descuentos, envío e impuestos.

- `discount` (number | null): El importe del descuento.

- `shipping` (number | null): El importe del envío.

- `tax` (number | null): El importe de los impuestos.

- `total` (number): El total del pedido. Los ingresos de los informes son `total` menos `refunded_amount`, y los pedidos cancelados no cuentan.

- `refunded_amount` (number): El importe reembolsado hasta el momento. `0` si no se ha reembolsado nada.

- `coupon_codes` (string[]): Los códigos de cupón o de descuento usados en el pedido.

- `cart_id` (string | null): El ID del carrito o del pago en tu tienda del que procede el pedido.

- `source` (string): Cómo llegó el pedido a Emailit: `api`, `js` (el script de seguimiento) o `import` ([importación en bloque](/es/docs/api-reference/orders/batch/)).

- `placed_at` (string): Cuándo se realizó el pedido, en formato ISO 8601 UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): Cuándo guardó Emailit el pedido por primera vez con ese estado. Se asigna una vez y no se borra cuando el estado vuelve a cambiar.

- `attribution` (object | null): El email al que se atribuye el pedido, o `null`. Se asigna una vez, cuando el pedido se guarda por primera vez. Consulta [Cómo se atribuyen los pedidos a los emails](/es/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (cadena): el email al que se atribuye. - `campaign_id`, `campaign_name` (cadena o null): su campaña. - `variant_id` (cadena o null): la versión de la prueba A/B (`cvr_...`) que recibió el comprador. - `automation_id`, `automation_name` (cadena o null): su automatización. - `type` (cadena): `click` u `open`. - `touched_at` (cadena o null): cuándo se produjo el clic o la apertura.

- `items` (object[]): Los artículos. Cada uno tiene `product_id` (el ID del producto en tu tienda), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` e `image_url`.

- `metadata` (object): Tus propios datos de clave y valor.

- `created_at, updated_at` (string): Cuándo guardó Emailit el pedido y cuándo cambió por última vez, en formato ISO 8601 UTC.

**Petición** `GET /orders/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/get/

## Actualizar un pedido — POST /orders/{id}

> Cambia el estado de un pedido, registra un reembolso o añade metadatos sin volver a enviar el pedido completo. Alfa: solo para el equipo de Emailit.

# Actualizar un pedido

Cambia el estado de un pedido guardado, registra un reembolso o añade metadatos. Todo lo demás se queda como está, incluidos los artículos y la atribución. Las métricas de compra del comprador se vuelven a calcular, y Emailit emite [`order.updated`](/es/docs/webhooks/events/order/updated/), con el `previous_status` del pedido si el estado ha cambiado. Requiere una clave de API con el permiso `full` o `events`. Con una clave `events`, la respuesta solo contiene `object`, `id` y `external_id`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del pedido (`ord_...`) o el ID del pedido en tu tienda.

## Cuerpo de la petición

Envía al menos uno de estos campos.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` o `refunded`. La primera vez que el pedido pasa a `paid`, `fulfilled`, `canceled` o `refunded`, se asigna la hora actual al campo correspondiente: `paid_at`, `fulfilled_at`, `canceled_at` o `refunded_at`. Los pedidos cancelados no cuentan para los ingresos.

- `refunded_amount` (number | string): El importe total reembolsado hasta el momento, no el importe de este reembolso. No puede ser negativo. Los ingresos son `total` menos `refunded_amount`. Si pones `status` en `refunded` sin `refunded_amount` y no se había reembolsado nada antes, todo el `total` cuenta como reembolsado.

- `metadata` (object): Las claves que se combinan con los metadatos del pedido. Hasta 16 KB en JSON.

## Devuelve

`200 OK` con el [objeto de pedido](/es/docs/api-reference/orders/get/) actualizado. Devuelve `404` si ningún pedido coincide con `id` y `422` si el cuerpo está vacío o un campo no es válido.
**Petición** `POST /orders/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/1042 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "refunded_amount": 18 }'
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 18,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-10T08:05:39.871Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

**422**

```json
{
  "message": "Validation failed. status: is required",
  "errors": {
    "status": [
      "is required"
    ]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/update/

## Listar pedidos — GET /orders

> Lista los pedidos, del más reciente al más antiguo, filtrados por comprador, estado, intervalo de fechas o la campaña o automatización a la que se atribuyen. Alfa: solo para el equipo de Emailit.

# Listar pedidos

Lista los pedidos con sus artículos, del realizado más recientemente al más antiguo. Requiere una clave de API con el permiso `full`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Parámetros de consulta

- `page` (integer): El número de página (mínimo: 1; por defecto: 1).

- `limit` (integer): El número de pedidos que se devuelven (mínimo: 1; máximo: 100; por defecto: 25).

- `search` (string): Búsqueda sin distinguir entre mayúsculas y minúsculas en el ID del pedido en tu tienda o en la dirección de email del comprador.

- `contact_id` (string): Solo los pedidos de este contacto (`con_...`).

- `email` (string): Solo los pedidos con esta dirección de email del comprador, sin distinguir entre mayúsculas y minúsculas.

- `status` (string): Solo los pedidos con este estado: `placed`, `paid`, `fulfilled`, `canceled` o `refunded`.

- `campaign_id` (string): Solo los pedidos atribuidos a esta campaña (`cmp_...`).

- `automation_id` (string): Solo los pedidos atribuidos a esta automatización (`aut_...`).

- `attributed` (boolean): `true` para los pedidos atribuidos a un email y `false` para los que no lo están.

- `from` (string): Solo los pedidos realizados en este momento o después. Una fecha o una fecha y hora en formato ISO 8601; cualquier otro valor devuelve `422`.

- `to` (string): Solo los pedidos realizados en este momento o antes. Una fecha o una fecha y hora en formato ISO 8601; cualquier otro valor devuelve `422`.

- `match` (string): `all` (por defecto) exige que coincidan todos los filtros `key.condition`. `or` exige que coincida cualquiera de ellos. Consulta [Filtrado](/es/docs/api-reference/filtering/).

- `sort` (string): El campo de ordenación: `placed_at` (por defecto), `total` o `created_at`.

- `order` (string): La dirección de ordenación: `asc` o `desc` (por defecto).

## Filtros

Claves de filtro y de ordenación: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

En este endpoint, `order` solo admite `asc` o `desc`. Indica el campo de ordenación en `sort`, por ejemplo `sort=total&order=desc`.

## Devuelve

Una página de [objetos de pedido](/es/docs/api-reference/orders/get/) en `data`, con `total_records`, `next_page_url` y `previous_page_url`. Las URL de las páginas solo llevan `page` y `limit`, así que vuelve a añadir tu búsqueda y tus filtros cuando las sigas.
**Petición** `GET /orders`

**cURL**

```bash
curl "https://api.emailit.com/v2/orders?campaign_id=cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN&from=2026-10-01&limit=25" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "order",
      "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
      "external_id": "1042",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "paid",
      "currency": "USD",
      "subtotal": 89,
      "discount": null,
      "shipping": 5,
      "tax": 0,
      "total": 94,
      "refunded_amount": 0,
      "coupon_codes": [],
      "cart_id": null,
      "source": "api",
      "placed_at": "2026-10-08T14:32:10.000Z",
      "paid_at": "2026-10-08T14:32:11.204Z",
      "fulfilled_at": null,
      "canceled_at": null,
      "refunded_at": null,
      "attribution": {
        "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
        "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
        "campaign_name": "October newsletter",
        "variant_id": null,
        "automation_id": null,
        "automation_name": null,
        "type": "click",
        "touched_at": "2026-10-08T09:41:52.000Z"
      },
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": null,
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "categories": [
            "Shoes",
            "Running"
          ],
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "metadata": {},
      "created_at": "2026-10-08T14:32:11.204Z",
      "updated_at": "2026-10-08T14:32:11.204Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/list/

## Importar pedidos en bloque — POST /orders/batch

> Envía hasta 1000 pedidos en una sola petición, por ejemplo tu historial de pedidos. Por defecto, las importaciones no atribuyen pedidos a los emails ni emiten eventos de pedido. Alfa: solo para el equipo de Emailit.

# Importar pedidos en bloque

Envía hasta 1000 pedidos en una sola petición. Úsalo para importar tu historial de pedidos, de modo que las métricas de compra, los segmentos y las recomendaciones de productos tengan datos desde el primer día. Cada pedido sigue las reglas de [Crear o actualizar un pedido](/es/docs/api-reference/orders/create/): se crea o se actualiza según su `id`, se crean los contactos salvo que `create_contact` sea `false`, se convierten los carritos, se canjean los códigos de cupón y se actualizan las métricas de compra. Requiere una clave de API con el permiso `full` o `events`. Con una clave `events`, la respuesta solo contiene `object`, `id` y `external_id`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

Por defecto, los pedidos son históricos: no se atribuyen a ningún email y Emailit no emite `order.placed` ni `order.updated`, así que no inician automatizaciones ni llegan a los webhooks. Los contactos nuevos siguen emitiendo `contact.created`. Los pedidos enviados con este endpoint tienen `source` igual a `import`, con o sin `historical`.

Los pedidos no válidos se omiten y se indican en `rejected`; los demás se guardan. La petición devuelve igualmente `200`.

`POST /orders/batch`

## Cuerpo de la petición

- `orders` (object[], obligatorio): De 1 a 1000 pedidos, cada uno con los campos de [Crear o actualizar un pedido](/es/docs/api-reference/orders/create/).

- `historical` (boolean): Por defecto, `true`: sin atribución y sin eventos de pedido. Con `false`, los pedidos se tratan como los pedidos enviados de uno en uno: los pedidos nuevos se atribuyen a los emails y emiten `order.placed`, y los pedidos actualizados emiten `order.updated`.

## Devuelve

- `created` (integer): El número de pedidos nuevos.

- `updated` (integer): El número de pedidos que ya estaban guardados y se han actualizado.

- `rejected` (object[]): Los pedidos que no se han guardado. Cada elemento tiene el `index` del pedido en tu array `orders` y `errors`, con la ruta del campo como clave, por ejemplo `orders.4.currency`. Un pedido que ha superado la validación pero no se ha podido guardar tiene el error `could not be stored` en `orders.<index>`.

Devuelve `422` si `orders` está vacío o tiene más de 1000 elementos.
**Petición** `POST /orders/batch`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/batch \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "id": "981",
        "email": "ada@example.com",
        "status": "fulfilled",
        "currency": "USD",
        "placed_at": "2026-03-14T10:12:00Z",
        "items": [{ "product_id": "8123456789", "quantity": 1, "price": 89 }]
      },
      {
        "id": "982",
        "email": "grace@example.com",
        "status": "fulfilled",
        "currency": "usd dollars",
        "total": 18,
        "placed_at": "2026-03-15T16:40:00Z"
      }
    ]
  }'
```

**200**

```json
{
  "created": 1,
  "updated": 0,
  "rejected": [
    {
      "index": 1,
      "errors": {
        "orders.1.currency": [
          "must be a three-letter ISO 4217 code, e.g. USD"
        ]
      }
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. orders: Send 1 to 1000 orders.",
  "errors": {
    "orders": [
      "Send 1 to 1000 orders."
    ]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/batch/

## Eliminar un pedido — DELETE /orders/{id}

> Elimina un pedido y sus artículos, y vuelve a calcular las métricas de compra del comprador. Alfa: solo para el equipo de Emailit.

# Eliminar un pedido

Elimina un pedido y sus artículos. Las métricas de compra del comprador se vuelven a calcular sin él, y sus ingresos dejan de contar en los informes. Los códigos de cupón que canjeó siguen canjeados y los carritos convertidos siguen convertidos. No se emite ningún evento. Para conservar el pedido pero dejar de contar sus ingresos, cambia su estado a `canceled` con [Actualizar un pedido](/es/docs/api-reference/orders/update/). Requiere una clave de API con el permiso `full`.

> **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del pedido (`ord_...`) o el ID del pedido en tu tienda.

**Petición** `DELETE /orders/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "deleted": true
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/orders/delete/