# Ordini API

> Invia gli ordini del tuo negozio per attribuire i ricavi alle email e creare i profili acquisti.

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

## Crea o aggiorna un ordine — POST /orders

> Invia un ordine dal tuo negozio. Emailit attribuisce i nuovi ordini all’email che l’acquirente ha cliccato o aperto per ultima, aggiorna il suo profilo acquisti e genera order.placed. Alpha: aperto solo al team di Emailit.

# Crea o aggiorna un ordine

Invia un ordine dal backend del negozio. L’ordine è identificato dal suo `id` nel tuo negozio: se invii di nuovo lo stesso `id`, l’ordine salvato viene aggiornato. 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).

Quando un ordine viene salvato per la prima volta, Emailit:

- lo attribuisce all’email di campagna o di automazione che l’acquirente ha cliccato per ultima entro la finestra dei clic prima di `placed_at` oppure, senza un clic, che ha aperto per ultima entro la finestra delle aperture. Le finestre si trovano nelle [impostazioni e-commerce](/it/docs/api-reference/commerce/get-settings/). Vedi [Come gli ordini vengono attribuiti alle email](/it/docs/commerce/#how-orders-are-credited-to-emails).
- lo collega al contatto dell’acquirente e, se serve, crea il contatto (vedi `create_contact`).
- contrassegna come convertito il carrello indicato in `cart_id`, insieme agli altri carrelli aperti dell’acquirente aggiornati l’ultima volta prima dell’ordine.
- contrassegna come utilizzati i codici coupon corrispondenti.
- aggiorna le metriche di acquisto del contatto.
- genera [`order.placed`](/it/docs/webhooks/events/order/placed/), che ricevono i webhook e le automazioni.

Se invii un ordine già salvato, l’ordine viene aggiornato e viene generato [`order.updated`](/it/docs/webhooks/events/order/updated/), con `previous_status` quando lo stato è cambiato. L’attribuzione non cambia. Cambiano solo i campi che invii: `status`, `placed_at`, `currency`, gli importi, `coupon_codes`, `cart_id` e `items` mantengono i valori salvati se li ometti, `metadata` viene unito all’oggetto salvato e `total` non è obbligatorio. Se invii `items`, tutti gli articoli vengono sostituiti. Per cambiare solo lo stato o un rimborso puoi usare anche [Aggiorna un ordine](/it/docs/api-reference/orders/update/).

Per importare ordini passati senza attribuirli alle email né avviare automazioni, usa [Importa ordini in blocco](/it/docs/api-reference/orders/batch/).

`POST /orders`

## Corpo della richiesta

- `id` (string | number, obbligatorio): L’ID dell’ordine nel tuo negozio, fino a 255 caratteri. I numeri vengono salvati come stringhe. Salvato come `external_id`. Puoi inviarlo anche come `external_id` o `order_id`.

- `email` (string): L’indirizzo email dell’acquirente. Salvato in minuscolo. Emailit lo usa per trovare il contatto e per attribuire l’ordine a un’email inviata a quell’indirizzo. È accettato anche `customer.email`.

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

- `first_name` (string): Il nome dell’acquirente, fino a 191 caratteri. Usato quando Emailit crea il contatto. È accettato anche `customer.first_name`.

- `last_name` (string): Il cognome dell’acquirente, fino a 191 caratteri. Usato quando Emailit crea il contatto. È accettato anche `customer.last_name`.

- `status` (string): `placed` (predefinito), `paid`, `fulfilled`, `canceled` o `refunded`. La prima volta che un ordine ha `paid`, `fulfilled`, `canceled` o `refunded`, Emailit imposta il corrispondente `paid_at`, `fulfilled_at`, `canceled_at` o `refunded_at` all’ora attuale. Gli ordini annullati non rientrano nei ricavi.

- `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/). Gli importi non vengono mai convertiti: i report raggruppano i ricavi per valuta.

- `total` (number | string): Totale dell’ordine. Obbligatorio per un nuovo ordine senza articoli. Se manca, Emailit calcola la somma dei totali degli articoli, meno `discount`, più `shipping` e `tax`, e mai sotto 0. Gli importi sono numeri o stringhe numeriche, non possono essere negativi e vengono salvati con al massimo 4 cifre decimali.

- `subtotal` (number | string): Importo prima di sconto, spedizione e imposte. Il valore predefinito è la somma dei totali degli articoli, quando l’ordine ha articoli.

- `discount` (number | string): Importo dello sconto, come numero positivo.

- `shipping` (number | string): Importo della spedizione.

- `tax` (number | string): Importo delle imposte.

- `refunded_amount` (number | string): Importo rimborsato. Il valore predefinito è `0`, oppure `total` quando `status` è `refunded`. I ricavi sono `total` meno `refunded_amount`.

- `coupon_codes` (string[]): Fino a 20 codici coupon o codici sconto usati nell’ordine. Un codice che corrisponde a un [codice coupon](/it/docs/api-reference/coupons/list-codes/) del workspace, senza distinzione tra maiuscole e minuscole, viene contrassegnato come utilizzato da questo ordine. Sono accettati anche `coupon_code` e `discount_codes`.

- `cart_id` (string): L’ID del carrello o del checkout nel tuo negozio da cui proviene l’ordine. Il [carrello](/it/docs/api-reference/carts/upsert/) con questo ID diventa `converted`.

- `placed_at` (string | number): Quando è stato effettuato l’ordine: una data e ora ISO 8601 o un timestamp Unix in secondi (funzionano anche i millisecondi). Il valore predefinito è l’ora attuale. Non può essere più di 24 ore nel futuro. È accettato anche `created_at`.

- `items` (object[]): Fino a 250 righe dell’ordine. È accettato anche `line_items`. Ogni articolo ha: - `product_id` (string o number): l’ID del prodotto nel tuo negozio. Gli articoli senza `title`, `url`, `image_url` o `categories` li prendono dal [catalogo](/it/docs/api-reference/products/create/). È accettato anche `id`. - `variant_id`, `sku` (string): fino a 255 caratteri. - `title` (string): fino a 500 caratteri. Obbligatorio quando l’articolo non ha `product_id` né `sku`. È accettato anche `name`. - `quantity` (integer): 1 o più. Il valore predefinito è 1. - `price` (number o string): il prezzo unitario. Il valore predefinito è 0. È accettato anche `unit_price`. - `total` (number o string): il totale della riga. Il valore predefinito è `price` per `quantity`. - `categories` (string[]): fino a 50 nomi di categoria. - `url`, `image_url` (string): URL `http` o `https`.

- `metadata` (object): Dati chiave-valore tuoi, fino a 16 KB in JSON. Negli aggiornamenti, le chiavi che invii vengono unite all’oggetto salvato.

- `create_contact` (boolean): Predefinito `true`: quando nessun contatto corrisponde a `contact_id` o `email`, Emailit ne crea uno da `email`, `first_name` e `last_name` e genera `contact.created`. Il nuovo contatto non è iscritto a nessuna lista, quindi le campagne non lo raggiungono. Imposta `false` per non creare mai un contatto: in questo caso l’ordine viene collegato solo a un contatto già esistente.

- `accepts_marketing` (boolean): Imposta `true` insieme ad `audience_id` quando l’acquirente ha accettato di ricevere comunicazioni di marketing. Emailit iscrive allora il contatto a quella lista, a meno che il contatto non ne faccia già parte. Predefinito `false`.

- `audience_id` (string): La lista (`aud_...`) a cui iscrivere l’acquirente quando `accepts_marketing` è `true`. Se la lista non esiste o è stato raggiunto il limite di iscritti del piano, l’ordine viene comunque salvato e il contatto non viene iscritto.

- `email_id` (string): L’email di campagna (`eml_...`) da cui proviene l’acquirente, se il tuo negozio la traccia. Usato solo per i nuovi ordini, e vengono letti solo gli ID che iniziano con `eml_`. L’ordine viene attribuito a questa email quando è un’email di campagna del workspace e ha un clic entro la finestra dei clic prima dell’ordine oppure è stata inviata entro quella finestra. Altrimenti Emailit attribuisce l’ordine come di consueto. È accettato anche `attribution.email_id`.

## Restituisce

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

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1042",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "paid",
    "currency": "USD",
    "discount": 10.7,
    "shipping": 5,
    "tax": 0,
    "coupon_codes": ["WELCOME-7KQ2M9XA"],
    "cart_id": "c-58f1a2",
    "placed_at": "2026-10-08T14:32:10Z",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "title": "Trail running shoe", "quantity": 1, "price": 89 },
      { "product_id": "8123456790", "title": "Merino running socks", "quantity": 2, "price": 9 }
    ],
    "metadata": { "channel": "web" },
    "accepts_marketing": true,
    "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV"
  }'
```

**201**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "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": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "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"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**422**

```json
{
  "message": "Validation failed. items.1.quantity: must be a positive integer",
  "errors": {
    "items.1.quantity": [
      "must be a positive integer"
    ]
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/orders/create/

## Recupera un ordine — GET /orders/{id}

> Recupera un ordine con i suoi articoli e l’email di campagna o di automazione a cui è attribuito. Alpha: aperto solo al team di Emailit.

# Recupera un ordine

Recupera un ordine tramite il suo ID Emailit o l’ID dell’ordine nel tuo negozio, con i suoi articoli e la sua attribuzione. 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 /orders/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID dell’ordine (`ord_...`) o l’ID dell’ordine nel tuo negozio (`external_id`). Codifica nell’URL gli ID del negozio che contengono caratteri speciali.

## L’oggetto ordine

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

- `id` (string): ID dell’ordine in Emailit (`ord_...`).

- `external_id` (string): L’ID dell’ordine nel tuo negozio: l’`id` che hai inviato.

- `contact_id` (string | null): Il contatto dell’acquirente (`con_...`), oppure `null` quando l’ordine non è collegato a un contatto.

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

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` o `refunded`.

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

- `subtotal` (number | null): Somma degli articoli prima di sconto, spedizione e imposte.

- `discount` (number | null): Importo dello sconto.

- `shipping` (number | null): Importo della spedizione.

- `tax` (number | null): Importo delle imposte.

- `total` (number): Totale dell’ordine. Nei report i ricavi sono `total` meno `refunded_amount`, e gli ordini annullati non contano.

- `refunded_amount` (number): Importo rimborsato finora. `0` quando non è stato rimborsato nulla.

- `coupon_codes` (string[]): Codici coupon o codici sconto usati nell’ordine.

- `cart_id` (string | null): L’ID del carrello o del checkout nel tuo negozio da cui proviene l’ordine.

- `source` (string): Come l’ordine è arrivato a Emailit: `api`, `js` (lo script di tracciamento) o `import` ([importazione in blocco](/it/docs/api-reference/orders/batch/)).

- `placed_at` (string): Quando è stato effettuato l’ordine, in ISO 8601 UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): Quando Emailit ha salvato per la prima volta l’ordine con quello stato. Viene impostato una sola volta e non viene azzerato quando lo stato cambia di nuovo.

