Carritos

Envía los carritos de tus compradores para que Emailit detecte los carritos abandonados.

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

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

Crear o actualizar un carrito

Envía el carrito actual del comprador cada vez que cambie. El carrito se identifica por su id en tu tienda: si vuelves a enviar el mismo id, se actualiza el carrito guardado. Cada llamada sustituye los items y el total del carrito. El email, el contacto, la moneda y la URL de pago se conservan si no los envías. Requiere una clave de API con el permiso full o events. Con una clave events, la respuesta solo contiene object, id y external_id.

El script de seguimiento también puede enviar los carritos desde el navegador.

Un carrito nuevo, o un cambio en los artículos, el total, el estado o el contacto de un carrito, emite cart.updated. Si vuelves a enviar el mismo carrito, no se emite nada.

Cómo pasa un carrito de un estado a otro:

Abandonado. Un carrito que pertenece a un contacto, tiene al menos un artículo y no se actualiza durante los cart_abandon_minutes de la configuración de Comercio electrónico (60 por defecto) pasa a abandoned, y Emailit emite cart.abandoned. Los carritos sin contacto siguen en active.
Activo de nuevo. Al actualizar un carrito abandonado, pasa a active y se borra abandoned_at.
Convertido. Un pedido con el mismo cart_id convierte el carrito. Un pedido nuevo del mismo contacto también convierte los carritos de ese contacto que se actualizaron por última vez antes del pedido. Un carrito convertido sigue convertido aunque lo actualices.

POST/carts

Cuerpo de la petición

idstring | numberObligatorio

El ID del carrito o del pago en tu tienda, de hasta 255 caracteres. Se guarda como external_id. Envía el mismo valor como cart_id en el pedido. También puedes enviarlo como external_id o cart_id.

emailstring

La dirección de email del comprador. Vincula el carrito al contacto con esta dirección. Los carritos nunca crean contactos: un carrito sin un contacto que coincida no puede pasar a abandonado. También se acepta customer.email.

contact_idstring

El contacto del comprador (con_...). Si ningún contacto tiene este ID, Emailit busca el contacto por email.

anonymous_idstring

El ID de visitante del script de seguimiento, de hasta 255 caracteres. Cuando ese visitante se identifica más tarde, los carritos con este ID y sin contacto se vinculan al contacto.

currencystring

El código ISO 4217 de tres letras. Por defecto, la moneda del espacio de trabajo en la configuración de Comercio electrónico.

itemsobject[]

Hasta 250 artículos, con el mismo formato que los items de Crear o actualizar un pedido. Los artículos sin title, url o image_url los toman del catálogo. También se acepta line_items.

totalnumber | string

El valor del carrito. Por defecto, la suma de los totales de los artículos.

checkout_urlstring

Un enlace http o https que devuelve al comprador a este carrito, de hasta 2048 caracteres. Los emails pueden enlazarlo con el bloque de carrito.

statusstring

active (por defecto) o converted. Envía converted para cerrar un carrito tú mismo.

Devuelve

201 Created con el objeto de carrito si el carrito es nuevo, o 200 OK si se ha actualizado un carrito existente. Devuelve 422 si un campo no es vá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"
    ]
  }
}

Obtener un carrito

Obtén un carrito por su ID de Emailit o por el ID del carrito o del pago en tu tienda. Requiere una clave de API con el permiso full.

GET/carts/{id}

Parámetros de ruta

idstringObligatorio

El ID del carrito (crt_...) o el ID del carrito o del pago en tu tienda (external_id). Codifica para URL los ID de tienda que contengan caracteres especiales.

Objeto de carrito

objectstring

Siempre cart.

idstring

El ID de Emailit del carrito (crt_...).

external_idstring

El ID del carrito o del pago en tu tienda: el id que enviaste. Los carritos del script de seguimiento que no tienen ID propio usan web: seguido del ID anónimo del visitante.

contact_idstring | null

El contacto al que pertenece el carrito (con_...), o null mientras no se conoce al comprador.

emailstring | null

La dirección de email del comprador.

statusstring

active: el comprador sigue comprando.
abandoned: el carrito pertenece a un contacto, tiene artículos y no ha cambiado durante los cart_abandon_minutes de la configuración de Comercio electrónico.
converted: se ha realizado un pedido con él, o lo enviaste con status igual a converted.

currencystring | null

El código ISO 4217 de tres letras de los importes.

totalnumber

El valor del carrito.

itemsobject[]

Los artículos. Cada uno tiene product_id (el ID del producto en tu tienda), variant_id, sku, title, quantity, unit_price, total, url e image_url.

checkout_urlstring | null

El enlace que devuelve al comprador a este carrito.

sourcestring

api, o js para los carritos del script de seguimiento.

abandoned_atstring | null

Cuándo se marcó el carrito como abandonado. Se borra cuando el carrito se vuelve a actualizar.

converted_atstring | null

Cuándo se convirtió el carrito.

converted_order_idstring | null

El pedido (ord_...) que convirtió el carrito.

created_at, updated_atstring

Cuándo se guardó el carrito por primera vez y cuándo cambió por última vez, en formato 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 carritos

Lista los carritos, de la actualización más reciente a la más antigua. Requiere una clave de API con el permiso full.

GET/carts

Parámetros de consulta

pageinteger

El número de página (mínimo: 1; por defecto: 1).

limitinteger

El número de carritos que se devuelven (mínimo: 1; máximo: 100; por defecto: 25).

statusstring

Solo los carritos con este estado: active, abandoned o converted.

contact_idstring

Solo los carritos de este contacto (con_...).

matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

Filtros y ordenación

Los filtros de listado son un único nivel de parámetros de consulta key.condition=value. Consulta Filtrado para ver match, order, direction y la lista de condiciones de cada tipo.

Claves de filtro

Clave	Tipo	Condiciones	Notas
`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

Claves de ordenación

Pasa en order una de estas claves y en direction el valor asc o desc: external_id, email, status, total, currency, updated_at, abandoned_at, created_at

Devuelve

Una página de objetos de carrito en data, con total_records, next_page_url y previous_page_url. Las URL de las páginas solo llevan page y limit, así que vuelve a añadir tus filtros cuando las sigas.

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
}

Eliminar un carrito

Elimina un carrito. Los pedidos que lo convirtieron no se ven afectados. Si vuelves a enviar un carrito con el mismo id, se guarda como un carrito nuevo. Requiere una clave de API con el permiso full.

DELETE/carts/{id}

Parámetros de ruta

idstringObligatorio

El ID del carrito (crt_...) o el ID del carrito o del pago en tu tienda.

JSON

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

JSON

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