# Pedidos API

> Envie os pedidos da sua loja para atribuir a receita aos e-mails e montar perfis de compra.

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar ou atualizar um pedido — POST /orders

> Envie um pedido da sua loja. O Emailit atribui os novos pedidos ao e-mail em que o comprador clicou ou que abriu por último, atualiza o perfil de compras do comprador e emite order.placed. Alfa: aberto apenas à equipe do Emailit.

# Criar ou atualizar um pedido

Envie um pedido a partir do backend da sua loja. O pedido é identificado pelo `id` dele na sua loja: envie o mesmo `id` de novo e o pedido armazenado é atualizado. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

Quando um pedido é armazenado pela primeira vez, o Emailit:

- o atribui ao e-mail de campanha ou de automação em que o comprador clicou por último dentro da janela de cliques antes de `placed_at` ou, sem um clique, que ele abriu por último dentro da janela de aberturas. As janelas estão nas [configurações de e-commerce](/pt/docs/api-reference/commerce/get-settings/). Consulte [Como os pedidos são atribuídos aos e-mails](/pt/docs/commerce/#how-orders-are-credited-to-emails).
- o vincula ao contato do comprador e cria o contato, se necessário (consulte `create_contact`).
- marca como convertido o carrinho indicado em `cart_id` e também os outros carrinhos abertos do comprador que foram atualizados pela última vez antes do pedido.
- marca os códigos de cupom correspondentes como resgatados.
- atualiza as métricas de compra do contato.
- emite [`order.placed`](/pt/docs/webhooks/events/order/placed/), que os webhooks e as automações recebem.

Enviar um pedido que já está armazenado o atualiza e emite [`order.updated`](/pt/docs/webhooks/events/order/updated/), com `previous_status` quando o status mudou. A atribuição não muda. Só mudam os campos que você enviar: `status`, `placed_at`, `currency`, os valores, `coupon_codes`, `cart_id` e `items` mantêm os valores armazenados quando você não os envia, `metadata` é mesclado ao objeto armazenado e `total` não é obrigatório. Enviar `items` substitui todos os itens. Para mudar só o status ou um reembolso, você também pode usar [Atualizar um pedido](/pt/docs/api-reference/orders/update/).

Para importar pedidos antigos sem atribuí-los a e-mails nem iniciar automações, use [Importar pedidos em massa](/pt/docs/api-reference/orders/batch/).

`POST /orders`

## Corpo da requisição

- `id` (string | number, obrigatório): O ID do pedido na sua loja, com até 255 caracteres. Os números são armazenados como strings. Armazenado como `external_id`. Você também pode enviá-lo como `external_id` ou `order_id`.

- `email` (string): O endereço de e-mail do comprador. Armazenado em minúsculas. O Emailit o usa para encontrar o contato e para atribuir o pedido a um e-mail enviado para esse endereço. `customer.email` também é aceito.

- `contact_id` (string): O contato do comprador (`con_...`). Se nenhum contato tiver esse ID, o Emailit procura o contato pelo `email`.

- `first_name` (string): O nome do comprador, com até 191 caracteres. Usado quando o Emailit cria o contato. `customer.first_name` também é aceito.

- `last_name` (string): O sobrenome do comprador, com até 191 caracteres. Usado quando o Emailit cria o contato. `customer.last_name` também é aceito.

- `status` (string): `placed` (padrão), `paid`, `fulfilled`, `canceled` ou `refunded`. Na primeira vez que um pedido tiver `paid`, `fulfilled`, `canceled` ou `refunded`, o Emailit define o `paid_at`, `fulfilled_at`, `canceled_at` ou `refunded_at` correspondente com o horário atual. Os pedidos cancelados não contam na receita.

- `currency` (string): Código ISO 4217 de três letras. O padrão é a moeda do workspace nas [configurações de e-commerce](/pt/docs/api-reference/commerce/get-settings/). Os valores nunca são convertidos: os relatórios agrupam a receita por moeda.

- `total` (number | string): Total do pedido. Obrigatório para um novo pedido sem itens. Sem ele, o Emailit calcula a soma dos totais dos itens, menos `discount`, mais `shipping` e `tax`, e nunca abaixo de 0. Os valores são números ou strings numéricas, não podem ser negativos e são armazenados com até 4 casas decimais.

- `subtotal` (number | string): Valor antes do desconto, do frete e dos impostos. O padrão é a soma dos totais dos itens quando o pedido tem itens.

- `discount` (number | string): Valor do desconto, como número positivo.

- `shipping` (number | string): Valor do frete.

- `tax` (number | string): Valor dos impostos.

- `refunded_amount` (number | string): Valor reembolsado. O padrão é `0`, ou `total` quando `status` é `refunded`. A receita é `total` menos `refunded_amount`.

- `coupon_codes` (string[]): Até 20 códigos de cupom ou de desconto usados no pedido. Um código que corresponde a um [código de cupom](/pt/docs/api-reference/coupons/list-codes/) do workspace, sem diferenciar maiúsculas de minúsculas, é marcado como resgatado por este pedido. `coupon_code` e `discount_codes` também são aceitos.

- `cart_id` (string): O ID do carrinho ou do checkout na sua loja de onde o pedido veio. O [carrinho](/pt/docs/api-reference/carts/upsert/) com esse ID passa a ser `converted`.

- `placed_at` (string | number): Quando o pedido foi feito: uma data e hora ISO 8601 ou um timestamp Unix em segundos (milissegundos também funcionam). O padrão é o horário atual. Não pode estar mais de 24 horas no futuro. `created_at` também é aceito.

- `items` (object[]): Até 250 itens. `line_items` também é aceito. Cada item tem: - `product_id` (string ou número): o ID do produto na sua loja. Os itens sem `title`, `url`, `image_url` ou `categories` recebem esses valores do [catálogo](/pt/docs/api-reference/products/create/). `id` também é aceito. - `variant_id`, `sku` (string): até 255 caracteres. - `title` (string): até 500 caracteres. Obrigatório quando o item não tem `product_id` nem `sku`. `name` também é aceito. - `quantity` (inteiro): 1 ou mais. O padrão é 1. - `price` (número ou string): o preço unitário. O padrão é 0. `unit_price` também é aceito. - `total` (número ou string): o total do item. O padrão é `price` vezes `quantity`. - `categories` (string[]): até 50 nomes de categorias. - `url`, `image_url` (string): URLs `http` ou `https`.

- `metadata` (object): Os seus próprios dados de chave e valor, com até 16 KB em JSON. Nas atualizações, as chaves que você envia são mescladas ao objeto armazenado.

- `create_contact` (boolean): Padrão `true`: quando nenhum contato corresponde a `contact_id` ou `email`, o Emailit cria um a partir de `email`, `first_name` e `last_name` e emite `contact.created`. O novo contato não é inscrito em nenhuma lista de contatos, então as campanhas não o alcançam. Defina como `false` para nunca criar um contato: o pedido então só é vinculado a um contato que já existe.

- `accepts_marketing` (boolean): Defina como `true`, junto com `audience_id`, quando o comprador aceitou receber marketing. O Emailit então inscreve o contato nessa lista de contatos, a menos que o contato já esteja nela. Padrão `false`.

- `audience_id` (string): A lista de contatos (`aud_...`) em que o comprador é inscrito quando `accepts_marketing` é `true`. Se a lista não existir ou o limite de inscritos do seu plano tiver sido atingido, o pedido é armazenado mesmo assim e o contato não é inscrito.

- `email_id` (string): O e-mail de campanha (`eml_...`) de onde o comprador veio, se a sua loja o rastrear. Usado só para novos pedidos, e só são lidos os IDs que começam com `eml_`. O pedido é atribuído a esse e-mail quando ele é um e-mail de campanha do workspace e tem um clique dentro da janela de cliques antes do pedido ou foi enviado dentro dessa janela. Caso contrário, o Emailit atribui o pedido normalmente. `attribution.email_id` também é aceito.

## Retorno

`201 Created` com o [objeto de pedido](/pt/docs/api-reference/orders/get/) quando o pedido é novo, ou `200 OK` quando um pedido existente foi atualizado. Retorna `422` quando um campo é inválido.
**Requisição** `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"
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/create/

## Obter um pedido — GET /orders/{id}

> Obtenha um pedido com os itens dele e o e-mail de campanha ou de automação ao qual ele é atribuído. Alfa: aberto apenas à equipe do Emailit.

# Obter um pedido

Obtém um pedido pelo ID dele no Emailit ou pelo ID do pedido na sua loja, com os itens e a atribuição dele. Requer uma chave de API com escopo `full`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do pedido (`ord_...`) ou o ID do pedido na sua loja (`external_id`). Codifique para URL os IDs da loja que contêm caracteres especiais.

## O objeto de pedido

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

- `id` (string): ID do pedido no Emailit (`ord_...`).

- `external_id` (string): O ID do pedido na sua loja: o `id` que você enviou.

- `contact_id` (string | null): O contato do comprador (`con_...`), ou `null` quando o pedido não está vinculado a um contato.

- `email` (string | null): O endereço de e-mail do comprador, em minúsculas.

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

- `currency` (string): Código ISO 4217 de três letras dos valores.

- `subtotal` (number | null): Soma dos itens antes do desconto, do frete e dos impostos.

- `discount` (number | null): Valor do desconto.

- `shipping` (number | null): Valor do frete.

- `tax` (number | null): Valor dos impostos.

- `total` (number): Total do pedido. A receita nos relatórios é `total` menos `refunded_amount`, e os pedidos cancelados não contam.

- `refunded_amount` (number): Valor reembolsado até agora. `0` quando nada foi reembolsado.

- `coupon_codes` (string[]): Códigos de cupom ou de desconto usados no pedido.

- `cart_id` (string | null): O ID do carrinho ou do checkout na sua loja de onde o pedido veio.

- `source` (string): Como o pedido chegou ao Emailit: `api`, `js` (o script de rastreamento) ou `import` ([importação em massa](/pt/docs/api-reference/orders/batch/)).

- `placed_at` (string): Quando o pedido foi feito, em ISO 8601 UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): Quando o Emailit armazenou o pedido pela primeira vez com esse status. Definido uma vez e não é limpo quando o status muda de novo.

- `attribution` (object | null): O e-mail ao qual o pedido é atribuído, ou `null`. Definido uma vez, quando o pedido é armazenado pela primeira vez. Consulte [Como os pedidos são atribuídos aos e-mails](/pt/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (string): o e-mail ao qual o pedido é atribuído. - `campaign_id`, `campaign_name` (string ou null): a campanha dele. - `variant_id` (string ou null): a versão do teste A/B (`cvr_...`) que o comprador recebeu. - `automation_id`, `automation_name` (string ou null): a automação dele. - `type` (string): `click` ou `open`. - `touched_at` (string ou null): quando o clique ou a abertura aconteceu.

- `items` (object[]): Itens. Cada um tem `product_id` (o ID do produto na sua loja), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` e `image_url`.

- `metadata` (object): Os seus próprios dados de chave e valor.

- `created_at, updated_at` (string): Quando o Emailit armazenou o pedido e quando ele mudou pela última vez, em ISO 8601 UTC.

**Requisição** `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."
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/get/

## Atualizar um pedido — POST /orders/{id}

> Altere o status de um pedido, registre um reembolso ou adicione metadados sem enviar o pedido inteiro de novo. Alfa: aberto apenas à equipe do Emailit.

# Atualizar um pedido

Altera o status de um pedido armazenado, registra um reembolso ou adiciona metadados. Todo o resto continua como está, incluindo os itens e a atribuição. As métricas de compra do comprador são recalculadas, e o Emailit emite [`order.updated`](/pt/docs/webhooks/events/order/updated/), com o `previous_status` do pedido quando o status mudou. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do pedido (`ord_...`) ou o ID do pedido na sua loja.

## Corpo da requisição

Envie pelo menos um destes campos.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` ou `refunded`. Na primeira vez que o pedido receber `paid`, `fulfilled`, `canceled` ou `refunded`, o `paid_at`, `fulfilled_at`, `canceled_at` ou `refunded_at` correspondente é definido com o horário atual. Os pedidos cancelados não contam na receita.

- `refunded_amount` (number | string): Valor total reembolsado até agora, e não o valor deste reembolso. Não pode ser negativo. A receita é `total` menos `refunded_amount`. Se você definir `status` como `refunded` sem `refunded_amount` e nada tiver sido reembolsado antes, o `total` inteiro conta como reembolsado.

- `metadata` (object): Chaves a mesclar aos metadados do pedido. Até 16 KB em JSON.

## Retorno

`200 OK` com o [objeto de pedido](/pt/docs/api-reference/orders/get/) atualizado. Retorna `404` se nenhum pedido corresponder a `id` e `422` quando o corpo estiver vazio ou um campo for inválido.
**Requisição** `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"
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/update/

## Listar pedidos — GET /orders

> Liste os pedidos, dos mais recentes para os mais antigos, filtrados por comprador, status, período ou pela campanha ou automação à qual são atribuídos. Alfa: aberto apenas à equipe do Emailit.

# Listar pedidos

Lista os pedidos com os itens deles, dos feitos mais recentemente para os mais antigos. Requer uma chave de API com escopo `full`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Parâmetros de consulta

- `page` (integer): Número da página para a paginação (mínimo: 1, padrão: 1).

- `limit` (integer): Número de pedidos a retornar (mínimo: 1, máximo: 100, padrão: 25).

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas no ID do pedido na sua loja ou no endereço de e-mail do comprador.

- `contact_id` (string): Só os pedidos deste contato (`con_...`).

- `email` (string): Só os pedidos com este endereço de e-mail do comprador, sem diferenciar maiúsculas de minúsculas.

- `status` (string): Só os pedidos com este status: `placed`, `paid`, `fulfilled`, `canceled` ou `refunded`.

- `campaign_id` (string): Só os pedidos atribuídos a esta campanha (`cmp_...`).

- `automation_id` (string): Só os pedidos atribuídos a esta automação (`aut_...`).

- `attributed` (boolean): `true` para os pedidos atribuídos a um e-mail, `false` para os que não são.

- `from` (string): Só os pedidos feitos neste momento ou depois dele. Uma data ou data e hora ISO 8601; qualquer outro valor retorna `422`.

- `to` (string): Só os pedidos feitos neste momento ou antes dele. Uma data ou data e hora ISO 8601; qualquer outro valor retorna `422`.

- `match` (string): `all` (padrão) exige que todos os filtros `key.condition` correspondam. `or` aceita qualquer um deles. Consulte [Filtragem](/pt/docs/api-reference/filtering/).

- `sort` (string): Chave de ordenação: `placed_at` (padrão), `total` ou `created_at`.

- `order` (string): Direção da ordenação: `asc` ou `desc` (padrão).

## Filtros

Chaves de filtro e de ordenação: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

Neste endpoint, `order` só aceita `asc` ou `desc`. Passe a chave de ordenação em `sort`, por exemplo `sort=total&order=desc`.

## Retorno

Uma página de [objetos de pedido](/pt/docs/api-reference/orders/get/) em `data`, com `total_records`, `next_page_url` e `previous_page_url`. As URLs de página levam só `page` e `limit`, então adicione a sua busca e os seus filtros de novo quando segui-las.
**Requisição** `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
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/list/

## Importar pedidos em massa — POST /orders/batch

> Envie até 1.000 pedidos em uma requisição, por exemplo o seu histórico de pedidos. Por padrão, as importações não atribuem pedidos a e-mails nem emitem eventos de pedido. Alfa: aberto apenas à equipe do Emailit.

# Importar pedidos em massa

Envie até 1.000 pedidos em uma requisição. Use este endpoint para importar o seu histórico de pedidos, para que as métricas de compra, os segmentos e as recomendações de produtos tenham dados desde o primeiro dia. Cada pedido segue as regras de [Criar ou atualizar um pedido](/pt/docs/api-reference/orders/create/): ele é criado ou atualizado pelo `id`, os contatos são criados a menos que `create_contact` seja `false`, os carrinhos são convertidos, os códigos de cupom são resgatados e as métricas de compra são atualizadas. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

Por padrão, os pedidos são históricos: eles não são atribuídos a nenhum e-mail, e o Emailit não emite `order.placed` nem `order.updated`, então eles não iniciam automações nem chegam aos webhooks. Os novos contatos continuam emitindo `contact.created`. Os pedidos enviados com este endpoint têm `source` definido como `import`, com ou sem `historical`.

Os pedidos inválidos são ignorados e listados em `rejected`; os outros são armazenados. A requisição retorna `200` mesmo assim.

`POST /orders/batch`

## Corpo da requisição

- `orders` (object[], obrigatório): De 1 a 1.000 pedidos, cada um com os campos de [Criar ou atualizar um pedido](/pt/docs/api-reference/orders/create/).

- `historical` (boolean): Padrão `true`: sem atribuição e sem eventos de pedido. Defina como `false` para tratar os pedidos como pedidos enviados um a um: os novos pedidos são atribuídos aos e-mails e emitem `order.placed`, e os pedidos atualizados emitem `order.updated`.

## Retorno

- `created` (integer): Número de pedidos novos.

- `updated` (integer): Número de pedidos que já estavam armazenados e foram atualizados.

- `rejected` (object[]): Pedidos que não foram armazenados. Cada item tem o `index` do pedido no seu array `orders` e `errors`, indexado pelo caminho do campo, como `orders.4.currency`. Um pedido que passou na validação mas não pôde ser salvo tem o erro `could not be stored` em `orders.<index>`.

Retorna `422` se `orders` estiver vazio ou tiver mais de 1.000 itens.
**Requisição** `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."
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/batch/

## Excluir um pedido — DELETE /orders/{id}

> Exclua um pedido e os itens dele e recalcule as métricas de compra do comprador. Alfa: aberto apenas à equipe do Emailit.

# Excluir um pedido

Exclui um pedido e os itens dele. As métricas de compra do comprador são recalculadas sem ele, e a receita dele deixa de contar nos relatórios. Os códigos de cupom que ele resgatou continuam resgatados e os carrinhos convertidos continuam convertidos. Nenhum evento é emitido. Para manter o pedido mas deixar de contar a receita dele, defina o status dele como `canceled` com [Atualizar um pedido](/pt/docs/api-reference/orders/update/) em vez de excluí-lo. Requer uma chave de API com escopo `full`.

> **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do pedido (`ord_...`) ou o ID do pedido na sua loja.

**Requisição** `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."
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/orders/delete/