[deliver]
Article Deliver · 2026-06-04 · Charlotte Rodrigues

API Klaviyo : envoyer des events depuis votre stack

La majorité des guides Klaviyo partent du principe que votre stack technique est Shopify ou WooCommerce. Vous installez le plugin, vous activez la connexion native, tout remonte automatiquement. Mais si vous avez une application SaaS, une plateforme custom, un système de fidélité maison, ou même un checkout développé en interne, cette logique ne s'applique plus.

Pour ces cas, Klaviyo expose une API REST complète qui permet d'envoyer n'importe quel event depuis n'importe quelle source, de profiler vos utilisateurs avec des propriétés custom, et de déclencher des flows depuis votre propre backend. C'est précisément ce que cet article couvre : les fondamentaux techniques pour intégrer Klaviyo dans une stack non standard.

TL;DR

API Klaviyo v3 : les fondamentaux

Authentification : clé privée vs clé publique

Klaviyo distingue deux types de clés, et la confusion entre les deux est la première source d'erreurs sur les intégrations custom.

La clé privée (Private API Key) commence par pk_. Elle donne accès à l'ensemble de l'API server-side : création d'events, gestion de profils, accès aux listes et segments, etc. Cette clé ne doit jamais être exposée côté client. Elle s'utilise dans le header HTTP de chaque requête :

Authorization: Klaviyo-API-Key pk_xxxxxxxxxxxxxxxxxxxx

La clé publique (Public API Key ou Site ID) est à 6 caractères alphanumériques. Elle est conçue pour les appels depuis le navigateur via Klaviyo.js. Elle n'est pas secrète et ne permet pas d'accéder aux données sensibles.

Pour retrouver vos clés : Klaviyo > Settings > API Keys.

Endpoints principaux

L'API v3 est accessible à la base URL https://a.klaviyo.com/api/. Les endpoints les plus utiles pour une intégration custom :

Endpoint Méthode Usage
/api/events/ POST Envoyer un event custom
/api/profiles/ POST/GET/PATCH Créer ou mettre à jour un profil
/api/lists/{list_id}/relationships/profiles/ POST Ajouter un profil à une liste
/api/metric-aggregates/ POST Agréger des métriques

Chaque requête doit inclure le header de révision de l'API :

revision: 2024-10-15

Ce header indique quelle version du schéma vous utilisez. Si vous ne le passez pas, Klaviyo retourne une erreur 400. Vérifiez dans la documentation officielle la révision stable la plus récente au moment de votre implémentation.

Rate limits

Les limites actuelles de l'API Klaviyo v3 sont de 75 requêtes par seconde pour la plupart des endpoints, dont /api/events/. Klaviyo retourne un 429 Too Many Requests en cas de dépassement, avec un header Retry-After indiquant le délai d'attente en secondes.

Pour les intégrations à fort volume (ex : event batch lors d'un import ou d'une migration), l'approche recommandée est d'envoyer les events un par un avec un contrôle de débit côté client, ou de passer par l'endpoint /api/event-bulk-create-jobs/ disponible en v3 pour les ingestions en masse.

Envoyer un event custom : payload et exemples de code

Structure de la payload

Un event Klaviyo v3 suit un format JSON basé sur la spec JSON:API. Voici la structure minimale :

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Completed Onboarding Step"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "user@example.com"
          }
        }
      },
      "properties": {
        "step_name": "profil complété",
        "plan": "pro",
        "nb_jours_depuis_inscription": 3
      },
      "time": "2026-06-04T10:00:00+00:00",
      "value": 0
    }
  }
}

Champs importants :

Exemple Python

import requests
import json

KLAVIYO_API_KEY = "pk_votre_cle_privee"
BASE_URL = "https://a.klaviyo.com/api"

headers = {
    "Authorization": f"Klaviyo-API-Key {KLAVIYO_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "revision": "2024-10-15"
}

payload = {
    "data": {
        "type": "event",
        "attributes": {
            "metric": {
                "data": {
                    "type": "metric",
                    "attributes": {
                        "name": "Completed Onboarding Step"
                    }
                }
            },
            "profile": {
                "data": {
                    "type": "profile",
                    "attributes": {
                        "email": "user@example.com",
                        "first_name": "Alice",
                        "properties": {
                            "plan": "pro"
                        }
                    }
                }
            },
            "properties": {
                "step_name": "profil complété",
                "nb_jours_depuis_inscription": 3
            }
        }
    }
}

response = requests.post(
    f"{BASE_URL}/events/",
    headers=headers,
    data=json.dumps(payload)
)

