# Carrelli API

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

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea o aggiorna un carrello — POST /carts

> Invia il carrello attuale dell’acquirente dal tuo negozio. I carrelli inattivi dei contatti noti diventano abbandonati e generano cart.abandoned. Alpha: aperto solo al team di Emailit.

# 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`.

> **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce).

In alternativa, lo [script di tracciamento](/it/docs/commerce/connect-your-shop/#the-tracking-script) può inviare i carrelli dal browser.

Un nuovo carrello, o una modifica ad articoli, totale, stato o contatto di un carrello, genera [`cart.updated`](/it/docs/webhooks/events/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](/it/docs/api-reference/commerce/get-settings/) (60 per impostazione predefinita) diventa `abandoned`, ed Emailit genera [`cart.abandoned`](/it/docs/webhooks/events/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](/it/docs/api-reference/orders/create/) 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

- `id` (string | number, obbligatorio): 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`.

- `email` (string): 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_id` (string): Il contatto dell’acquirente (`con_...`). Se nessun contatto ha questo ID, Emailit cerca il contatto tramite `email`.

- `anonymous_id` (string): 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.

- `currency` (string): Codice ISO 4217 di tre lettere. Il valore predefinito è la valuta del workspace nelle [impostazioni e-commerce](/it/docs/api-reference/commerce/get-settings/).

- `items` (object[]): Fino a 250 righe, nello stesso formato degli `items` di [Crea o aggiorna un ordine](/it/docs/api-reference/orders/create/). Gli articoli senza `title`, `url` o `image_url` li prendono dal [catalogo](/it/docs/api-reference/products/create/). È accettato anche `line_items`.

- `total` (number | string): Valore del carrello. Il valore predefinito è la somma dei totali degli articoli.

- `checkout_url` (string): 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](/it/docs/campaigns/products-and-coupons/#the-cart).

- `status` (string): `active` (predefinito) o `converted`. Invia `converted` per chiudere tu stesso un carrello.

## Restituisce

`201 Created` con l’[oggetto carrello](/it/docs/api-reference/carts/get/) quando il carrello è nuovo, oppure `200 OK` quando è stato aggiornato un carrello esistente. Restituisce `422` quando un campo non è valido.
**Richiesta** `POST /carts`

**cURL**

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

**201**

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

**422**

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

---
Fonte: https://emailit.com/it/docs/api-reference/carts/upsert/

## Recupera un carrello — GET /carts/{id}

> Recupera un carrello tramite il suo ID Emailit o l’ID del carrello o del checkout nel tuo negozio. Alpha: aperto solo al team di Emailit.

# 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`.

> **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce).

`GET /carts/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): 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

- `object` (string): Sempre `cart`.

- `id` (string): ID del carrello in Emailit (`crt_...`).

- `external_id` (string): 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_id` (string | null): Il contatto a cui appartiene il carrello (`con_...`), oppure `null` finché l’acquirente è sconosciuto.

- `email` (string | null): L’indirizzo email dell’acquirente.

- `status` (string): - `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](/it/docs/api-reference/commerce/get-settings/). - `converted`: è stato effettuato un ordine per il carrello, oppure lo hai inviato con `status` impostato su `converted`.

- `currency` (string | null): Codice ISO 4217 di tre lettere degli importi.

- `total` (number): Valore del carrello.

- `items` (object[]): 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_url` (string | null): Link che riporta l’acquirente a questo carrello.

- `source` (string): `api`, oppure `js` per i carrelli dello script di tracciamento.

- `abandoned_at` (string | null): Quando il carrello è stato contrassegnato come abbandonato. Viene azzerato quando il carrello viene aggiornato di nuovo.

- `converted_at` (string | null): Quando il carrello è stato convertito.

- `converted_order_id` (string | null): L’ordine (`ord_...`) che ha convertito il carrello.

- `created_at, updated_at` (string): Quando il carrello è stato salvato per la prima volta e quando è cambiato l’ultima volta, in ISO 8601 UTC.

**Richiesta** `GET /carts/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
```

**200**

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

**404**

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

---
Fonte: https://emailit.com/it/docs/api-reference/carts/get/

## Elenca i carrelli — GET /carts

> Elenca i carrelli, a partire da quello aggiornato più di recente, filtrati per stato o contatto. Alpha: aperto solo al team di Emailit.

# Elenca i carrelli

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

> **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce).

`GET /carts`

## Parametri di query

- `page` (integer): Numero di pagina per la paginazione (minimo: 1, predefinito: 1).

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

- `status` (string): Solo i carrelli con questo stato: `active`, `abandoned` o `converted`.

- `contact_id` (string): Solo i carrelli di questo contatto (`con_...`).

- `match`, `order`, `direction`: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

## Filtri e ordinamento

Chiavi di filtro e di ordinamento: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

## Restituisce

Una pagina di [oggetti carrello](/it/docs/api-reference/carts/get/) 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.
**Richiesta** `GET /carts`

**cURL**

```bash
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
```

**200**

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

---
Fonte: https://emailit.com/it/docs/api-reference/carts/list/

## Elimina un carrello — DELETE /carts/{id}

> Elimina un carrello. Alpha: aperto solo al team di Emailit.

# 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`.

> **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce).

`DELETE /carts/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del carrello (`crt_...`) o l’ID del carrello o del checkout nel tuo negozio.

**Richiesta** `DELETE /carts/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
```

**200**

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

**404**

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

---
Fonte: https://emailit.com/it/docs/api-reference/carts/delete/