E-commerce

As configurações de e-commerce, o resumo de receita e o perfil de compra de um contato.

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

GET/commerce/settings
POST/commerce/settings
GET/commerce/overview
GET/contacts/{id}/commerce

Obter as configurações de e-commerce

Obtém as configurações de e-commerce do workspace. Um workspace que nunca as alterou recebe os valores padrão. Requer uma chave de API com escopo full.

GET/commerce/settings

O objeto de configurações

objectstring

Sempre commerce_settings.

currencystring

Código ISO 4217 de três letras usado nos pedidos e nos carrinhos que não indicam uma moeda. Padrão USD.

attribution_click_daysinteger

Um novo pedido é atribuído ao e-mail de campanha ou de automação em que o comprador clicou por último dentro deste número de dias antes do pedido. Padrão 5.

attribution_open_daysinteger

Sem um clique, o pedido é atribuído ao e-mail que o comprador abriu por último dentro deste número de dias. Com 0, só os cliques são atribuídos. Padrão 1.

cart_abandon_minutesinteger

O carrinho com itens de um contato que não é atualizado durante este número de minutos passa a ser abandonado e emite cart.abandoned. Padrão 60.

JSON

{
  "object": "commerce_settings",
  "currency": "USD",
  "attribution_click_days": 5,
  "attribution_open_days": 1,
  "cart_abandon_minutes": 60
}

Atualizar as configurações de e-commerce

Altera as configurações de e-commerce do workspace. Só mudam os campos que você enviar. A atribuição é definida quando um pedido é armazenado pela primeira vez, então as novas janelas valem para os pedidos armazenados depois. Requer uma chave de API com escopo full.

POST/commerce/settings

Corpo da requisição

currencystring

Código ISO 4217 de três letras, como EUR. Usado nos pedidos e nos carrinhos que não indicam uma moeda.

attribution_click_daysinteger

Janela de cliques em dias, de 1 a 30.

attribution_open_daysinteger

Janela de aberturas em dias, de 0 a 30. Com 0, só os cliques são atribuídos.

cart_abandon_minutesinteger

Minutos sem atualização até o carrinho de um contato passar a ser abandonado, de 15 a 10.080 (7 dias).

Retorno

200 OK com todas as configurações. Retorna 422 quando um valor está fora do intervalo.

POST/commerce/settings

Terminal

curl -X POST https://api.emailit.com/v2/commerce/settings \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "EUR", "attribution_open_days": 0, "cart_abandon_minutes": 120 }'

JSON

{
  "object": "commerce_settings",
  "currency": "EUR",
  "attribution_click_days": 5,
  "attribution_open_days": 0,
  "cart_abandon_minutes": 120
}

JSON

{
  "message": "Validation failed. cart_abandon_minutes: Must be a whole number from 15 to 10080.",
  "errors": {
    "cart_abandon_minutes": [
      "Must be a whole number from 15 to 10080."
    ]
  }
}

Obter o resumo de e-commerce

Obtém os números por trás de Email MarketingCommerce para um período. Requer uma chave de API com escopo full.

A receita é o total do pedido menos os reembolsos, e os pedidos cancelados não contam. Os valores são agrupados por moeda e nunca convertidos, então a maioria dos campos são listas com uma entrada por moeda.

GET/commerce/overview

Parâmetros de consulta

fromstring

Início do período, uma data ou data e hora ISO 8601. O padrão é 30 dias antes de to.

tostring

Fim do período, não incluído. O padrão é o momento atual. O período pode ter até 366 dias.

Retorno

objectstring

Sempre commerce_overview.

from, tostring

O período usado, em ISO 8601 UTC.

totalsobject[]

Todos os pedidos feitos no período, por moeda, da maior receita para a menor: currency, orders, revenue, buyers e average_order_value.

attributedobject[]

Os pedidos atribuídos a um e-mail, por channel (campaigns ou automations) e currency, com orders, revenue e buyers.

customersobject

new: contatos cujo primeiro pedido está no período.
returning: contatos cujo primeiro pedido foi antes de from e que voltaram a comprar desde from.

cartsobject

Os carrinhos atualizados pela última vez no período: active, abandoned e recovered (convertidos depois de abandonados). abandoned_by_currency lista a contagem de carrinhos (carts) e o value total dos carrinhos abandonados por currency, do maior valor para o menor, e abandoned_value e abandoned_currency repetem o primeiro item.

seriesobject[]

Uma entrada por dia e moeda com pedidos: date (YYYY-MM-DD), currency, orders, revenue e attributed_revenue.

top_productsobject[]

Até 10 produtos por receita dos itens: product_id (o ID do produto na sua loja), title, image_url, currency, quantity e revenue.

top_campaignsobject[]

Até 5 campanhas por receita atribuída: campaign_id, name, currency, orders e revenue.

Retorna 422 se from ou to não for uma data válida, se from não for anterior a to ou se o período tiver mais de 366 dias.

JSON

