Programme de fidélité par paliers

Cas d'usage événements personnalisés + données personnalisées · Pour les boutiques avec un programme de fidélité à paliers (Bronze, Silver, Gold, Platinum) qui veulent déclencher des scénarios marketing en temps réel sur les événements du programme : gain de points, changement de palier, points à expirer.
Cette page modélise le programme au niveau API. Pour le packager en intégration hébergée avec le kit, voir l'exemple programme de fidélité.

Le besoin métier

Votre programme de fidélité attribue des points à chaque achat (ou action de gamification : parrainage, avis client, abonnement newsletter) et fait monter/descendre vos clients sur 4 paliers : Bronze, Silver, Gold, Platinum. Chaque palier débloque des avantages (livraison offerte, code promo permanent, accès anticipé aux ventes privées).

Vous voulez utiliser ShopiMind pour :

Notifier le client en temps réel quand il gagne des points (« +50 points pour votre commande, solde = 1290 pts »).
Féliciter le client lors du passage à un palier supérieur (« Vous êtes désormais Gold 🎉 »).
Rattraper un client qui rétrograde (« Encore 30 jours pour reconquérir votre statut Gold »).
Rappeler au client ses points sur le point d'expirer (« 500 points expirent dans 7 jours »).

La solution ShopiMind

Trois briques combinées :

Une définition « LoyaltyAccount » (donnée personnalisée) qui stocke l'état courant du compte fidélité : solde, palier, date d'entrée dans le palier. Utile pour la segmentation et l'affichage dynamique dans les messages.
Plusieurs types d'événements déclarés via createEvent, un par moment-clé du programme.
Des scénarios d'automatisation configurés côté dashboard ShopiMind, abonnés aux événements et qui personnalisent leur contenu avec les attributs LoyaltyAccount.

Le modèle de données

Définition « LoyaltyAccount »

L'état courant du programme pour un contact. Une ligne par client inscrit.

contact_id (number) — relation vers l'entité Contact.
points_balance (number) — solde courant en points.
tier (text) — Bronze, Silver, Gold ou Platinum.
tier_since (date) — date d'entrée dans le palier courant.
next_expiry_date (date) — date d'expiration du prochain lot de points.
next_expiry_amount (number) — nombre de points qui vont expirer à cette date.
Clé d'unicité : contact_id — un compte fidélité par contact.

Types d'événements

`code_name`	Déclenché par votre système	`metaData`
`loyalty.points_earned`	À chaque gain de points (achat, parrainage, etc.)	`points_amount`, `reason`, `new_balance`
`loyalty.tier_upgraded`	Passage à un palier supérieur	`previous_tier`, `new_tier`
`loyalty.tier_downgraded`	Passage à un palier inférieur	`previous_tier`, `new_tier`, `grace_period_days`
`loyalty.points_expiring`	X jours avant expiration d'un lot	`points_at_risk`, `expiry_date`

Mise en place

1. Créer la définition « LoyaltyAccount »

bash

curl -X POST 'https://core.shopimind.com/v1/custom-data-definitions' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "LoyaltyAccount",
    "description": "Etat courant du programme de fidelite pour un contact",
    "unique_keys": ["contact_id"],
    "fields": [
      { "name": "contact_id",         "label": "Contact",            "type": "number", "required": true  },
      { "name": "points_balance",     "label": "Solde points",       "type": "number", "required": true  },
      { "name": "tier",               "label": "Palier",             "type": "text",   "required": true  },
      { "name": "tier_since",         "label": "Palier depuis",      "type": "date",   "required": false },
      { "name": "next_expiry_date",   "label": "Prochaine expir.",   "type": "date",   "required": false },
      { "name": "next_expiry_amount", "label": "Points en risque",   "type": "number", "required": false }
    ],
    "relationships": [
      { "sourceField": "contact_id", "targetSchemaType": "system", "targetSchema": "contacts", "targetField": "id_contact" }
    ]
  }'

Notez l'id_definition retourné — disons 312.

2. Déclarer les types d'événements

Un appel par type d'événement. Les code_name choisis ici suivent la notation Resource.Action recommandée — vous pouvez aussi utiliser _ comme séparateur.

bash

# 1/ Gain de points
curl -X POST 'https://core.shopimind.com/v1/events' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Fidelite — points gagnes",
    "code_name": "loyalty.points_earned",
    "properties": {
      "metaData": [
        { "name": "points_amount", "type": "number", "required": true,
          "description": "Nombre de points credites par cette action" },
        { "name": "reason",        "type": "text",   "required": true,
          "description": "purchase | referral | review | newsletter_signup | birthday" },
        { "name": "new_balance",   "type": "number", "required": true,
          "description": "Solde apres credit" }
      ]
    }
  }'

# 2/ Passage de palier (up)
curl -X POST 'https://core.shopimind.com/v1/events' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Fidelite — palier debloque",
    "code_name": "loyalty.tier_upgraded",
    "properties": {
      "metaData": [
        { "name": "previous_tier", "type": "text", "required": true },
        { "name": "new_tier",      "type": "text", "required": true }
      ]
    }
  }'

# 3/ Retrogradation
curl -X POST 'https://core.shopimind.com/v1/events' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Fidelite — palier retrograde",
    "code_name": "loyalty.tier_downgraded",
    "properties": {
      "metaData": [
        { "name": "previous_tier",     "type": "text",   "required": true },
        { "name": "new_tier",          "type": "text",   "required": true },
        { "name": "grace_period_days", "type": "number", "required": false,
          "description": "Jours restants pour reconquerir l ancien palier" }
      ]
    }
  }'

