# Commandes API

> Envoyez les commandes de votre boutique pour attribuer le chiffre d’affaires aux e-mails et construire les profils d’achat.

URL de base : `https://api.emailit.com/v2`. Authentifiez-vous avec `Authorization: Bearer <API key>`.

## Créer ou mettre à jour une commande — POST /orders

> Envoyez une commande depuis votre boutique. Emailit attribue les nouvelles commandes à l’e-mail sur lequel l’acheteur a cliqué ou qu’il a ouvert en dernier, met à jour son profil d’achat et émet order.placed. Alpha : réservé à l’équipe Emailit.

# Créer ou mettre à jour une commande

Envoie une commande depuis le backend de votre boutique. La commande est identifiée par son `id` dans votre boutique : si vous renvoyez le même `id`, la commande enregistrée est mise à jour. Nécessite une clé API avec la portée `full` ou `events`. Avec une clé `events`, la réponse ne contient que `object`, `id` et `external_id`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

Quand une commande est enregistrée pour la première fois, Emailit :

- l’attribue à l’e-mail de campagne ou d’automatisation sur lequel l’acheteur a cliqué en dernier pendant la fenêtre de clic précédant `placed_at` ou, sans clic, qu’il a ouvert en dernier pendant la fenêtre d’ouverture. Les fenêtres sont définies dans les [paramètres Commerce](/fr/docs/api-reference/commerce/get-settings/). Consultez [Attribution des commandes aux e-mails](/fr/docs/commerce/#how-orders-are-credited-to-emails).
- la rattache au contact de l’acheteur, et crée le contact si nécessaire (voir `create_contact`).
- marque comme converti le panier désigné par `cart_id`, ainsi que les autres paniers ouverts de l’acheteur mis à jour pour la dernière fois avant la commande.
- marque comme utilisés les codes de réduction correspondants.
- met à jour les métriques d’achat du contact.
- émet [`order.placed`](/fr/docs/webhooks/events/order/placed/), que reçoivent les webhooks et les automatisations.

Envoyer une commande déjà enregistrée la met à jour et émet [`order.updated`](/fr/docs/webhooks/events/order/updated/), avec `previous_status` quand le statut a changé. L’attribution ne change pas. Seuls les champs envoyés changent : `status`, `placed_at`, `currency`, les montants, `coupon_codes`, `cart_id` et `items` gardent leur valeur enregistrée quand vous les omettez, `metadata` est fusionné dans l’objet enregistré, et `total` n’est pas obligatoire. Envoyer `items` remplace tous les articles. Pour ne modifier que le statut ou un remboursement, vous pouvez aussi utiliser [Mettre à jour une commande](/fr/docs/api-reference/orders/update/).

Pour importer des commandes passées sans les attribuer aux e-mails ni démarrer d’automatisation, utilisez [Importer des commandes par lots](/fr/docs/api-reference/orders/batch/).

`POST /orders`

## Corps de la requête

- `id` (string | number, obligatoire): L’ID de la commande dans votre boutique, 255 caractères au maximum. Les nombres sont enregistrés comme des chaînes. Enregistré dans `external_id`. Vous pouvez aussi l’envoyer sous le nom `external_id` ou `order_id`.

- `email` (string): L’adresse e-mail de l’acheteur. Enregistrée en minuscules. Emailit l’utilise pour trouver le contact et pour attribuer la commande à un e-mail envoyé à cette adresse. `customer.email` est aussi accepté.

- `contact_id` (string): Le contact de l’acheteur (`con_...`). Si aucun contact n’a cet ID, Emailit recherche le contact par `email`.

- `first_name` (string): Le prénom de l’acheteur, 191 caractères au maximum. Utilisé quand Emailit crée le contact. `customer.first_name` est aussi accepté.

- `last_name` (string): Le nom de l’acheteur, 191 caractères au maximum. Utilisé quand Emailit crée le contact. `customer.last_name` est aussi accepté.

- `status` (string): `placed` (par défaut), `paid`, `fulfilled`, `canceled` ou `refunded`. La première fois qu’une commande a le statut `paid`, `fulfilled`, `canceled` ou `refunded`, Emailit définit le champ correspondant (`paid_at`, `fulfilled_at`, `canceled_at` ou `refunded_at`) à l’heure actuelle. Les commandes annulées ne comptent pas dans le chiffre d’affaires.

- `currency` (string): Code ISO 4217 à trois lettres. Vaut par défaut la devise de l’espace de travail définie dans les [paramètres Commerce](/fr/docs/api-reference/commerce/get-settings/). Les montants ne sont jamais convertis : les rapports regroupent le chiffre d’affaires par devise.

- `total` (number | string): Total de la commande. Obligatoire pour une nouvelle commande sans articles. Sans lui, Emailit calcule la somme des totaux des articles, moins `discount`, plus `shipping` et `tax`, sans jamais descendre sous 0. Les montants sont des nombres ou des chaînes numériques, ne peuvent pas être négatifs et sont enregistrés avec 4 décimales au maximum.

- `subtotal` (number | string): Montant avant réduction, livraison et taxes. Vaut par défaut la somme des totaux des articles quand la commande a des articles.

- `discount` (number | string): Montant de la réduction, en nombre positif.

- `shipping` (number | string): Montant de la livraison.

- `tax` (number | string): Montant des taxes.

- `refunded_amount` (number | string): Montant remboursé. Vaut `0` par défaut, ou `total` quand `status` vaut `refunded`. Le chiffre d’affaires correspond à `total` moins `refunded_amount`.

- `coupon_codes` (string[]): Les codes de coupon ou de réduction utilisés dans la commande, 20 au maximum. Un code qui correspond à un [code de coupon](/fr/docs/api-reference/coupons/list-codes/) de l’espace de travail, sans tenir compte de la casse, est marqué comme utilisé par cette commande. `coupon_code` et `discount_codes` sont aussi acceptés.

- `cart_id` (string): L’ID du panier ou du paiement (checkout) dans votre boutique dont provient la commande. Le [panier](/fr/docs/api-reference/carts/upsert/) qui a cet ID passe à `converted`.

- `placed_at` (string | number): Date de la commande : une date-heure ISO 8601 ou un horodatage Unix en secondes (les millisecondes fonctionnent aussi). Par défaut : l’heure actuelle. Ne peut pas se situer plus de 24 heures dans le futur. `created_at` est aussi accepté.

- `items` (object[]): Les articles, 250 au maximum. `line_items` est aussi accepté. Chaque article a : - `product_id` (chaîne ou nombre) : l’ID du produit dans votre boutique. Les articles sans `title`, `url`, `image_url` ou `categories` les reprennent du [catalogue](/fr/docs/api-reference/products/create/). `id` est aussi accepté. - `variant_id`, `sku` (chaîne) : 255 caractères au maximum. - `title` (chaîne) : 500 caractères au maximum. Obligatoire quand l’article n’a ni `product_id` ni `sku`. `name` est aussi accepté. - `quantity` (entier) : 1 ou plus. Par défaut : 1. - `price` (nombre ou chaîne) : le prix unitaire. Par défaut : 0. `unit_price` est aussi accepté. - `total` (nombre ou chaîne) : le total de la ligne. Vaut par défaut `price` multiplié par `quantity`. - `categories` (tableau de chaînes) : 50 noms de catégorie au maximum. - `url`, `image_url` (chaîne) : URL `http` ou `https`.

- `metadata` (object): Vos propres données clé-valeur, 16 Ko au maximum en JSON. Lors d’une mise à jour, les clés envoyées sont fusionnées dans l’objet enregistré.

- `create_contact` (boolean): Vaut `true` par défaut : quand aucun contact ne correspond à `contact_id` ou `email`, Emailit en crée un à partir de `email`, `first_name` et `last_name` et émet `contact.created`. Le nouveau contact n’est abonné à aucune liste : les campagnes ne l’atteignent donc pas. Définissez `false` pour ne jamais créer de contact : la commande n’est alors rattachée qu’à un contact qui existe déjà.

- `accepts_marketing` (boolean): Définissez `true`, avec `audience_id`, quand l’acheteur a accepté de recevoir des communications marketing. Emailit abonne alors le contact à cette liste, sauf s’il en fait déjà partie. Par défaut : `false`.

- `audience_id` (string): La liste (`aud_...`) à laquelle abonner l’acheteur quand `accepts_marketing` vaut `true`. Si la liste n’existe pas ou si la limite d’abonnés de votre forfait est atteinte, la commande est tout de même enregistrée et le contact n’est pas abonné.

- `email_id` (string): L’e-mail de campagne (`eml_...`) d’où vient l’acheteur, si votre boutique le suit. Utilisé uniquement pour les nouvelles commandes, et seuls les ID qui commencent par `eml_` sont lus. La commande est attribuée à cet e-mail quand c’est un e-mail de campagne de l’espace de travail et qu’il a reçu un clic pendant la fenêtre de clic précédant la commande ou a été envoyé pendant cette fenêtre. Sinon, Emailit attribue la commande comme d’habitude. `attribution.email_id` est aussi accepté.

## Réponse

Renvoie `201 Created` avec l’[objet commande](/fr/docs/api-reference/orders/get/) quand la commande est nouvelle, ou `200 OK` quand une commande existante a été mise à jour. Renvoie `422` quand un champ n’est pas valide.
**Requête** `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"
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/create/

## Récupérer une commande — GET /orders/{id}

> Récupérez une commande avec ses articles et l’e-mail de campagne ou d’automatisation auquel elle est attribuée. Alpha : réservé à l’équipe Emailit.

# Récupérer une commande

Récupère une commande par son ID Emailit ou par l’ID de commande de votre boutique, avec ses articles et son attribution. Nécessite une clé API avec la portée `full`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Paramètres de chemin

- `id` (string, obligatoire): L’ID de la commande (`ord_...`) ou l’ID de commande de votre boutique (`external_id`). Encodez pour l’URL les ID de boutique qui contiennent des caractères spéciaux.

## L’objet commande

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

- `id` (string): ID de la commande dans Emailit (`ord_...`).

- `external_id` (string): L’ID de la commande dans votre boutique : l’`id` que vous avez envoyé.

- `contact_id` (string | null): Le contact de l’acheteur (`con_...`), ou `null` quand la commande n’est rattachée à aucun contact.

- `email` (string | null): L’adresse e-mail de l’acheteur, en minuscules.

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

- `currency` (string): Code ISO 4217 à trois lettres des montants.

- `subtotal` (number | null): Somme des articles avant réduction, livraison et taxes.

- `discount` (number | null): Montant de la réduction.

- `shipping` (number | null): Montant de la livraison.

- `tax` (number | null): Montant des taxes.

- `total` (number): Total de la commande. Dans les rapports, le chiffre d’affaires correspond à `total` moins `refunded_amount`, et les commandes annulées ne comptent pas.

- `refunded_amount` (number): Montant remboursé jusqu’ici. `0` quand rien n’a été remboursé.

- `coupon_codes` (string[]): Codes de coupon ou de réduction utilisés dans la commande.

- `cart_id` (string | null): L’ID du panier ou du paiement (checkout) dans votre boutique dont provient la commande.

- `source` (string): Comment la commande est arrivée dans Emailit : `api`, `js` (le script de suivi) ou `import` ([import par lots](/fr/docs/api-reference/orders/batch/)).

- `placed_at` (string): Date de la commande, au format ISO 8601 UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): Date à laquelle Emailit a enregistré pour la première fois la commande avec ce statut. Défini une seule fois et pas effacé quand le statut change de nouveau.

- `attribution` (object | null): L’e-mail auquel la commande est attribuée, ou `null`. Défini une seule fois, au premier enregistrement de la commande. Consultez [Attribution des commandes aux e-mails](/fr/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (chaîne) : l’e-mail auquel la commande est attribuée. - `campaign_id`, `campaign_name` (chaîne ou null) : sa campagne. - `variant_id` (chaîne ou null) : la version du test A/B (`cvr_...`) reçue par l’acheteur. - `automation_id`, `automation_name` (chaîne ou null) : son automatisation. - `type` (chaîne) : `click` ou `open`. - `touched_at` (chaîne ou null) : date du clic ou de l’ouverture.

- `items` (object[]): Les articles. Chacun a `product_id` (l’ID du produit dans votre boutique), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` et `image_url`.

- `metadata` (object): Vos propres données clé-valeur.

- `created_at, updated_at` (string): Dates auxquelles Emailit a enregistré la commande et l’a modifiée pour la dernière fois, au format ISO 8601 UTC.

**Requête** `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."
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/get/

## Mettre à jour une commande — POST /orders/{id}

> Modifiez le statut d’une commande, enregistrez un remboursement ou ajoutez des métadonnées, sans renvoyer toute la commande. Alpha : réservé à l’équipe Emailit.

# Mettre à jour une commande

Modifie le statut d’une commande enregistrée, enregistre un remboursement ou ajoute des métadonnées. Tout le reste ne change pas, y compris les articles et l’attribution. Les métriques d’achat de l’acheteur sont recalculées, et Emailit émet [`order.updated`](/fr/docs/webhooks/events/order/updated/), avec le `previous_status` de la commande quand le statut a changé. Nécessite une clé API avec la portée `full` ou `events`. Avec une clé `events`, la réponse ne contient que `object`, `id` et `external_id`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Paramètres de chemin

- `id` (string, obligatoire): L’ID de la commande (`ord_...`) ou l’ID de commande de votre boutique.

## Corps de la requête

Envoyez au moins l’un de ces champs.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` ou `refunded`. La première fois que la commande reçoit le statut `paid`, `fulfilled`, `canceled` ou `refunded`, le champ correspondant (`paid_at`, `fulfilled_at`, `canceled_at` ou `refunded_at`) prend l’heure actuelle. Les commandes annulées ne comptent pas dans le chiffre d’affaires.

- `refunded_amount` (number | string): Montant total remboursé jusqu’ici, pas le montant de ce remboursement. Ne peut pas être négatif. Le chiffre d’affaires correspond à `total` moins `refunded_amount`. Si vous passez `status` à `refunded` sans `refunded_amount` et que rien n’a été remboursé auparavant, tout le `total` compte comme remboursé.

- `metadata` (object): Clés à fusionner dans les métadonnées de la commande. 16 Ko au maximum en JSON.

## Réponse

Renvoie `200 OK` avec l’[objet commande](/fr/docs/api-reference/orders/get/) mis à jour. Renvoie `404` si aucune commande ne correspond à `id` et `422` quand le corps est vide ou qu’un champ n’est pas valide.
**Requête** `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"
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/update/

## Lister les commandes — GET /orders

> Listez les commandes, de la plus récente à la plus ancienne, filtrées par acheteur, statut, période, ou par la campagne ou l’automatisation à laquelle elles sont attribuées. Alpha : réservé à l’équipe Emailit.

# Lister les commandes

Liste les commandes avec leurs articles, les plus récemment passées en premier. Nécessite une clé API avec la portée `full`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Paramètres de requête

- `page` (integer): Numéro de page pour la pagination (minimum : 1, par défaut : 1).

- `limit` (integer): Nombre de commandes à renvoyer (minimum : 1, maximum : 100, par défaut : 25).

- `search` (string): Correspondance insensible à la casse sur l’ID de commande de votre boutique ou l’adresse e-mail de l’acheteur.

- `contact_id` (string): Uniquement les commandes de ce contact (`con_...`).

- `email` (string): Uniquement les commandes avec cette adresse e-mail d’acheteur, sans tenir compte de la casse.

- `status` (string): Uniquement les commandes avec ce statut : `placed`, `paid`, `fulfilled`, `canceled` ou `refunded`.

- `campaign_id` (string): Uniquement les commandes attribuées à cette campagne (`cmp_...`).

- `automation_id` (string): Uniquement les commandes attribuées à cette automatisation (`aut_...`).

- `attributed` (boolean): `true` pour les commandes attribuées à un e-mail, `false` pour celles qui ne le sont pas.

- `from` (string): Uniquement les commandes passées à partir de cette date. Une date ou une date-heure ISO 8601 ; toute autre valeur renvoie `422`.

- `to` (string): Uniquement les commandes passées jusqu’à cette date incluse. Une date ou une date-heure ISO 8601 ; toute autre valeur renvoie `422`.

- `match` (string): `all` (par défaut) exige que chaque filtre `key.condition` corresponde. `or` accepte n’importe lequel d’entre eux. Consultez [Filtrage et tri](/fr/docs/api-reference/filtering/).

- `sort` (string): Clé de tri : `placed_at` (par défaut), `total` ou `created_at`.

- `order` (string): Sens du tri : `asc` ou `desc` (par défaut).

## Filtres

Clés de filtre et de tri : voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

Sur cet endpoint, `order` n’accepte que `asc` ou `desc`. Transmettez la clé de tri dans `sort`, par exemple `sort=total&order=desc`.

## Réponse

Renvoie une page d’[objets commande](/fr/docs/api-reference/orders/get/) dans `data`, avec `total_records`, `next_page_url` et `previous_page_url`. Les URL de page ne contiennent que `page` et `limit` : ajoutez de nouveau votre recherche et vos filtres quand vous les suivez.
**Requête** `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
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/list/

## Importer des commandes par lots — POST /orders/batch

> Envoyez jusqu’à 1 000 commandes en une requête, par exemple votre historique de commandes. Par défaut, les imports ne sont pas attribués aux e-mails et n’émettent pas d’événement de commande. Alpha : réservé à l’équipe Emailit.

# Importer des commandes par lots

Envoie jusqu’à 1 000 commandes en une requête. Utilisez cet endpoint pour importer votre historique de commandes, afin que les métriques d’achat, les segments et les recommandations de produits disposent de données dès le premier jour. Chaque commande suit les règles de [Créer ou mettre à jour une commande](/fr/docs/api-reference/orders/create/) : elle est créée ou mise à jour selon son `id`, les contacts sont créés sauf si `create_contact` vaut `false`, les paniers sont convertis, les codes de réduction sont marqués comme utilisés et les métriques d’achat sont mises à jour. Nécessite une clé API avec la portée `full` ou `events`. Avec une clé `events`, la réponse ne contient que `object`, `id` et `external_id`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

Par défaut, les commandes sont historiques : elles ne sont attribuées à aucun e-mail et Emailit n’émet ni `order.placed` ni `order.updated`, si bien qu’elles ne démarrent pas d’automatisation et n’atteignent pas les webhooks. Les nouveaux contacts émettent tout de même `contact.created`. Les commandes envoyées avec cet endpoint ont `source` défini à `import`, avec ou sans `historical`.

Les commandes non valides sont ignorées et listées dans `rejected` ; les autres sont enregistrées. La requête renvoie tout de même `200`.

`POST /orders/batch`

## Corps de la requête

- `orders` (object[], obligatoire): De 1 à 1 000 commandes, chacune avec les champs de [Créer ou mettre à jour une commande](/fr/docs/api-reference/orders/create/).

- `historical` (boolean): Vaut `true` par défaut : pas d’attribution ni d’événement de commande. Définissez `false` pour traiter les commandes comme des commandes envoyées une par une : les nouvelles commandes sont attribuées aux e-mails et émettent `order.placed`, les commandes mises à jour émettent `order.updated`.

## Réponse

- `created` (integer): Nombre de nouvelles commandes.

- `updated` (integer): Nombre de commandes déjà enregistrées qui ont été mises à jour.

- `rejected` (object[]): Les commandes qui n’ont pas été enregistrées. Chaque élément contient l’`index` de la commande dans votre tableau `orders` et `errors`, dont les clés sont des chemins de champ comme `orders.4.currency`. Une commande qui a passé la validation mais n’a pas pu être enregistrée a l’erreur `could not be stored` sous `orders.<index>`.

Renvoie `422` si `orders` est vide ou contient plus de 1 000 éléments.
**Requête** `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."
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/batch/

## Supprimer une commande — DELETE /orders/{id}

> Supprimez une commande et ses articles, et recalculez les métriques d’achat de l’acheteur. Alpha : réservé à l’équipe Emailit.

# Supprimer une commande

Supprime une commande et ses articles. Les métriques d’achat de l’acheteur sont recalculées sans elle, et son chiffre d’affaires ne compte plus dans les rapports. Les codes de réduction qu’elle a utilisés restent utilisés et les paniers convertis restent convertis. Aucun événement n’est émis. Pour garder la commande sans compter son chiffre d’affaires, passez plutôt son statut à `canceled` avec [Mettre à jour une commande](/fr/docs/api-reference/orders/update/). Nécessite une clé API avec la portée `full`.

> **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Paramètres de chemin

- `id` (string, obligatoire): L’ID de la commande (`ord_...`) ou l’ID de commande de votre boutique.

**Requête** `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."
}
```

---
Source: https://emailit.com/fr/docs/api-reference/orders/delete/