- `attribution` (object | null): L’email a cui è attribuito l’ordine, oppure `null`. Viene impostata una sola volta, quando l’ordine viene salvato per la prima volta. Vedi [Come gli ordini vengono attribuiti alle email](/it/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (string): l’email a cui è attribuito l’ordine. - `campaign_id`, `campaign_name` (string o null): la sua campagna. - `variant_id` (string o null): la versione del test A/B (`cvr_...`) che ha ricevuto l’acquirente. - `automation_id`, `automation_name` (string o null): la sua automazione. - `type` (string): `click` o `open`. - `touched_at` (string o null): quando è avvenuto il clic o l’apertura.

- `items` (object[]): Righe dell’ordine. Ognuna ha `product_id` (l’ID del prodotto nel tuo negozio), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` e `image_url`.

- `metadata` (object): Dati chiave-valore tuoi.

- `created_at, updated_at` (string): Quando Emailit ha salvato l’ordine e quando è cambiato l’ultima volta, in ISO 8601 UTC.

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

**cURL**

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

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "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": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "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"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**404**

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

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

## Aggiorna un ordine — POST /orders/{id}

> Cambia lo stato di un ordine, registra un rimborso o aggiungi metadati, senza inviare di nuovo l’intero ordine. Alpha: aperto solo al team di Emailit.

# Aggiorna un ordine

Cambia lo stato di un ordine salvato, registra un rimborso o aggiungi metadati. Tutto il resto rimane com’è, compresi gli articoli e l’attribuzione. Le metriche di acquisto dell’acquirente vengono ricalcolate ed Emailit genera [`order.updated`](/it/docs/webhooks/events/order/updated/), con il `previous_status` dell’ordine quando lo stato è cambiato. 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).

`POST /orders/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID dell’ordine (`ord_...`) o l’ID dell’ordine nel tuo negozio.

## Corpo della richiesta

Invia almeno uno di questi campi.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` o `refunded`. La prima volta che l’ordine passa a `paid`, `fulfilled`, `canceled` o `refunded`, il corrispondente `paid_at`, `fulfilled_at`, `canceled_at` o `refunded_at` viene impostato all’ora attuale. Gli ordini annullati non rientrano nei ricavi.

- `refunded_amount` (number | string): Importo totale rimborsato finora, non l’importo di questo rimborso. Non può essere negativo. I ricavi sono `total` meno `refunded_amount`. Se imposti `status` su `refunded` senza `refunded_amount` e prima non era stato rimborsato nulla, l’intero `total` viene considerato rimborsato.

- `metadata` (object): Chiavi da unire ai metadati dell’ordine. Fino a 16 KB in JSON.

## Restituisce

`200 OK` con l’[oggetto ordine](/it/docs/api-reference/orders/get/) aggiornato. Restituisce `404` se nessun ordine corrisponde a `id` e `422` quando il corpo è vuoto o un campo non è valido.
**Richiesta** `POST /orders/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/1042 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "refunded_amount": 18 }'
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 18,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "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": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "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"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-10T08:05:39.871Z"
}
```

**404**

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

**422**

```json
{
  "message": "Validation failed. status: is required",
  "errors": {
    "status": [
      "is required"
    ]
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/orders/update/

## Elenca gli ordini — GET /orders

> Elenca gli ordini, a partire dal più recente, filtrati per acquirente, stato, intervallo di date o campagna o automazione a cui sono attribuiti. Alpha: aperto solo al team di Emailit.

# Elenca gli ordini

Elenca gli ordini con i loro articoli, a partire da quello effettuato 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 /orders`

## Parametri di query

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

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

- `search` (string): Corrispondenza sull’ID dell’ordine nel tuo negozio o sull’indirizzo email dell’acquirente, senza distinzione tra maiuscole e minuscole.

- `contact_id` (string): Solo gli ordini di questo contatto (`con_...`).

- `email` (string): Solo gli ordini con questo indirizzo email dell’acquirente, senza distinzione tra maiuscole e minuscole.

- `status` (string): Solo gli ordini con questo stato: `placed`, `paid`, `fulfilled`, `canceled` o `refunded`.

- `campaign_id` (string): Solo gli ordini attribuiti a questa campagna (`cmp_...`).

- `automation_id` (string): Solo gli ordini attribuiti a questa automazione (`aut_...`).

- `attributed` (boolean): `true` per gli ordini attribuiti a un’email, `false` per quelli che non lo sono.

- `from` (string): Solo gli ordini effettuati a partire da questo momento. Una data o una data e ora ISO 8601; qualsiasi altro valore restituisce `422`.

- `to` (string): Solo gli ordini effettuati fino a questo momento compreso. Una data o una data e ora ISO 8601; qualsiasi altro valore restituisce `422`.

- `match` (string): `all` (predefinito) richiede che corrispondano tutti i filtri `key.condition`. Con `or` basta che ne corrisponda uno. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

- `sort` (string): Chiave di ordinamento: `placed_at` (predefinito), `total` o `created_at`.

- `order` (string): Direzione dell’ordinamento: `asc` o `desc` (predefinito).

## Filtri

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

In questo endpoint, `order` accetta solo `asc` o `desc`. Passa la chiave di ordinamento in `sort`, ad esempio `sort=total&order=desc`.

## Restituisce

Una pagina di [oggetti ordine](/it/docs/api-reference/orders/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 la ricerca e i filtri quando li segui.
**Richiesta** `GET /orders`

**cURL**

```bash
curl "https://api.emailit.com/v2/orders?campaign_id=cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN&from=2026-10-01&limit=25" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "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": {
        "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
        "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
        "campaign_name": "October newsletter",
        "variant_id": null,
        "automation_id": null,
        "automation_name": null,
        "type": "click",
        "touched_at": "2026-10-08T09:41:52.000Z"
      },
      "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"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Importa ordini in blocco — POST /orders/batch

> Invia fino a 1000 ordini in una sola richiesta, ad esempio lo storico degli ordini. Per impostazione predefinita le importazioni non vengono attribuite alle email e non generano eventi degli ordini. Alpha: aperto solo al team di Emailit.

# Importa ordini in blocco

Invia fino a 1000 ordini in una sola richiesta. Usalo per importare lo storico degli ordini, così metriche di acquisto, segmenti e prodotti consigliati hanno dati fin dal primo giorno. Ogni ordine segue le regole di [Crea o aggiorna un ordine](/it/docs/api-reference/orders/create/): viene creato o aggiornato in base al suo `id`, i contatti vengono creati a meno che `create_contact` non sia `false`, i carrelli vengono convertiti, i codici coupon vengono contrassegnati come utilizzati e le metriche di acquisto vengono aggiornate. 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).

Per impostazione predefinita gli ordini sono storici: non vengono attribuiti a nessuna email ed Emailit non genera `order.placed` né `order.updated`, quindi non avviano automazioni e non raggiungono i webhook. I nuovi contatti generano comunque `contact.created`. Gli ordini inviati con questo endpoint hanno `source` impostato su `import`, con o senza `historical`.

Gli ordini non validi vengono saltati ed elencati in `rejected`; gli altri vengono salvati. La richiesta restituisce comunque `200`.

`POST /orders/batch`

## Corpo della richiesta

- `orders` (object[], obbligatorio): Da 1 a 1000 ordini, ognuno con i campi di [Crea o aggiorna un ordine](/it/docs/api-reference/orders/create/).

- `historical` (boolean): Predefinito `true`: nessuna attribuzione e nessun evento degli ordini. Imposta `false` per trattare gli ordini come ordini inviati uno alla volta: i nuovi ordini vengono attribuiti alle email e generano `order.placed`, gli ordini aggiornati generano `order.updated`.

## Restituisce

- `created` (integer): Numero di nuovi ordini.

- `updated` (integer): Numero di ordini già salvati che sono stati aggiornati.

- `rejected` (object[]): Ordini che non sono stati salvati. Ogni elemento ha l’`index` dell’ordine nel tuo array `orders` ed `errors`, con chiavi che sono percorsi di campo come `orders.4.currency`. Un ordine che ha superato la convalida ma non è stato possibile salvare ha l’errore `could not be stored` sotto `orders.<index>`.

Restituisce `422` se `orders` è vuoto o ha più di 1000 elementi.
**Richiesta** `POST /orders/batch`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/batch \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "id": "981",
        "email": "ada@example.com",
        "status": "fulfilled",
        "currency": "USD",
        "placed_at": "2026-03-14T10:12:00Z",
        "items": [{ "product_id": "8123456789", "quantity": 1, "price": 89 }]
      },
      {
        "id": "982",
        "email": "grace@example.com",
        "status": "fulfilled",
        "currency": "usd dollars",
        "total": 18,
        "placed_at": "2026-03-15T16:40:00Z"
      }
    ]
  }'
