> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recuperare i carrelli abbandonati

> Invia un'email di promemoria quando un cliente lascia un carrello e non effettua un ordine nel giorno successivo.

Alla fine avrai un'automazione che aspetta dopo ogni evento carrello, controlla se c'è stato un ordine e invia al cliente un'email con gli articoli rimasti nel carrello.

## Prima di iniziare

- Una API Key con **scrittura su Contatti**, creata in **Impostazioni** → **Team e API Key**. Gli eventi personalizzati dipendono dal permesso sui contatti.
- L'ID del tuo workspace e l'indirizzo della tua istanza Notifuse (`YOUR_HOST` negli esempi).
- Una lista per l'automazione, per esempio la lista della newsletter. Senza lista, un'automazione non può contenere un nodo Email.
- Un provider email impostato per le **Email di marketing**.

## Configurare il recupero dei carrelli

### 1. Invia un evento carrello dal tuo negozio

Quando un cliente crea un carrello, invia un evento personalizzato a `POST /api/customEvents.import`. Il body contiene il tuo `workspace_id` e un array `events` con da 1 a 50 eventi.

Ogni evento richiede:

- `external_id`: l'ID del carrello nel tuo negozio. Un nuovo `external_id` avvia l'automazione. Se invii di nuovo lo stesso, l'evento salvato viene aggiornato e non parte nulla.
- `email`: l'indirizzo del cliente.
- `event_name`: lettere minuscole, numeri, `_`, `.`, `/` e `-`, al massimo 100 caratteri. Questa guida usa `cart.created`.
- `properties`: tutto ciò che l'email mostrerà, per esempio gli articoli e un link per tornare al carrello.

`occurred_at` è facoltativo e per impostazione predefinita vale l'istante attuale. Non dare un `goal_type` all'evento carrello.

**cURL**

```bash
curl -X POST https://YOUR_HOST/api/customEvents.import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "YOUR_WORKSPACE_ID",
    "events": [
      {
        "external_id": "cart_8f3a2c",
        "email": "jane@example.com",
        "event_name": "cart.created",
        "properties": {
          "cart_url": "https://shop.example.com/cart/8f3a2c",
          "total": 89.9,
          "items": [
            { "name": "Linen shirt", "quantity": 1, "price": 59.9 },
            { "name": "Canvas tote", "quantity": 1, "price": 30.0 }
          ]
        }
      }
    ]
  }'
```

**Node.js**

```javascript
const response = await fetch('https://YOUR_HOST/api/customEvents.import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTIFUSE_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspace_id: 'YOUR_WORKSPACE_ID',
    events: [
      {
        external_id: `cart_${cart.id}`,
        email: cart.email,
        event_name: 'cart.created',
        properties: {
          cart_url: cart.url,
          total: cart.total,
          items: cart.items.map((item) => ({
            name: item.name,
            quantity: item.quantity,
            price: item.price
          }))
        }
      }
    ]
  })
})

if (!response.ok) {
  throw new Error(`Notifuse returned ${response.status}: ${await response.text()}`)
}
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://YOUR_HOST/api/customEvents.import",
    headers={"Authorization": f"Bearer {os.environ['NOTIFUSE_API_KEY']}"},
    json={
        "workspace_id": "YOUR_WORKSPACE_ID",
        "events": [
            {
                "external_id": f"cart_{cart['id']}",
                "email": cart["email"],
                "event_name": "cart.created",
                "properties": {
                    "cart_url": cart["url"],
                    "total": cart["total"],
                    "items": [
                        {"name": i["name"], "quantity": i["quantity"], "price": i["price"]}
                        for i in cart["items"]
                    ],
                },
            }
        ],
    },
)
response.raise_for_status()
```

Notifuse non crea un contatto a partire da un evento, e un percorso non può eseguire i suoi passaggi senza contatto. Se il cliente potrebbe non essere ancora un contatto, crealo prima con `POST /api/contacts.upsert`.

L'email mostra il carrello com'era all'arrivo di questo primo evento. Gli aggiornamenti inviati in seguito con lo stesso `external_id` modificano l'evento salvato, ma non il percorso già avviato.

### 2. Invia gli ordini come obiettivi di acquisto

L'automazione cerca un ordine con una condizione **Obiettivo**, e una condizione di questo tipo conta solo gli eventi che hanno un `goal_type`. Invia ogni ordine con `goal_type: "purchase"` e il suo importo in `goal_value`, obbligatorio per gli acquisti.

**cURL**

```bash
curl -X POST https://YOUR_HOST/api/customEvents.import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "YOUR_WORKSPACE_ID",
    "events": [
      {
        "external_id": "order_1042",
        "email": "jane@example.com",
        "event_name": "order.completed",
        "goal_type": "purchase",
        "goal_value": 89.9,
        "properties": { "cart_id": "8f3a2c" }
      }
    ]
  }'
```

**Node.js**

```javascript
await fetch('https://YOUR_HOST/api/customEvents.import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTIFUSE_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspace_id: 'YOUR_WORKSPACE_ID',
    events: [
      {
        external_id: `order_${order.id}`,
        email: order.email,
        event_name: 'order.completed',
        goal_type: 'purchase',
        goal_value: order.total,
        properties: { cart_id: order.cartId }
      }
    ]
  })
})
```

**Python**

```python
requests.post(
    "https://YOUR_HOST/api/customEvents.import",
    headers={"Authorization": f"Bearer {os.environ['NOTIFUSE_API_KEY']}"},
    json={
        "workspace_id": "YOUR_WORKSPACE_ID",
        "events": [
            {
                "external_id": f"order_{order['id']}",
                "email": order["email"],
                "event_name": "order.completed",
                "goal_type": "purchase",
                "goal_value": order["total"],
                "properties": {"cart_id": order["cart_id"]},
            }
        ],
    },
).raise_for_status()
```

