Comercio electrónico

La configuración de Comercio electrónico, el resumen de ingresos y el perfil de compras de un contacto.

URL basehttps://api.emailit.com/v2Autenticación Errores Límites de velocidad

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

Obtener la configuración de Comercio electrónico

Obtén la configuración de Comercio electrónico del espacio de trabajo. Un espacio de trabajo que nunca la ha cambiado recibe los valores por defecto. Requiere una clave de API con el permiso full.

GET/commerce/settings

Objeto de configuración

objectstring

Siempre commerce_settings.

currencystring

El código ISO 4217 de tres letras que se usa en los pedidos y los carritos que no indican ninguna moneda. Por defecto, USD.

attribution_click_daysinteger

Un pedido nuevo se atribuye al último email de campaña o de automatización en el que el comprador hizo clic dentro de este número de días antes del pedido. Por defecto, 5.

attribution_open_daysinteger

Si no hay ningún clic, el pedido se atribuye al último email que el comprador abrió dentro de este número de días. Con 0 solo se atribuyen los clics. Por defecto, 1.

cart_abandon_minutesinteger

El carrito de un contacto con artículos que no se actualiza durante este número de minutos pasa a estar abandonado y emite cart.abandoned. Por defecto, 60.

JSON

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

Actualizar la configuración de Comercio electrónico

Cambia la configuración de Comercio electrónico del espacio de trabajo. Solo cambian los campos que envías. La atribución se fija cuando un pedido se guarda por primera vez, así que las ventanas nuevas se aplican a los pedidos que se guarden después. Requiere una clave de API con el permiso full.

POST/commerce/settings

Cuerpo de la petición

currencystring

El código ISO 4217 de tres letras, por ejemplo EUR. Se usa en los pedidos y los carritos que no indican ninguna moneda.

attribution_click_daysinteger

La ventana de clic en días, de 1 a 30.

attribution_open_daysinteger

La ventana de apertura en días, de 0 a 30. Con 0 solo se atribuyen los clics.

cart_abandon_minutesinteger

Los minutos sin actualizaciones que deben pasar para que el carrito de un contacto pase a estar abandonado, de 15 a 10.080 (7 días).

Devuelve

200 OK con toda la configuración. Devuelve 422 si un valor está fuera del rango.

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

Obtener el resumen de Comercio electrónico

Obtén las cifras de Email MarketingCommerce para un intervalo de fechas. Requiere una clave de API con el permiso full.

Los ingresos son el total del pedido menos los reembolsos, y los pedidos cancelados no cuentan. Los importes se agrupan por moneda y nunca se convierten, así que la mayoría de los campos son listas con una entrada por moneda.

GET/commerce/overview

Parámetros de consulta

fromstring

El inicio del intervalo, una fecha o una fecha y hora en formato ISO 8601. Por defecto, 30 días antes de to.

tostring

El final del intervalo, no incluido. Por defecto, el momento actual. El intervalo puede durar hasta 366 días.

Devuelve

objectstring

Siempre commerce_overview.

from, tostring

El intervalo usado, en formato ISO 8601 UTC.

totalsobject[]

Todos los pedidos realizados en el intervalo, por moneda, de más a menos ingresos: currency, orders, revenue, buyers y average_order_value.

attributedobject[]

Los pedidos atribuidos a un email, por channel (campaigns o automations) y currency, con orders, revenue y buyers.

customersobject

new: los contactos cuyo primer pedido está en el intervalo.
returning: los contactos cuyo primer pedido fue anterior a from y que han vuelto a comprar desde from.

cartsobject

Los carritos actualizados por última vez en el intervalo: active, abandoned y recovered (convertidos después de abandonarse). abandoned_by_currency indica el número de carritos abandonados (carts) y su value total por currency, de mayor a menor valor, y abandoned_value y abandoned_currency repiten el primero.

seriesobject[]

Una entrada por día y moneda con pedidos: date (YYYY-MM-DD), currency, orders, revenue y attributed_revenue.

top_productsobject[]

Hasta 10 productos según los ingresos de sus artículos: product_id (el ID del producto en tu tienda), title, image_url, currency, quantity y revenue.

top_campaignsobject[]

Hasta 5 campañas según los ingresos atribuidos: campaign_id, name, currency, orders y revenue.

Devuelve 422 si from o to no es una fecha válida, si from no es anterior a to o si el intervalo dura más de 366 días.

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

Obtener el perfil de compras de un contacto

Obtén lo que un contacto ha comprado y visto: las métricas de compra, los 10 pedidos más recientes, el carrito abierto y los productos vistos recientemente. El panel muestra los mismos datos en la tarjeta Purchases de la página del contacto. Requiere una clave de API con el permiso full.

GET/contacts/{id}/commerce

Parámetros de ruta

idstringObligatorio

El ID del contacto (con_...) o la dirección de email del contacto. Codifica para URL las direcciones de email.

Devuelve

objectstring

Siempre contact_commerce.

contact_idstring

El ID del contacto (con_...).

metricsobject

Las métricas de compra, que se recalculan cada vez que se escribe un pedido. Cuentan todos los pedidos salvo los cancelados y restan los reembolsos. Si el contacto ha comprado en varias monedas, solo cuentan los pedidos en la moneda de su último pedido.

orders_count (entero), total_spent (número), average_order_value (número), currency (cadena o null).
first_order_at, last_order_at (cadena o null).
expected_next_order_at (cadena o null): el último pedido más el tiempo medio del contacto entre pedidos. Tiene valor a partir del segundo pedido.
churn_risk (cadena o null): low, medium o high. Compara el tiempo transcurrido desde el último pedido con el intervalo medio del contacto entre pedidos (como mínimo 14 días), o con 90 días si solo hay un pedido. Dentro del intervalo es low, hasta el doble del intervalo es medium y a partir de ahí es high. null si no hay pedidos.
last_active_at (cadena o null): la última actividad en tu web que registró el script de seguimiento.
timezone (cadena o null): la zona horaria IANA que indica el navegador del contacto. La usan los envíos a la hora local.

ordersobject[]

Los 10 pedidos más recientes del contacto.

orders_totalinteger

El número de pedidos del contacto, incluidos los cancelados. Usa Listar pedidos con contact_id para recorrerlos página a página.

open_cartobject | null

El carrito del contacto actualizado más recientemente que está en active o abandoned y tiene artículos, o null.

recently_viewedobject[]

Hasta 12 productos que el contacto ha visto en los últimos 90 días, del más reciente al más antiguo, según el script de seguimiento. Se omiten los productos archivados y los agotados. Cada uno tiene id (el ID del producto en tu tienda), title, url, image_url, price, price_formatted, currency y on_sale.

Devuelve 404 si ningún contacto coincide con 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."
}