if response.status_code == 202:
    print("Event envoyé avec succès")
else:
    print(f"Erreur {response.status_code} : {response.text}")

Une réponse 202 Accepted confirme que l'event a été reçu et mis en file de traitement. Klaviyo ne retourne pas de 200 OK pour les events : le 202 est la réponse normale.

Exemple JavaScript (Node.js)

const axios = require('axios');

const KLAVIYO_API_KEY = 'pk_votre_cle_privee';

const payload = {
  data: {
    type: 'event',
    attributes: {
      metric: {
        data: {
          type: 'metric',
          attributes: { name: 'Completed Onboarding Step' }
        }
      },
      profile: {
        data: {
          type: 'profile',
          attributes: { email: 'user@example.com' }
        }
      },
      properties: {
        step_name: 'profil complété',
        plan: 'pro'
      }
    }
  }
};

axios.post('https://a.klaviyo.com/api/events/', payload, {
  headers: {
    'Authorization': `Klaviyo-API-Key ${KLAVIYO_API_KEY}`,
    'Content-Type': 'application/json',
    'revision': '2024-10-15'
  }
})
.then(res => console.log('Event envoyé, status:', res.status))
.catch(err => console.error('Erreur:', err.response?.data));

Exemple cURL

curl -X POST https://a.klaviyo.com/api/events/ \
  -H "Authorization: Klaviyo-API-Key pk_votre_cle_privee" \
  -H "Content-Type: application/json" \
  -H "revision: 2024-10-15" \
  -d '{
    "data": {
      "type": "event",
      "attributes": {
        "metric": {
          "data": {
            "type": "metric",
            "attributes": { "name": "Completed Onboarding Step" }
          }
        },
        "profile": {
          "data": {
            "type": "profile",
            "attributes": { "email": "user@example.com" }
          }
        },
        "properties": { "step_name": "profil complété" }
      }
    }
  }'

Klaviyo.js vs API server-side : quand utiliser quoi

Les deux mécanismes ne s'opposent pas : ils se complètent. Comprendre leurs périmètres respectifs évite les doublons d'events et les erreurs d'authentification.

Klaviyo.js (frontend)

Klaviyo.js est un snippet JavaScript chargé dans le navigateur. Il utilise votre clé publique (Site ID) et expose deux méthodes principales :

Quand l'utiliser : pour les events qui se produisent dans le navigateur et dont vous avez besoin en temps quasi-réel pour déclencher des pop-ups Klaviyo ou des flows immédiats. Exemple : "Viewed Product", "Started Checkout", "Clicked CTA".

Limitations : pas d'accès aux données sensibles, dépendant du JavaScript côté client (ad-blockers, consentement), et la clé publique ne doit pas être utilisée pour des opérations d'écriture massives sur les profils.

API server-side (backend)

L'API v3 avec clé privée est la solution pour tout ce qui se passe côté serveur : actions post-paiement, events liés à des changements d'état dans votre base de données, intégrations avec des systèmes tiers (ERP, CRM, plateforme de fidélité).