# 4/ Points en expiration
curl -X POST 'https://core.shopimind.com/v1/events' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Fidelite — points en expiration",
    "code_name": "loyalty.points_expiring",
    "properties": {
      "metaData": [
        { "name": "points_at_risk", "type": "number", "required": true },
        { "name": "expiry_date",    "type": "date",   "required": true }
      ]
    }
  }'

3. Configurer les scénarios côté dashboard

Dans le dashboard ShopiMind, créez un scénario d'automatisation par moment-clé. Pour chaque scénario :

Choisissez le type de déclencheur « Événement personnalisé » et sélectionnez le code_name correspondant (loyalty.points_earned, loyalty.tier_upgraded, etc.).
Construisez le message en exploitant à la fois le payload de l'événement ({var=metaData.points_amount}, {var=metaData.new_tier}) et les attributs du compte fidélité ({var=LoyaltyAccount.tier}, {var=LoyaltyAccount.points_balance}).

À l'enregistrement, ShopiMind câble automatiquement l'événement au scénario — aucun appel API supplémentaire n'est nécessaire côté votre système.

4. Synchroniser l'état du compte fidélité

À chaque mutation de l'état (idéalement juste avant ou juste après l'émission de l'événement), upsertez le record LoyaltyAccount. La clé d'unicité contact_id garantit que le record existant est mis à jour, pas dupliqué.

bash

curl -X POST 'https://core.shopimind.com/v1/custom-data-records/312' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '[
    {
      "contact_id":         { "by": "id_customer", "value": "CUST-A4521" },
      "points_balance":     1290,
      "tier":               "Gold",
      "tier_since":         "2025-11-12",
      "next_expiry_date":   "2026-12-31",
      "next_expiry_amount": 320
    }
  ]'

Cette synchronisation permet aux scénarios d'afficher le solde et le palier à jour dans leurs messages, et de filtrer/segmenter sur ces attributs.

5. Émettre les événements

À chaque action côté votre système de fidélité, appelez triggerEvent avec le code_name correspondant.

Achat avec gain de points :

bash

curl -X POST 'https://core.shopimind.com/v1/events/trigger/loyalty.points_earned' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "contact": { "email": "marie.dupont@example.com" },
    "metaData": {
      "points_amount": 50,
      "reason":        "purchase",
      "new_balance":   1290
    }
  }'

Passage de palier :

bash

curl -X POST 'https://core.shopimind.com/v1/events/trigger/loyalty.tier_upgraded' \
  -H 'spm-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  --data '{
    "contact": { "email": "marie.dupont@example.com" },
    "metaData": {
      "previous_tier": "Silver",
      "new_tier":      "Gold"
    }
  }'

Tous les scénarios actifs abonnés à ce code_name sont déclenchés en quasi temps réel.

Personnalisation du contenu des messages

Dans le scénario « Passage Gold », vous pouvez combiner le payload de l'événement et les attributs du compte fidélité :

text

Félicitations {var=contact.first_name} !

Vous venez de passer au statut {var=metaData.new_tier} 🎉

Vous bénéficiez désormais de :
- Livraison gratuite sur toutes vos commandes
- 10 % de réduction permanente
- Accès anticipé aux ventes privées

Votre solde actuel : {var=LoyaltyAccount.points_balance} points

ShopiMind résout metaData.* (payload de l'événement courant) et LoyaltyAccount.* (état du compte custom) à la volée — aucune logique conditionnelle dans le template.

Aller plus loin

Diagnostiquer un scénario muet

Si un scénario semble ne pas se déclencher après un triggerEvent :

Vérifiez via listEventHistories que l'événement est bien arrivé (filtre code_name).
Confirmez que la cible (contact ou visitor) a été résolue — un payload avec un email inconnu journalise l'événement mais ne déclenche aucun scénario.
Vérifiez que le scénario est en statut actif côté dashboard.

Récapitulatif

Étape	Endpoint	Quand
Créer définition `LoyaltyAccount`	`createCustomDataDefinition`	Une fois
Déclarer les 4 types d'événements	`createEvent`	Une fois
Synchroniser l'état du compte	`saveCustomDataRecords`	À chaque mutation
Émettre un événement de fidélité	`triggerEvent`	À chaque action utilisateur
Consulter l'historique des déclenchements	`listEventHistories`	Diagnostic

Cas d'usages

Cas d'usages

Programme de fidélité par paliers

Le besoin métier

La solution ShopiMind

Le modèle de données

Définition « LoyaltyAccount »

Types d'événements

Mise en place

1. Créer la définition « LoyaltyAccount »

2. Déclarer les types d'événements

3. Configurer les scénarios côté dashboard

4. Synchroniser l'état du compte fidélité

5. Émettre les événements

Personnalisation du contenu des messages

Aller plus loin

Diagnostiquer un scénario muet

Récapitulatif

Programme de fidélité par paliers ​

Le besoin métier ​

La solution ShopiMind ​

Le modèle de données ​

Définition « LoyaltyAccount » ​

Types d'événements ​

Mise en place ​

1. Créer la définition « LoyaltyAccount » ​

2. Déclarer les types d'événements ​

3. Configurer les scénarios côté dashboard ​

4. Synchroniser l'état du compte fidélité ​

5. Émettre les événements ​

Personnalisation du contenu des messages ​

Aller plus loin ​

Diagnostiquer un scénario muet ​

Récapitulatif ​

Programme de fidélité par paliers

Le besoin métier

La solution ShopiMind

Le modèle de données

Définition « LoyaltyAccount »

Types d'événements

Mise en place

1. Créer la définition « LoyaltyAccount »

2. Déclarer les types d'événements

3. Configurer les scénarios côté dashboard

4. Synchroniser l'état du compte fidélité

5. Émettre les événements

Personnalisation du contenu des messages

Aller plus loin

Diagnostiquer un scénario muet

Récapitulatif