E-commerce

Le impostazioni e-commerce, il riepilogo dei ricavi e il profilo acquisti di un contatto.

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

GET/commerce/settings
POST/commerce/settings
GET/commerce/overview
GET/contacts/{id}/commerce

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.

GET/commerce/settings

L’oggetto impostazioni

objectstring

Sempre commerce_settings.

currencystring

Codice ISO 4217 di tre lettere usato per gli ordini e i carrelli che non indicano una valuta. Predefinito USD.

attribution_click_daysinteger

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_daysinteger

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_minutesinteger

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.

JSON

{
  "object": "commerce_settings",
  "currency": "USD",
  "attribution_click_days": 5,
  "attribution_open_days": 1,
  "cart_abandon_minutes": 60
}

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.

POST/commerce/settings

Corpo della richiesta

currencystring

Codice ISO 4217 di tre lettere, come EUR. Usato per gli ordini e i carrelli che non indicano una valuta.

attribution_click_daysinteger

Finestra dei clic in giorni, da 1 a 30.

attribution_open_daysinteger

Finestra delle aperture in giorni, da 0 a 30. Con 0 vengono attribuiti solo i clic.

cart_abandon_minutesinteger

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. Restituisce 422 quando un valore è fuori dall’intervallo consentito.

POST/commerce/settings

Terminal

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

JSON

{
  "object": "commerce_settings",
  "currency": "EUR",
  "attribution_click_days": 5,
  "attribution_open_days": 0,
  "cart_abandon_minutes": 120
}

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

Recupera il riepilogo e-commerce

Recupera i numeri alla base di Email MarketingCommerce per un intervallo di date. Richiede una chiave API con il permesso full.

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

fromstring

Inizio dell’intervallo, una data o una data e ora ISO 8601. Il valore predefinito è 30 giorni prima di to.

tostring

Fine dell’intervallo, esclusa. Il valore predefinito è il momento attuale. L’intervallo può durare al massimo 366 giorni.

Restituisce

objectstring

Sempre commerce_overview.

from, tostring

L’intervallo usato, in ISO 8601 UTC.

totalsobject[]

Tutti gli ordini effettuati nell’intervallo, per valuta, a partire dai ricavi più alti: currency, orders, revenue, buyers e average_order_value.

attributedobject[]

Ordini attribuiti a un’email, per channel (campaigns o automations) e currency, con orders, revenue e buyers.

customersobject

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.

cartsobject

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.

seriesobject[]

Una voce per ogni giorno e valuta con ordini: date (YYYY-MM-DD), currency, orders, revenue e attributed_revenue.

top_productsobject[]

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_campaignsobject[]

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.

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

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

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.

GET/contacts/{id}/commerce

Parametri di percorso

idstringObbligatorio

L’ID del contatto (con_...) o l’indirizzo email del contatto. Codifica nell’URL gli indirizzi email.

Restituisce

objectstring

Sempre contact_commerce.

contact_idstring

L’ID del contatto (con_...).

metricsobject

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.

ordersobject[]

I 10 ordini effettuati più di recente dal contatto.

orders_totalinteger

Numero di ordini del contatto, compresi quelli annullati. Usa Elenca gli ordini con contact_id per scorrerli pagina per pagina.

open_cartobject | null

Il carrello del contatto aggiornato più di recente che è active o abandoned e contiene articoli, oppure null.

recently_viewedobject[]

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.

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

JSON

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