# Carrinhos API

> Envie os carrinhos dos seus compradores para o Emailit detectar carrinhos abandonados.

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

## Criar ou atualizar um carrinho — POST /carts

> Envie o carrinho atual do comprador a partir da sua loja. Os carrinhos parados de contatos conhecidos passam a ser abandonados e emitem cart.abandoned. Alfa: aberto apenas à equipe do Emailit.

# Criar ou atualizar um carrinho

Envie o carrinho atual do comprador sempre que ele mudar. O carrinho é identificado pelo `id` dele na sua loja: envie o mesmo `id` de novo e o carrinho armazenado é atualizado. Cada chamada substitui os `items` e o `total` do carrinho. O e-mail, o contato, a moeda e a URL de checkout são mantidos quando você não os envia. 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).

O [script de rastreamento](/pt/docs/commerce/connect-your-shop/#the-tracking-script) pode enviar os carrinhos a partir do navegador.

Um carrinho novo, ou uma mudança nos itens, no total, no status ou no contato de um carrinho, emite [`cart.updated`](/pt/docs/webhooks/events/cart/updated/). Enviar o mesmo carrinho de novo não emite nada.

Como um carrinho passa de um status para outro:

- **Abandonado.** Um carrinho que pertence a um contato, tem pelo menos um item e não é atualizado durante os `cart_abandon_minutes` das [configurações de e-commerce](/pt/docs/api-reference/commerce/get-settings/) (60 por padrão) passa a ser `abandoned`, e o Emailit emite [`cart.abandoned`](/pt/docs/webhooks/events/cart/abandoned/). Os carrinhos sem contato continuam `active`.
- **Ativo de novo.** Atualizar um carrinho abandonado o torna `active` e limpa `abandoned_at`.
- **Convertido.** Um [pedido](/pt/docs/api-reference/orders/create/) com o mesmo `cart_id` converte o carrinho. Um novo pedido do mesmo contato também converte os carrinhos desse contato que foram atualizados pela última vez antes do pedido. Um carrinho convertido continua convertido quando você o atualiza.

`POST /carts`

## Corpo da requisição

- `id` (string | number, obrigatório): O ID do carrinho ou do checkout na sua loja, com até 255 caracteres. Armazenado como `external_id`. Envie o mesmo valor como `cart_id` no pedido. Você também pode enviá-lo como `external_id` ou `cart_id`.

- `email` (string): O endereço de e-mail do comprador. Vincula o carrinho ao contato com esse endereço. Os carrinhos nunca criam contatos: um carrinho sem um contato correspondente não pode passar a ser abandonado. `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`.

- `anonymous_id` (string): O ID de visitante do script de rastreamento, com até 255 caracteres. Quando esse visitante for identificado mais tarde, os carrinhos com esse ID e sem contato são vinculados ao contato.

- `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/).

- `items` (object[]): Até 250 itens, no mesmo formato dos `items` de [Criar ou atualizar um pedido](/pt/docs/api-reference/orders/create/). Os itens sem `title`, `url` ou `image_url` recebem esses valores do [catálogo](/pt/docs/api-reference/products/create/). `line_items` também é aceito.

- `total` (number | string): Valor do carrinho. O padrão é a soma dos totais dos itens.

- `checkout_url` (string): Um link `http` ou `https` que leva o comprador de volta a este carrinho, com até 2.048 caracteres. Os e-mails podem criar um link para ele com o [bloco de carrinho](/pt/docs/campaigns/products-and-coupons/#the-cart).

- `status` (string): `active` (padrão) ou `converted`. Envie `converted` para fechar um carrinho você mesmo.

## Retorno

`201 Created` com o [objeto de carrinho](/pt/docs/api-reference/carts/get/) quando o carrinho é novo, ou `200 OK` quando um carrinho existente foi atualizado. Retorna `422` quando um campo é inválido.
**Requisição** `POST /carts`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/carts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "c-58f1a2",
    "email": "ada@example.com",
    "currency": "USD",
    "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "quantity": 1, "price": 89 }
    ]
  }'
```

**201**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "active",
  "currency": "USD",
  "total": 89,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": null,
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:12:47.630Z"
}
```

**422**

```json
{
  "message": "Validation failed. checkout_url: must be an http(s) URL",
  "errors": {
    "checkout_url": [
      "must be an http(s) URL"
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/carts/upsert/

## Obter um carrinho — GET /carts/{id}

> Obtenha um carrinho pelo ID dele no Emailit ou pelo ID do carrinho ou do checkout na sua loja. Alfa: aberto apenas à equipe do Emailit.

# Obter um carrinho

Obtém um carrinho pelo ID dele no Emailit ou pelo ID do carrinho ou do checkout na sua loja. 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 /carts/{id}`

## Parâmetros de caminho

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

## O objeto de carrinho

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

- `id` (string): ID do carrinho no Emailit (`crt_...`).

- `external_id` (string): O ID do carrinho ou do checkout na sua loja: o `id` que você enviou. Os carrinhos do script de rastreamento sem um ID próprio usam `web:` seguido do ID anônimo do visitante.

- `contact_id` (string | null): O contato a quem o carrinho pertence (`con_...`), ou `null` enquanto o comprador é desconhecido.

- `email` (string | null): O endereço de e-mail do comprador.

- `status` (string): - `active`: o comprador ainda está comprando. - `abandoned`: o carrinho pertence a um contato, tem itens e não muda durante os `cart_abandon_minutes` das [configurações de e-commerce](/pt/docs/api-reference/commerce/get-settings/). - `converted`: um pedido foi feito a partir dele, ou você o enviou com `status` definido como `converted`.

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

- `total` (number): Valor do carrinho.

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

- `checkout_url` (string | null): Link que leva o comprador de volta a este carrinho.

- `source` (string): `api`, ou `js` para os carrinhos do script de rastreamento.

- `abandoned_at` (string | null): Quando o carrinho foi marcado como abandonado. Limpo quando o carrinho é atualizado de novo.

- `converted_at` (string | null): Quando o carrinho foi convertido.

- `converted_order_id` (string | null): O pedido (`ord_...`) que converteu o carrinho.

- `created_at, updated_at` (string): Quando o carrinho foi armazenado pela primeira vez e quando mudou pela última vez, em ISO 8601 UTC.

**Requisição** `GET /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "abandoned",
  "currency": "USD",
  "total": 107,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "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,
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": "2026-10-08T13:31:04.118Z",
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:28:51.902Z"
}
```

**404**

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

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

## Listar carrinhos — GET /carts

> Liste os carrinhos, dos atualizados mais recentemente para os mais antigos, filtrados por status ou contato. Alfa: aberto apenas à equipe do Emailit.

# Listar carrinhos

Lista os carrinhos, dos atualizados 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 /carts`

## 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 carrinhos a retornar (mínimo: 1, máximo: 100, padrão: 25).

- `status` (string): Só os carrinhos com este status: `active`, `abandoned` ou `converted`.

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

- `match`, `order`, `direction`: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

## Filtros e ordenação

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

## Retorno

Uma página de [objetos de carrinho](/pt/docs/api-reference/carts/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 os seus filtros de novo quando segui-las.
**Requisição** `GET /carts`

**cURL**

```bash
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "cart",
      "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
      "external_id": "c-58f1a2",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "abandoned",
      "currency": "USD",
      "total": 89,
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": "42-blue",
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
      "source": "api",
      "abandoned_at": "2026-10-08T13:31:04.118Z",
      "converted_at": null,
      "converted_order_id": null,
      "created_at": "2026-10-08T12:12:47.630Z",
      "updated_at": "2026-10-08T12:28:51.902Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Excluir um carrinho — DELETE /carts/{id}

> Exclua um carrinho. Alfa: aberto apenas à equipe do Emailit.

# Excluir um carrinho

Exclui um carrinho. Os pedidos que o converteram não são afetados. Se você enviar de novo um carrinho com o mesmo `id`, ele é armazenado como um carrinho novo. 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 /carts/{id}`

## Parâmetros de caminho

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

**Requisição** `DELETE /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "deleted": true
}
```

**404**

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

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