Comprendre les erreurs de renouvellement (rebill errors)

PrestaShop

Cette page concerne les boutiques PrestaShop équipées du module Ciklik. Vous avez une boutique box Ciklik ? Voir le parcours box.

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

Attention

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-08 06:00:00",
  "subscription_id": "uuid-de-l-abonnement",
  "order_id": 1234,
  "error_code": null,
  "error_message": null
}

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-08 06:00:00",
  "subscription_id": "uuid-de-l-abonnement",
  "order_id": 1235,
  "error_code": null,
  "error_message": null
}

Comportement :

• La commande est créée avec uniquement les produits disponibles
• Le produit en rupture n’est pas listé dans la réponse de l’API rebill-errors
• Dans Ciklik, le panneau Situation du renouvellement de l’abonnement le nomme, ligne Produits concernés (pour les erreurs enregistrées depuis le 9 octobre 2026 ; pour les plus anciennes, comparez le contenu de la commande générée avec celui 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

Dans le back-office Ciklik

Les mêmes erreurs sont visibles sans passer par l’API, pour les comptes ayant un site PrestaShop :

• en bas du détail d’un abonnement (Ventes > Abonnements), rubrique Erreurs de renouvellement : la date, le type (Appel du module en erreur, Commande partielle (rupture), Commande refusée (rupture)), le code et le message d’erreur ;
• en bas de la fiche de votre site (Paramètres > Sites), la même liste pour tous les abonnements du site.

Ces lignes sont en lecture seule et restent en historique, même après un renouvellement réussi : l’état actuel du renouvellement se lit dans le panneau Situation du renouvellement de l’abonnement.

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

Note

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[by_subscription_uuid]=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.

Voir aussi

Renouvellements PrestaShop expliqués

Messages d'erreur API PrestaShop

Rebill et indisponibilité du site PrestaShop

Les erreurs de paiements