Quand l'utiliser :
- Events déclenchés par des actions backend : confirmation de commande, upgrade de plan, activation d'une feature.
- Données sensibles à ne pas exposer au navigateur (valeur d'achat, segment interne).
- Ingestion batch ou migration de données historiques.
- Environnements sans navigateur : applications mobiles via API, scripts d'import, jobs CRON.

Règle simple : si l'event nécessite votre clé privée ou des données que vous ne voulez pas exposer au client, c'est du server-side. Sinon, Klaviyo.js peut suffire.

Webhooks sortants depuis Klaviyo (Flow Webhook action)

Il y a une confusion fréquente sur ce que "webhook Klaviyo" signifie selon le sens de l'échange.

Klaviyo reçoit des events : via l'API Track (ancienne v1) ou l'API v3 /api/events/. C'est ce qu'on vient de décrire. Klaviyo est ici le récepteur.

Klaviyo envoie des données vers votre système : c'est possible via l'action "Webhook" disponible dans les Flows. Klaviyo est alors l'émetteur : il envoie une requête HTTP POST vers votre endpoint à chaque fois qu'un profil atteint ce noeud du flow.

Configurer un webhook sortant dans un Flow

  1. Dans votre Flow, ajoutez une action "Action > Webhook".
  2. Renseignez l'URL de votre endpoint (HTTPS obligatoire).
  3. Définissez les headers si nécessaire (ex : un token d'authentification pour votre API).
  4. Personnalisez le corps du message avec des variables Klaviyo : {{ person.email }}, {{ event.properties.plan }}, etc.

La payload que Klaviyo envoie est du JSON libre que vous composez dans l'interface. Cela vous permet de notifier votre backend lorsqu'un utilisateur entre dans un segment, complète un flow, ou répond à un email.

Exemples d'usage :
- Notifier votre CRM quand un lead télécharge un lead magnet et entre dans la séquence de nurturing.
- Déclencher un ticket support automatique si un client entre dans un flow "churned".
- Mettre à jour un statut dans votre base de données quand un utilisateur clique sur un lien d'activation.

Cas d'usage concrets

SaaS : onboarding progressif

Un SaaS avec un onboarding en 5 étapes peut envoyer un event Completed Onboarding Step à chaque étape complétée, avec une propriété step_number et step_name. Klaviyo déclenche un flow différent selon le step atteint : félicitations, nudge si l'étape suivante n'est pas complétée après 48h, offre de démonstration si l'utilisateur bloque à l'étape 3.

La valeur de cette approche : Klaviyo gère la logique de communication, votre backend n'a qu'à envoyer l'event. Pas de logique d'emailing dans votre code.

DTC : events custom hors Shopify

Une marque DTC avec une plateforme de commande custom peut envoyer des events que Shopify ne propose pas nativement : Subscription Activated, Product Personalized, Gift Message Added. Ces events enrichissent les segments Klaviyo et permettent des automations très précises sans dépendre du catalogue d'events de l'intégration native.

Pour les custom properties sur les profils, voir notre article sur les propriétés custom Klaviyo qui couvre la gestion des champs profil enrichis.

Programme de fidélité

Un système de points maison envoie un event Points Earned avec points_added et total_points à chaque achat. Klaviyo peut déclencher des emails de célébration à chaque palier (500 points, 1 000 points), segmenter les VIP, et envoyer des rappels d'expiration de points.

Le webhook sortant de Klaviyo peut en retour notifier votre système de fidélité quand un utilisateur a consulté l'email de rappel (événement "Opened Email" dans un flow), pour logger l'engagement côté CRM.

Erreurs fréquentes et debugging

401 Unauthorized

Cause la plus fréquente : utilisation de la clé publique (Site ID) à la place de la clé privée pour un appel API server-side. Vérifiez que votre header Authorization commence bien par Klaviyo-API-Key pk_....

400 Bad Request

Souvent lié à :
- Le header revision manquant ou incorrect.
- Un champ mal structuré dans la payload JSON (ex : metric directement à la racine au lieu d'être dans attributes).
- Un email absent du profil sans external_id ou phone_number pour identifier le contact.

Lisez attentivement le corps de la réponse d'erreur : Klaviyo retourne des messages détaillés au format JSON:API avec un tableau errors qui pointe exactement le champ problématique.

202 reçu mais l'event n'apparaît pas dans Klaviyo

Le 202 signifie que l'event est en file de traitement, pas qu'il est déjà visible. Un délai de 1 à 5 minutes est normal. Si l'event n'apparaît pas après 10 minutes :
- Vérifiez dans Klaviyo > Analytics > Metrics que le nom de la métrique correspond exactement.
- Contrôlez que l'email du profil dans la payload est un email valide et non supprimé dans votre compte Klaviyo.
- Vérifiez les logs de votre endpoint : assurez-vous que la requête a bien été envoyée.

Events dupliqués

Si vous envoyez un event depuis le frontend (Klaviyo.js) et depuis votre backend pour la même action, Klaviyo créera deux events distincts. Définissez clairement quel mécanisme est responsable de quel event et documentez-le. Les doublons faussent les métriques et peuvent déclencher des flows en double.

Metric names incohérents

Order Completed, order_completed, OrderCompleted sont trois métriques différentes dans Klaviyo. Standardisez vos noms d'events dès le départ et documentez-les dans un registre partagé avec votre équipe technique. Un changement de nom d'event casse tous les flows et segments qui en dépendent.

Pour aller plus loin

Si votre intégration est complexe (migration de données historiques, système multi-marques, architecture microservices), notre équipe peut auditer votre setup et vous accompagner. Contactez l'agence Deliver pour en discuter.

CR
Charlotte Rodrigues · CRM Lead, Deliver. Une question sur cet article ? charlotte@agence-deliver.com

Besoin d'appliquer ça à votre stack ?

30 minutes avec Charlotte. On audit votre setup CRM en direct, on chiffre l'opportunité, vous repartez avec un plan d'attaque.

Réserver 30 minutes →