# E-commerce API > Le impostazioni e-commerce, il riepilogo dei ricavi e il profilo acquisti di un contatto. URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer `. ## Recupera le impostazioni e-commerce — GET /commerce/settings > Recupera la valuta del workspace, le finestre di attribuzione e il tempo di abbandono del carrello. Alpha: aperto solo al team di Emailit. # Recupera le impostazioni e-commerce Recupera le impostazioni e-commerce del workspace. Un workspace che non le ha mai modificate riceve i valori predefiniti. 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 /commerce/settings` ## L’oggetto impostazioni - `object` (string): Sempre `commerce_settings`. - `currency` (string): Codice ISO 4217 di tre lettere usato per gli ordini e i carrelli che non indicano una valuta. Predefinito `USD`. - `attribution_click_days` (integer): Un nuovo ordine viene attribuito all’email di campagna o di automazione che l’acquirente ha cliccato per ultima entro questo numero di giorni prima dell’ordine. Predefinito `5`. - `attribution_open_days` (integer): Senza un clic, l’ordine viene attribuito all’email che l’acquirente ha aperto per ultima entro questo numero di giorni. Con `0` vengono attribuiti solo i clic. Predefinito `1`. - `cart_abandon_minutes` (integer): Il carrello di un contatto che contiene articoli e non viene aggiornato per questo numero di minuti diventa abbandonato e genera `cart.abandoned`. Predefinito `60`. **Richiesta** `GET /commerce/settings` **cURL** ```bash curl https://api.emailit.com/v2/commerce/settings \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "commerce_settings", "currency": "USD", "attribution_click_days": 5, "attribution_open_days": 1, "cart_abandon_minutes": 60 } ``` --- Fonte: https://emailit.com/it/docs/api-reference/commerce/get-settings/ ## Aggiorna le impostazioni e-commerce — POST /commerce/settings > Cambia la valuta del workspace, le finestre di attribuzione o il tempo di abbandono del carrello. Alpha: aperto solo al team di Emailit. # Aggiorna le impostazioni e-commerce Cambia le impostazioni e-commerce del workspace. Cambiano solo i campi che invii. L’attribuzione viene stabilita quando un ordine viene salvato per la prima volta, quindi le nuove finestre si applicano agli ordini salvati da quel momento in poi. 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). `POST /commerce/settings` ## Corpo della richiesta - `currency` (string): Codice ISO 4217 di tre lettere, come `EUR`. Usato per gli ordini e i carrelli che non indicano una valuta. - `attribution_click_days` (integer): Finestra dei clic in giorni, da 1 a 30. - `attribution_open_days` (integer): Finestra delle aperture in giorni, da 0 a 30. Con `0` vengono attribuiti solo i clic. - `cart_abandon_minutes` (integer): Minuti senza aggiornamenti dopo i quali il carrello di un contatto diventa abbandonato, da 15 a 10.080 (7 giorni). ## Restituisce `200 OK` con tutte le [impostazioni](/it/docs/api-reference/commerce/get-settings/). Restituisce `422` quando un valore è fuori dall’intervallo consentito. **Richiesta** `POST /commerce/settings` **cURL** ```bash 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 }' ``` **200** ```json { "object": "commerce_settings", "currency": "EUR", "attribution_click_days": 5, "attribution_open_days": 0, "cart_abandon_minutes": 120 } ``` **422** ```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." ] } } ``` --- Fonte: https://emailit.com/it/docs/api-reference/commerce/update-settings/ ## Recupera il riepilogo e-commerce — GET /commerce/overview > Ricavi, ricavi dalle email, clienti, carrelli, una serie giornaliera, prodotti principali e campagne principali per un intervallo di date. Alpha: aperto solo al team di Emailit. # Recupera il riepilogo e-commerce Recupera i numeri alla base di **Email Marketing → Commerce** per un intervallo di date. 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). I ricavi sono il totale degli ordini meno i rimborsi, e gli ordini annullati non contano. Gli importi sono raggruppati per valuta e non vengono mai convertiti, quindi la maggior parte dei campi sono liste con una voce per valuta. `GET /commerce/overview` ## Parametri di query - `from` (string): Inizio dell’intervallo, una data o una data e ora ISO 8601. Il valore predefinito è 30 giorni prima di `to`. - `to` (string): Fine dell’intervallo, esclusa. Il valore predefinito è il momento attuale. L’intervallo può durare al massimo 366 giorni. ## Restituisce - `object` (string): Sempre `commerce_overview`. - `from, to` (string): L’intervallo usato, in ISO 8601 UTC. - `totals` (object[]): Tutti gli ordini effettuati nell’intervallo, per valuta, a partire dai ricavi più alti: `currency`, `orders`, `revenue`, `buyers` e `average_order_value`. - `attributed` (object[]): Ordini attribuiti a un’email, per `channel` (`campaigns` o `automations`) e `currency`, con `orders`, `revenue` e `buyers`. - `customers` (object): - `new`: contatti il cui primo ordine è nell’intervallo. - `returning`: contatti il cui primo ordine è precedente a `from` e che hanno ordinato di nuovo da `from` in poi. - `carts` (object): Carrelli aggiornati l’ultima volta nell’intervallo: `active`, `abandoned` e `recovered` (convertiti dopo essere stati abbandonati). `abandoned_by_currency` elenca per ogni `currency` il numero `carts` di carrelli abbandonati e il loro `value` totale, a partire dal valore più alto, e `abandoned_value` e `abandoned_currency` ripetono la prima voce. - `series` (object[]): Una voce per ogni giorno e valuta con ordini: `date` (`YYYY-MM-DD`), `currency`, `orders`, `revenue` e `attributed_revenue`. - `top_products` (object[]): Fino a 10 prodotti per ricavi degli articoli: `product_id` (l’ID del prodotto nel tuo negozio), `title`, `image_url`, `currency`, `quantity` e `revenue`. - `top_campaigns` (object[]): Fino a 5 campagne per ricavi attribuiti: `campaign_id`, `name`, `currency`, `orders` e `revenue`. Restituisce `422` se `from` o `to` non è una data valida, se `from` non è precedente a `to` o se l’intervallo supera i 366 giorni. **Richiesta** `GET /commerce/overview` **cURL** ```bash curl "https://api.emailit.com/v2/commerce/overview?from=2026-09-10&to=2026-10-10" \ -H "Authorization: Bearer your_api_key" ``` **200** ```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 } ] } ``` **422** ```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." ] } } ``` --- Fonte: https://emailit.com/it/docs/api-reference/commerce/overview/ ## Recupera il profilo acquisti di un contatto — GET /contacts/{id}/commerce > Recupera le metriche di acquisto, il rischio di churn, gli ordini recenti, il carrello aperto e i prodotti visti di recente di un contatto. Alpha: aperto solo al team di Emailit. # Recupera il profilo acquisti di un contatto Recupera ciò che un contatto ha acquistato e visto: le metriche di acquisto, i 10 ordini più recenti, il carrello aperto e i prodotti visti di recente. Il pannello mostra gli stessi dati nel riquadro **Purchases** della pagina del contatto. 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 /contacts/{id}/commerce` ## Parametri di percorso - `id` (string, obbligatorio): L’ID del contatto (`con_...`) o l’indirizzo email del contatto. Codifica nell’URL gli indirizzi email. ## Restituisce - `object` (string): Sempre `contact_commerce`. - `contact_id` (string): L’ID del contatto (`con_...`). - `metrics` (object): Metriche di acquisto, ricalcolate a ogni scrittura di un ordine. Contano tutti gli ordini tranne quelli annullati e sottraggono i rimborsi. Quando il contatto ha ordinato in più valute, contano solo gli ordini nella valuta del suo ordine più recente. - `orders_count` (integer), `total_spent` (number), `average_order_value` (number), `currency` (string o null). - `first_order_at`, `last_order_at` (string o null). - `expected_next_order_at` (string o null): l’ultimo ordine più l’intervallo medio tra gli ordini del contatto. Impostato a partire dal secondo ordine. - `churn_risk` (string o null): `low`, `medium` o `high`. Confronta il tempo trascorso dall’ultimo ordine con l’intervallo medio tra gli ordini del contatto (almeno 14 giorni), oppure con 90 giorni dopo un solo ordine. Entro l’intervallo è `low`, fino al doppio dell’intervallo `medium`, oltre `high`. `null` senza ordini. - `last_active_at` (string o null): l’ultima attività sul tuo sito registrata dallo script di tracciamento. - `timezone` (string o null): il fuso orario IANA indicato dal browser del contatto. Usato dagli [invii all’ora locale](/it/docs/api-reference/campaigns/send/). - `orders` (object[]): I 10 [ordini](/it/docs/api-reference/orders/get/) effettuati più di recente dal contatto. - `orders_total` (integer): Numero di ordini del contatto, compresi quelli annullati. Usa [Elenca gli ordini](/it/docs/api-reference/orders/list/) con `contact_id` per scorrerli pagina per pagina. - `open_cart` (object | null): Il [carrello](/it/docs/api-reference/carts/get/) del contatto aggiornato più di recente che è `active` o `abandoned` e contiene articoli, oppure `null`. - `recently_viewed` (object[]): Fino a 12 prodotti che il contatto ha visto negli ultimi 90 giorni, a partire dal più recente, come registrato dallo script di tracciamento. I prodotti archiviati ed esauriti vengono esclusi. Ognuno ha `id` (l’ID del prodotto nel tuo negozio), `title`, `url`, `image_url`, `price`, `price_formatted`, `currency` e `on_sale`. Restituisce `404` se nessun contatto corrisponde a `id`. **Richiesta** `GET /contacts/{id}/commerce` **cURL** ```bash curl https://api.emailit.com/v2/contacts/con_3EwrXnu9OaQWlfI1AyPUUEoYjQs/commerce \ -H "Authorization: Bearer your_api_key" ``` **200** ```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 } ] } ``` **404** ```json { "error": "Contact not found", "message": "Contact not found." } ``` --- Fonte: https://emailit.com/it/docs/api-reference/commerce/contact-commerce/