Comprendre les erreurs de renouvellement (rebill errors)

Astuce

Ce guide s’adresse aux développeurs et intégrateurs PrestaShop qui souhaitent comprendre les différents types d’erreurs pouvant survenir lors du renouvellement automatique des abonnements, et comment les diagnostiquer via l’API Ciklik.

Prérequis

• Accès à l’API Ciklik (documentation API)
• Familiarité avec les concepts de rebill (renouvellement automatique)
• Module Ciklik installé et configuré sur PrestaShop

Endpoint API Rebill Errors

L’API Ciklik expose un endpoint dédié aux erreurs de rebill : /api/rebill-errors

Important

Ce endpoint ne liste pas les erreurs de paiement CB (refus de carte, fonds insuffisants, etc.). Ces erreurs sont gérées séparément via le mécanisme de tentatives de prélèvement.

Pour les erreurs de paiement CB, consultez :

• Tentatives de prélèvements : Rebill
• Les erreurs de paiements

Types d’erreurs

L’endpoint rebill-errors couvre exclusivement les erreurs suivantes :

Erreur de stock totale (failed)

Aucun produit de l’abonnement n’était disponible au moment du renouvellement. Aucune commande n’est générée.

{
  "id": 1,
  "type": "failed",
  "created_at": "2026-01-08T06:00:00Z",
  "subscription_id": "uuid-de-l-abonnement",
  "message": "All items out of stock"
}

Comportement :

• Aucune commande n’est créée dans PrestaShop
• L’abonnement reste actif
• L’erreur est loggée et accessible via l’API
• Le rebill sera retenté automatiquement le lendemain, puis chaque jour suivant tant que le stock n’est pas revenu. Une fois le stock rétabli, le renouvellement s’effectue et la date de ce paiement devient la nouvelle date d’échéance (le cycle repart à partir de cette date)

Erreur de stock partielle (partial)

Au moins un produit de l’abonnement était en rupture, mais la commande a été passée avec les produits disponibles.

{
  "id": 432,
  "type": "partial",
  "created_at": "2026-01-08T06:00:00Z",
  "subscription_id": "uuid-de-l-abonnement",
  "message": "Partial stock availability"
}

Comportement :

• La commande est créée avec uniquement les produits disponibles
• Le produit en rupture n’est pas listé dans la réponse d’erreur (limitation connue)
• Pour identifier le produit manquant, comparez le contenu de la commande générée avec le contenu attendu de l’abonnement

Piège courant — Détection des ruptures de stock

PrestaShop ne remonte pas explicitement l’information de rupture de stock au module Ciklik. La détection fonctionne ainsi :

1. Ciklik tente d’ajouter le produit au panier PrestaShop
2. Si le produit n’apparaît pas dans le panier après tentative d’ajout, c’est considéré comme une rupture

C’est un comportement spécifique à l’intégration PrestaShop.

Erreur d’API PrestaShop

Le site PrestaShop a renvoyé une réponse inattendue (réponse HTTP vide, erreur 500, 401, timeout…).

Comportement :

• L’erreur est capturée
• Le rebill est retenté automatiquement 24h plus tard
• L’abonnement reste au statut actif

Piège courant — Réponse HTTP vide

Quand Ciklik tente de créer le panier via le module PrestaShop et reçoit une réponse HTTP vide, cela peut générer un bug silencieux.

Vérifications à effectuer :

• L’IP du serveur Ciklik est bien whitelistée côté hébergeur
• Le pare-feu (iptables, CSF) autorise les connexions
• Le WAF (ModSecurity, Sucuri, Cloudflare) ne bloque pas les requêtes
• Les règles .htaccess n’interfèrent pas

Voir aussi : Rebill et indisponibilité du site PrestaShop

Filtrage par date

Vous pouvez filtrer les erreurs par date pour analyser une période spécifique :

GET /api/rebill-errors?filter[created_at_after]=2026-01-07&filter[created_at_before]=2026-01-09

Données historiques

Information

Les données de l’API rebill-errors ne sont disponibles qu’à partir de décembre 2025 (date d’activation du endpoint).

Avant cette date, les erreurs étaient stockées temporairement, envoyées par rapport email, puis purgées. Il n’y a donc pas d’historique antérieur.

Cas d’usage concrets

Diagnostic d’erreurs récurrentes

Un abonnement échoue systématiquement depuis plusieurs mois :

1. Récupérez les erreurs pour cet abonnement :

   GET /api/rebill-errors?filter[subscription_id]=uuid-abonnement

2. Analysez le type d’erreur :

   • failed → Vérifier le stock du produit dans PrestaShop
   • partial → Comparer la commande générée avec l’abonnement
   • Erreur API → Vérifier les logs serveur PrestaShop

Rapport quotidien des erreurs

Pour identifier les problèmes de la veille :

GET /api/rebill-errors?filter[created_at_after]=2026-01-07&filter[created_at_before]=2026-01-08

FAQ

Q : Pourquoi mon erreur de paiement CB n’apparaît pas dans ce endpoint ?

Les erreurs de paiement CB (refus de carte, fonds insuffisants, etc.) ne sont pas gérées par ce endpoint. Elles passent par le système de tentatives de prélèvement. Consultez Tentatives de prélèvements : Rebill.

Q : Comment savoir quel produit était en rupture lors d’une erreur partial ?

Le produit en rupture n’est pas listé dans l’erreur. Comparez le contenu de la commande générée (via l’API commandes) avec le contenu attendu de l’abonnement (via l’API subscriptions).

Q : Les erreurs sont-elles conservées indéfiniment ?

Oui, depuis l’activation du endpoint en décembre 2025. Les erreurs antérieures n’ont pas été conservées.