# Paniers API

> Envoyez les paniers de vos acheteurs pour qu’Emailit détecte les paniers abandonnés.

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

## Créer ou mettre à jour un panier — POST /carts

> Envoyez le panier actuel de l’acheteur depuis votre boutique. Les paniers inactifs des contacts connus deviennent abandonnés et émettent cart.abandoned. Alpha : réservé à l’équipe Emailit.

# Créer ou mettre à jour un panier

Envoyez le panier actuel de l’acheteur chaque fois qu’il change. Le panier est identifié par son `id` dans votre boutique : si vous renvoyez le même `id`, le panier enregistré est mis à jour. Chaque appel remplace les `items` et le `total` du panier. L’adresse e-mail, le contact, la devise et l’URL de paiement sont conservés quand vous les omettez. 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).

Le [script de suivi](/fr/docs/commerce/connect-your-shop/#the-tracking-script) peut envoyer les paniers depuis le navigateur à la place.

Un nouveau panier, ou une modification des articles, du total, du statut ou du contact d’un panier, émet [`cart.updated`](/fr/docs/webhooks/events/cart/updated/). Renvoyer le même panier n’émet rien.

Comment un panier passe d’un statut à l’autre :

- **Abandonné.** Un panier qui appartient à un contact, contient au moins un article et n’est pas mis à jour pendant la durée `cart_abandon_minutes` des [paramètres Commerce](/fr/docs/api-reference/commerce/get-settings/) (60 minutes par défaut) passe à `abandoned`, et Emailit émet [`cart.abandoned`](/fr/docs/webhooks/events/cart/abandoned/). Les paniers sans contact restent `active`.
- **De nouveau actif.** Mettre à jour un panier abandonné le repasse à `active` et efface `abandoned_at`.
- **Converti.** Une [commande](/fr/docs/api-reference/orders/create/) avec le même `cart_id` convertit le panier. Une nouvelle commande du même contact convertit aussi les paniers de ce contact mis à jour pour la dernière fois avant la commande. Un panier converti reste converti quand vous le mettez à jour.

`POST /carts`

## Corps de la requête

- `id` (string | number, obligatoire): L’ID du panier ou du paiement (checkout) dans votre boutique, 255 caractères au maximum. Enregistré dans `external_id`. Envoyez la même valeur dans le `cart_id` de la commande. Vous pouvez aussi l’envoyer sous le nom `external_id` ou `cart_id`.

- `email` (string): L’adresse e-mail de l’acheteur. Rattache le panier au contact qui a cette adresse. Les paniers ne créent jamais de contact : un panier sans contact correspondant ne peut pas devenir abandonné. `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`.

- `anonymous_id` (string): L’ID de visiteur du script de suivi, 255 caractères au maximum. Quand ce visiteur s’identifie plus tard, les paniers qui ont cet ID et aucun contact sont rattachés au contact.

- `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/).

- `items` (object[]): Les articles, 250 au maximum, au même format que les `items` de [Créer ou mettre à jour une commande](/fr/docs/api-reference/orders/create/). Les articles sans `title`, `url` ou `image_url` les reprennent du [catalogue](/fr/docs/api-reference/products/create/). `line_items` est aussi accepté.

- `total` (number | string): Valeur du panier. Vaut par défaut la somme des totaux des articles.

- `checkout_url` (string): Un lien `http` ou `https` qui ramène l’acheteur à ce panier, 2 048 caractères au maximum. Les e-mails peuvent y renvoyer avec le [bloc panier](/fr/docs/campaigns/products-and-coupons/#the-cart).

- `status` (string): `active` (par défaut) ou `converted`. Envoyez `converted` pour clore vous-même un panier.

## Réponse

Renvoie `201 Created` avec l’[objet panier](/fr/docs/api-reference/carts/get/) quand le panier est nouveau, ou `200 OK` quand un panier existant a été mis à jour. Renvoie `422` quand un champ n’est pas valide.
**Requête** `POST /carts`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/carts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "c-58f1a2",
    "email": "ada@example.com",
    "currency": "USD",
    "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "quantity": 1, "price": 89 }
    ]
  }'
```

**201**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "active",
  "currency": "USD",
  "total": 89,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": null,
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:12:47.630Z"
}
```

**422**

```json
{
  "message": "Validation failed. checkout_url: must be an http(s) URL",
  "errors": {
    "checkout_url": [
      "must be an http(s) URL"
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/carts/upsert/

## Récupérer un panier — GET /carts/{id}

> Récupérez un panier par son ID Emailit ou par l’ID du panier ou du paiement dans votre boutique. Alpha : réservé à l’équipe Emailit.

# Récupérer un panier

Récupère un panier par son ID Emailit ou par l’ID du panier ou du paiement (checkout) dans votre boutique. 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 /carts/{id}`

## Paramètres de chemin

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

## L’objet panier

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

- `id` (string): ID du panier dans Emailit (`crt_...`).

- `external_id` (string): L’ID du panier ou du paiement dans votre boutique : l’`id` que vous avez envoyé. Les paniers du script de suivi sans ID propre utilisent `web:` suivi de l’ID anonyme du visiteur.

- `contact_id` (string | null): Le contact auquel appartient le panier (`con_...`), ou `null` tant que l’acheteur est inconnu.

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

- `status` (string): - `active` : l’acheteur fait encore ses achats. - `abandoned` : le panier appartient à un contact, contient des articles et n’a pas changé pendant la durée `cart_abandon_minutes` des [paramètres Commerce](/fr/docs/api-reference/commerce/get-settings/). - `converted` : une commande a été passée pour ce panier, ou vous l’avez envoyé avec `status` défini à `converted`.

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

- `total` (number): Valeur du panier.

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

- `checkout_url` (string | null): Lien qui ramène l’acheteur à ce panier.

- `source` (string): `api`, ou `js` pour les paniers du script de suivi.

- `abandoned_at` (string | null): Date à laquelle le panier a été marqué comme abandonné. Effacé quand le panier est de nouveau mis à jour.

- `converted_at` (string | null): Date à laquelle le panier a été converti.

- `converted_order_id` (string | null): La commande (`ord_...`) qui a converti le panier.

- `created_at, updated_at` (string): Dates auxquelles le panier a été enregistré pour la première fois et modifié pour la dernière fois, au format ISO 8601 UTC.

**Requête** `GET /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "abandoned",
  "currency": "USD",
  "total": 107,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "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,
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": "2026-10-08T13:31:04.118Z",
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:28:51.902Z"
}
```

**404**

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

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

## Lister les paniers — GET /carts

> Listez les paniers, du plus récemment mis à jour au plus ancien, filtrés par statut ou par contact. Alpha : réservé à l’équipe Emailit.

# Lister les paniers

Liste les paniers, les plus récemment mis à jour 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 /carts`

## Paramètres de requête

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

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

- `status` (string): Uniquement les paniers avec ce statut : `active`, `abandoned` ou `converted`.

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

- `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

## Filtres et tri

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

## Réponse

Renvoie une page d’[objets panier](/fr/docs/api-reference/carts/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 vos filtres quand vous les suivez.
**Requête** `GET /carts`

**cURL**

```bash
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "cart",
      "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
      "external_id": "c-58f1a2",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "abandoned",
      "currency": "USD",
      "total": 89,
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": "42-blue",
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
      "source": "api",
      "abandoned_at": "2026-10-08T13:31:04.118Z",
      "converted_at": null,
      "converted_order_id": null,
      "created_at": "2026-10-08T12:12:47.630Z",
      "updated_at": "2026-10-08T12:28:51.902Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Supprimer un panier — DELETE /carts/{id}

> Supprimez un panier. Alpha : réservé à l’équipe Emailit.

# Supprimer un panier

Supprime un panier. Les commandes qui l’ont converti ne sont pas affectées. Si vous renvoyez un panier avec le même `id`, il est enregistré comme un nouveau panier. 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 /carts/{id}`

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du panier (`crt_...`) ou l’ID du panier ou du paiement dans votre boutique.

**Requête** `DELETE /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "deleted": true
}
```

**404**

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

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