Carrelli

Invia i carrelli dei tuoi acquirenti perché Emailit rilevi i carrelli abbandonati.

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

Crea o aggiorna un carrello

Invia il carrello attuale dell’acquirente ogni volta che cambia. Il carrello è identificato dal suo id nel tuo negozio: se invii di nuovo lo stesso id, il carrello salvato viene aggiornato. Ogni chiamata sostituisce items e total del carrello. L’email, il contatto, la valuta e l’URL di checkout vengono mantenuti se li ometti. Richiede una chiave API con il permesso full o events. Con una chiave events, la risposta contiene solo object, id e external_id.

In alternativa, lo script di tracciamento può inviare i carrelli dal browser.

Un nuovo carrello, o una modifica ad articoli, totale, stato o contatto di un carrello, genera cart.updated. Se invii di nuovo lo stesso carrello, non viene generato nulla.

Come un carrello passa da uno stato all’altro:

Abbandonato. Un carrello che appartiene a un contatto, ha almeno un articolo e non viene aggiornato per i cart_abandon_minutes delle impostazioni e-commerce (60 per impostazione predefinita) diventa abandoned, ed Emailit genera cart.abandoned. I carrelli senza contatto restano active.
Di nuovo attivo. Aggiornare un carrello abbandonato lo rende active e azzera abandoned_at.
Convertito. Un ordine con lo stesso cart_id converte il carrello. Un nuovo ordine dello stesso contatto converte anche i carrelli di quel contatto aggiornati l’ultima volta prima dell’ordine. Un carrello convertito resta convertito quando lo aggiorni.

POST/carts

Corpo della richiesta

idstring | numberObbligatorio

L’ID del carrello o del checkout nel tuo negozio, fino a 255 caratteri. Salvato come external_id. Invia lo stesso valore come cart_id nell’ordine. Puoi inviarlo anche come external_id o cart_id.

emailstring

L’indirizzo email dell’acquirente. Collega il carrello al contatto con questo indirizzo. I carrelli non creano mai contatti: un carrello senza un contatto corrispondente non può diventare abbandonato. È accettato anche customer.email.

contact_idstring

Il contatto dell’acquirente (con_...). Se nessun contatto ha questo ID, Emailit cerca il contatto tramite email.

anonymous_idstring

L’ID visitatore dello script di tracciamento, fino a 255 caratteri. Quando in seguito quel visitatore viene identificato, i carrelli con questo ID e senza contatto vengono collegati al contatto.

currencystring

Codice ISO 4217 di tre lettere. Il valore predefinito è la valuta del workspace nelle impostazioni e-commerce.

itemsobject[]

Fino a 250 righe, nello stesso formato degli items di Crea o aggiorna un ordine. Gli articoli senza title, url o image_url li prendono dal catalogo. È accettato anche line_items.

totalnumber | string

Valore del carrello. Il valore predefinito è la somma dei totali degli articoli.

checkout_urlstring

Un link http o https che riporta l’acquirente a questo carrello, fino a 2048 caratteri. Le email possono collegarsi a questo link con il blocco del carrello.

statusstring

active (predefinito) o converted. Invia converted per chiudere tu stesso un carrello.

Restituisce

201 Created con l’oggetto carrello quando il carrello è nuovo, oppure 200 OK quando è stato aggiornato un carrello esistente. Restituisce 422 quando un campo non è valido.

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

Recupera un carrello

Recupera un carrello tramite il suo ID Emailit o l’ID del carrello o del checkout nel tuo negozio. Richiede una chiave API con il permesso full.

GET/carts/{id}

Parametri di percorso

idstringObbligatorio

L’ID del carrello (crt_...) o l’ID del carrello o del checkout nel tuo negozio (external_id). Codifica nell’URL gli ID del negozio che contengono caratteri speciali.

L’oggetto carrello

objectstring

Sempre cart.

idstring

ID del carrello in Emailit (crt_...).

external_idstring

L’ID del carrello o del checkout nel tuo negozio: l’id che hai inviato. I carrelli dello script di tracciamento senza un ID proprio usano web: seguito dall’ID anonimo del visitatore.

contact_idstring | null

Il contatto a cui appartiene il carrello (con_...), oppure null finché l’acquirente è sconosciuto.

emailstring | null

L’indirizzo email dell’acquirente.

statusstring

active: l’acquirente sta ancora facendo acquisti.
abandoned: il carrello appartiene a un contatto, contiene articoli e non è cambiato per i cart_abandon_minutes delle impostazioni e-commerce.
converted: è stato effettuato un ordine per il carrello, oppure lo hai inviato con status impostato su converted.

currencystring | null

Codice ISO 4217 di tre lettere degli importi.

totalnumber

Valore del carrello.

itemsobject[]

Righe del carrello. Ognuna ha product_id (l’ID del prodotto nel tuo negozio), variant_id, sku, title, quantity, unit_price, total, url e image_url.

checkout_urlstring | null

Link che riporta l’acquirente a questo carrello.

sourcestring

api, oppure js per i carrelli dello script di tracciamento.

abandoned_atstring | null

Quando il carrello è stato contrassegnato come abbandonato. Viene azzerato quando il carrello viene aggiornato di nuovo.

converted_atstring | null

Quando il carrello è stato convertito.

converted_order_idstring | null

L’ordine (ord_...) che ha convertito il carrello.

created_at, updated_atstring

Quando il carrello è stato salvato per la prima volta e quando è cambiato l’ultima volta, in 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."
}

Elenca i carrelli

Elenca i carrelli, a partire da quello aggiornato più di recente. Richiede una chiave API con il permesso full.

GET/carts

Parametri di query

pageinteger

Numero di pagina per la paginazione (minimo: 1, predefinito: 1).

limitinteger

Numero di carrelli da restituire (minimo: 1, massimo: 100, predefinito: 25).

statusstring

Solo i carrelli con questo stato: active, abandoned o converted.

contact_idstring

Solo i carrelli di questo contatto (con_...).

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

Filtri e ordinamento

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

Chiave	Tipo	Condizioni	Note
`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	Valori: `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

Chiavi di ordinamento

Passa in order una di queste chiavi e in direction il valore asc o desc: external_id, email, status, total, currency, updated_at, abandoned_at, created_at

Restituisce

Una pagina di oggetti carrello in data, con total_records, next_page_url e previous_page_url. Gli URL delle pagine riportano solo page e limit, quindi aggiungi di nuovo i filtri quando li segui.

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
}

Elimina un carrello

Elimina un carrello. Gli ordini che lo hanno convertito non vengono modificati. Se invii di nuovo un carrello con lo stesso id, viene salvato come nuovo carrello. Richiede una chiave API con il permesso full.

DELETE/carts/{id}

Parametri di percorso

idstringObbligatorio

L’ID del carrello (crt_...) o l’ID del carrello o del checkout nel tuo negozio.

JSON

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

JSON

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