{
  "object": "commerce_overview",
  "from": "2026-09-10T00:00:00.000Z",
  "to": "2026-10-10T00:00:00.000Z",
  "totals": [
    {
      "currency": "USD",
      "orders": 1284,
      "revenue": 108422.6,
      "buyers": 1007,
      "average_order_value": 84.44
    }
  ],
  "attributed": [
    {
      "channel": "campaigns",
      "currency": "USD",
      "orders": 312,
      "revenue": 27140.3,
      "buyers": 288
    },
    {
      "channel": "automations",
      "currency": "USD",
      "orders": 158,
      "revenue": 13981.2,
      "buyers": 149
    }
  ],
  "customers": {
    "new": 604,
    "returning": 403
  },
  "carts": {
    "active": 37,
    "abandoned": 412,
    "recovered": 66,
    "abandoned_value": 35210.8,
    "abandoned_currency": "USD",
    "abandoned_by_currency": [
      { "currency": "USD", "carts": 412, "value": 35210.8 }
    ]
  },
  "series": [
    {
      "date": "2026-10-08",
      "currency": "USD",
      "orders": 51,
      "revenue": 4318.4,
      "attributed_revenue": 1702.9
    },
    {
      "date": "2026-10-09",
      "currency": "USD",
      "orders": 44,
      "revenue": 3720.15,
      "attributed_revenue": 1188.6
    }
  ],
  "top_products": [
    {
      "product_id": "8123456789",
      "title": "Trail running shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
      "currency": "USD",
      "quantity": 214,
      "revenue": 18190
    }
  ],
  "top_campaigns": [
    {
      "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "name": "October newsletter",
      "currency": "USD",
      "orders": 214,
      "revenue": 18364.3
    }
  ]
}

JSON

{
  "message": "Validation failed. from: Use an ISO from/to range of at most 366 days.",
  "errors": {
    "from": [
      "Use an ISO from/to range of at most 366 days."
    ]
  }
}

Obter o perfil de compra de um contato

Obtém o que um contato comprou e navegou: as métricas de compra, os 10 pedidos mais recentes, o carrinho aberto e os produtos vistos recentemente. O painel mostra os mesmos dados no card Purchases da página do contato. Requer uma chave de API com escopo full.

GET/contacts/{id}/commerce

Parâmetros de caminho

idstringObrigatório

O ID do contato (con_...) ou o endereço de e-mail do contato. Codifique os endereços de e-mail para URL.

Retorno

objectstring

Sempre contact_commerce.

contact_idstring

O ID do contato (con_...).

metricsobject

Métricas de compra, recalculadas a cada gravação de pedido. Elas contam todos os pedidos, exceto os cancelados, e descontam os reembolsos. Quando o contato fez pedidos em várias moedas, só contam os pedidos na moeda do pedido mais recente dele.

orders_count (inteiro), total_spent (número), average_order_value (número), currency (string ou null).
first_order_at, last_order_at (string ou null).
expected_next_order_at (string ou null): o último pedido mais o tempo médio do contato entre pedidos. Tem valor a partir do segundo pedido.
churn_risk (string ou null): low, medium ou high. Compara o tempo desde o último pedido com o intervalo médio do contato entre pedidos (no mínimo 14 dias), ou com 90 dias depois de um único pedido. Dentro do intervalo, é low; até o dobro do intervalo, medium; depois disso, high. null sem pedidos.
last_active_at (string ou null): a última atividade que o script de rastreamento registrou no seu site.
timezone (string ou null): o fuso horário IANA informado pelo navegador do contato. Usado pelos envios no horário local.

ordersobject[]

Os 10 pedidos feitos mais recentemente pelo contato.

orders_totalinteger

Número de pedidos do contato, incluindo os cancelados. Use Listar pedidos com contact_id para percorrê-los página por página.

open_cartobject | null

O carrinho atualizado mais recentemente do contato que esteja active ou abandoned e tenha itens, ou null.

recently_viewedobject[]

Até 12 produtos que o contato viu nos últimos 90 dias, dos mais recentes para os mais antigos, conforme registrado pelo script de rastreamento. Os produtos arquivados e sem estoque ficam de fora. Cada um tem id (o ID do produto na sua loja), title, url, image_url, price, price_formatted, currency e on_sale.

Retorna 404 se nenhum contato corresponder a id.

JSON

{
  "object": "contact_commerce",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "metrics": {
    "orders_count": 3,
    "total_spent": 276.3,
    "average_order_value": 92.1,
    "currency": "USD",
    "first_order_at": "2026-03-14T10:12:00.000Z",
    "last_order_at": "2026-10-08T14:32:10.000Z",
    "expected_next_order_at": "2027-01-20T16:42:15.000Z",
    "churn_risk": "low",
    "last_active_at": "2026-10-09T18:03:27.000Z",
    "timezone": "Europe/London"
  },
  "orders": [
    {
      "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": null,
      "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"
    }
  ],
  "orders_total": 3,
  "open_cart": null,
  "recently_viewed": [
    {
      "id": "8123456790",
      "title": "Merino running socks",
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg",
      "price": 9,
      "price_formatted": "$9.00",
      "currency": "USD",
      "on_sale": false
    }
  ]
}

JSON

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