```

**200**

```json
{
  "created": 1,
  "updated": 0,
  "rejected": [
    {
      "index": 1,
      "errors": {
        "orders.1.currency": [
          "must be a three-letter ISO 4217 code, e.g. USD"
        ]
      }
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. orders: Send 1 to 1000 orders.",
  "errors": {
    "orders": [
      "Send 1 to 1000 orders."
    ]
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/orders/batch/

## Elimina un ordine — DELETE /orders/{id}

> Elimina un ordine e i suoi articoli, e ricalcola le metriche di acquisto dell’acquirente. Alpha: aperto solo al team di Emailit.

# Elimina un ordine

Elimina un ordine e i suoi articoli. Le metriche di acquisto dell’acquirente vengono ricalcolate senza l’ordine, e i suoi ricavi non contano più nei report. I codici coupon che ha utilizzato restano utilizzati e i carrelli convertiti restano convertiti. Non viene generato nessun evento. Per mantenere l’ordine ma smettere di contarne i ricavi, imposta invece il suo stato su `canceled` con [Aggiorna un ordine](/it/docs/api-reference/orders/update/). 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 /orders/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID dell’ordine (`ord_...`) o l’ID dell’ordine nel tuo negozio.

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

**cURL**

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

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "deleted": true
}
```

**404**

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

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