Fidélité

Ajouter ou retirer des points de fidélité à un client

POST /v1/customers/{id}/loyalty-points
vpn_key Permission write_loyalty Compte comme une écriture

Ajoute ou retire des points au solde de fidélité d'un client, et renvoie le solde avant et après. Cette adresse demande la permission write_loyalty, distincte de write_customers.

points est un ajustement, pas un solde : envoyez 50 pour ajouter 50 points, -20 pour en retirer 20. Vous n'avez pas à lire le solde avant, ni à calculer le nouveau. Un appel ne peut pas dépasser 1000 points, en plus comme en moins. Le solde ne peut pas devenir négatif ni dépasser 1 000 000 : un ajustement qui le ferait sortir de ces bornes est refusé avec l'erreur points_out_of_range, qui donne le solde actuel. Il n'est jamais arrondi à votre place.

L'en-tête Idempotency-Key est obligatoire sur cette adresse. Comme l'ajustement s'ajoute au solde, une requête renvoyée après une coupure réseau sans cet identifiant ajouterait les points deux fois. Utilisez un identifiant nouveau pour chaque ajustement voulu, et le même identifiant si vous renvoyez la même requête.

motif est obligatoire : dites en quelques mots pourquoi ces points sont ajoutés ou retirés (parrainage, geste commercial, correction). Le titulaire du compte le lit dans son journal des modifications.

Seul le solde actuel change. Les points cumulés depuis l'origine, le nombre d'utilisations et les totaux d'achats reflètent l'activité réelle du client et ne se modifient pas. Les points que valent vos ajustements dépendent du programme du compte : voir GET /v1/loyalty-program. L'ajustement est accepté même si le programme est désactivé. Pour vérifier une requête sans rien modifier, ajoutez ?dry_run=true.

Paramètres

id Obligatoire Identifiant du client (champ id).
Idempotency-Key Obligatoire Obligatoire. Identifiant unique de votre choix (8 à 100 caractères), nouveau pour chaque ajustement.
dry_run Facultatif true pour tout vérifier sans rien modifier : la réponse est celle que vous auriez obtenue, avec meta.dry_run à true.

Corps JSON à envoyer

Champ Type Description
points entier Nombre de points à ajouter (positif) ou à retirer (négatif). Jamais 0. De -1000 à 1000 par appel.
motif texte Raison de l'ajustement, en quelques mots. Obligatoire, 100 caractères au maximum. Elle est inscrite dans le journal des modifications que le titulaire du compte consulte.

Exemple d'appel

curl -X POST "https://api.wanapos.com/v1/customers/1842/loyalty-points" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Idempotency-Key: parrainage-1842-2026-11-11" \
  -H "Content-Type: application/json" \
  -d '{"points":50,"motif":"Parrainage"}'

Réponse en cas de succès (statut 200)

L'ajustement est enregistré.

Champ Type Description
data objet
data.id_client entier Identifiant du client.
data.ajustement entier Nombre de points ajoutés (positif) ou retirés (négatif).
data.points_avant entier Solde de points avant l'ajustement.
data.points_actuels entier Solde de points après l'ajustement.
data.motif texte Raison donnée pour l'ajustement.
meta objet
meta.request_id texte Identifiant de l'appel, à communiquer à l'assistance en cas de problème.
{
    "data": {
        "id_client": 1842,
        "ajustement": 50,
        "points_avant": 120,
        "points_actuels": 170,
        "motif": "Parrainage"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}

Erreurs possibles

  • 400 L'en-tête Idempotency-Key est absent ou mal formé. Codes : idempotency_key_required, idempotency_key_invalid, invalid_json.
  • 401 Clé absente, inconnue ou révoquée. Codes : missing_key, invalid_key.
  • 403 Appel refusé pour ce compte ou cette clé. Codes : api_not_activated, account_not_eligible, access_blocked, missing_scope.
  • 404 L'élément demandé n'existe pas sur ce compte. Code : resource_not_found.
  • 409 L'ajustement ferait passer le solde sous 0 ou au-dessus de 1 000 000. Code : points_out_of_range. Le message donne le solde actuel. Rien n'a été modifié.
  • 422 Données envoyées invalides. Code : validation_failed. Le champ details liste chaque erreur.
  • 429 Quota dépassé. Codes : rate_limited, daily_quota_exceeded, too_many_failed_attempts. L'en-tête Retry-After indique combien de secondes attendre.

Voir toutes les erreurs

Une question ? contact@wanapos.com