Notifuse non collega un ordine a un carrello. La proprietà `cart_id` serve solo per i tuoi archivi.

### 3. Scrivi l'email di promemoria

Crea un template nella categoria **Marketing**. L'evento che ha avviato il percorso è disponibile come `trigger_event`, con le proprietà del carrello sotto `trigger_event.properties`:

```liquid
<p>Hi {{ contact.first_name | default: "there" }}, you left these in your cart:</p>
{% for item in trigger_event.properties.items %}
  <p>{{ item.quantity }} × {{ item.name }}: {{ item.price }}</p>
{% endfor %}
<p><a href="{{ trigger_event.properties.cart_url }}">Back to your cart</a></p>
```

### 4. Crea l'automazione

Vai in **Automazioni** e fai clic su **Nuova automazione**. In **Impostazioni**, a sinistra, scegli la **Lista** e imposta la **Frequenza**:

- **Ogni volta**: ogni nuovo carrello avvia un proprio percorso.
- **Una volta per contatto**: solo il primo carrello in assoluto di un contatto riceve un promemoria.

Sul trigger, imposta **Evento trigger** su **Evento personalizzato** e **Nome Evento** su `cart.created`.

### 5. Aggiungi un Ritardo

Aggiungi un passaggio **Ritardo** dopo il trigger. Imposta **Durata attesa** su 1 e l'unità su **Giorni**.

Il passaggio successivo spiega perché un'attesa di 1 giorno è la più adatta al controllo dell'ordine.

### 6. Aggiungi un Filtro che cerca un ordine

Aggiungi un passaggio **Filtro** dopo il Ritardo e fai clic su **Aggiungi condizioni del filtro**. Aggiungi una **Condizione** di tipo **Obiettivo** e compilala:

- **Il contatto**: **non ha raggiunto**, **Acquisto**.
- **Misura**: **conteggio**, **maggiore o uguale a**, 1.
- **Quando**: **negli ultimi** 1 **giorni**.

Fai clic su **Conferma**. I contatti che soddisfano la condizione seguono il ramo **Si**. Lascia vuoto il ramo **No**: lì termina il percorso di chi ha fatto un ordine.

![Il passaggio Filtro di un'automazione carrello, con la sua condizione e il numero di contatti passati da ciascun ramo](https://www.notifuse.com/docs/assets/screenshots/automation_filter_goal.png)

> [!NOTE]
>
> Il Filtro non può verificare "nessun ordine dopo questo carrello". La finestra dell'obiettivo conta giorni interi a ritroso dal momento in cui il Filtro viene eseguito, e non può partire dall'evento carrello.
>
> Con un Ritardo di 1 giorno e una finestra di 1 giorno, i due coincidono: il Filtro guarda indietro fino a circa il momento in cui è arrivato l'evento carrello. Con un Ritardo più breve e la stessa finestra, il Filtro guarda più indietro del carrello. Con un Ritardo di 4 ore, un cliente che ha ordinato nelle 20 ore prima di creare il carrello viene considerato un acquirente e non riceve il promemoria.
>
> La finestra conta inoltre tutti gli acquisti, quindi anche un ordine di tutt'altro blocca il promemoria.

Nel Filtro puoi anche limitare l'email agli iscritti. I contatti che non sono mai stati nella lista dell'automazione ricevono comunque un'email di marketing: vengono esclusi solo quelli che si sono disiscritti, sono andati in bounce o hanno segnalato un reclamo su quella lista. Per scrivere solo ai membri della lista, aggiungi una condizione **Sottoscrizione lista** accanto all'Obiettivo.

### 7. Aggiungi il passaggio Email e attiva

Aggiungi un passaggio **Email** sul ramo **Si** e scegli il tuo promemoria in **Template email**.

Fai clic su **Attiva**, poi su **Si, attiva**. Solo i carrelli che arrivano da questo momento in poi avviano un percorso.

![Un'automazione di recupero carrelli: trigger su evento personalizzato, ritardo, poi un filtro sugli acquisti recenti](https://www.notifuse.com/docs/assets/screenshots/automation_abandoned_cart.png)

## Verificare che funzioni

1. Durante il test, imposta il Ritardo a qualche minuto, con l'unità **Minuti**.
2. Invia un evento `cart.created` per il tuo indirizzo, con un `external_id` che non hai ancora usato.
3. Apri il tuo contatto in **Contatti**, vai nella scheda **Attività** e scegli il filtro **Eventi**. Dovresti vedere l'evento carrello e "È entrato nell’automazione".
4. Al termine del ritardo arriva il promemoria e l'attività mostra "Ha completato l’automazione".
5. Invia un secondo carrello, poi un evento di acquisto prima che il ritardo finisca. Quel percorso termina al Filtro e non parte nessuna email.

Prima che arrivino i carrelli reali, riporta il Ritardo a 1 giorno.

## Prossimi passi

> [card] [Eventi personalizzati e obiettivi](https://www.notifuse.com/it/docs/features/custom-events.md)
>
> Tipi di obiettivo, rimborsi come valori negativi e campi dell'evento.

> [card] [Riconquistare i clienti inattivi](https://www.notifuse.com/it/docs/guides/win-back-customers.md)
>
> Usa gli stessi obiettivi di acquisto per trovare i clienti che hanno smesso di comprare.

> [card] [Variabili delle automazioni](https://www.notifuse.com/it/docs/features/templates.md#automation-variables)
>
> Tutto ciò che contiene `trigger_event` in un'email di automazione.
