Carrinhos

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

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

POST/carts
GET/carts/{id}
GET/carts
DEL/carts/{id}

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 script de rastreamento 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. 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 (60 por padrão) passa a ser abandoned, e o Emailit emite 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 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

idstring | numberObrigató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.

emailstring

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_idstring

O contato do comprador (con_...). Se nenhum contato tiver esse ID, o Emailit procura o contato pelo email.

anonymous_idstring

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.

currencystring

Código ISO 4217 de três letras. O padrão é a moeda do workspace nas configurações de e-commerce.

itemsobject[]

Até 250 itens, no mesmo formato dos items de Criar ou atualizar um pedido. Os itens sem title, url ou image_url recebem esses valores do catálogo. line_items também é aceito.

totalnumber | string

Valor do carrinho. O padrão é a soma dos totais dos itens.

checkout_urlstring

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.

statusstring

active (padrão) ou converted. Envie converted para fechar um carrinho você mesmo.

Retorno

201 Created com o objeto de carrinho quando o carrinho é novo, ou 200 OK quando um carrinho existente foi atualizado. Retorna 422 quando um campo é inválido.

POST/carts

Terminal

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 }
    ]
  }'

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"
}

JSON

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

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.

GET/carts/{id}

Parâmetros de caminho

idstringObrigató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

objectstring

Sempre cart.

idstring

ID do carrinho no Emailit (crt_...).

external_idstring

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_idstring | null

O contato a quem o carrinho pertence (con_...), ou null enquanto o comprador é desconhecido.

emailstring | null

O endereço de e-mail do comprador.

statusstring

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.
converted: um pedido foi feito a partir dele, ou você o enviou com status definido como converted.

currencystring | null

Código ISO 4217 de três letras dos valores.

totalnumber

Valor do carrinho.

itemsobject[]

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_urlstring | null

Link que leva o comprador de volta a este carrinho.

sourcestring

api, ou js para os carrinhos do script de rastreamento.

abandoned_atstring | null

Quando o carrinho foi marcado como abandonado. Limpo quando o carrinho é atualizado de novo.

converted_atstring | null

Quando o carrinho foi convertido.

converted_order_idstring | null

O pedido (ord_...) que converteu o carrinho.

created_at, updated_atstring

Quando o carrinho foi armazenado pela primeira vez e quando mudou pela última vez, em ISO 8601 UTC.

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"
}

JSON

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

Listar carrinhos

Lista os carrinhos, dos atualizados mais recentemente para os mais antigos. Requer uma chave de API com escopo full.

GET/carts

Parâmetros de consulta

pageinteger

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

limitinteger

Número de carrinhos a retornar (mínimo: 1, máximo: 100, padrão: 25).

statusstring

Só os carrinhos com este status: active, abandoned ou converted.

contact_idstring

Só os carrinhos deste contato (con_...).

matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Filtros e ordenação

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

Chave	Tipo	Condições	Observações
`external_id`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`email`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`status`	enum	exact, not_exact	Valores: `active`, `abandoned`, `converted`
`total`	number	exact, not_exact, gt, gte, lt, lte, empty, not_empty
`currency`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`updated_at`	date	exact, before, after, empty, not_empty
`abandoned_at`	date	exact, before, after, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Chaves de ordenação

Passe em order uma destas chaves e em direction o valor asc ou desc: external_id, email, status, total, currency, updated_at, abandoned_at, created_at

Retorno

Uma página de objetos de carrinho 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.

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
}

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.

DELETE/carts/{id}

Parâmetros de caminho

idstringObrigatório

O ID do carrinho (crt_...) ou o ID do carrinho ou do checkout na sua loja.

JSON

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

JSON

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