--- title: "Événements : abonnements" description: "Quand partent les webhooks d'abonnement (création, modification, suppression, choix), ce qu'ils contiennent et leurs effets en cascade." url: https://www.ciklik.academy/fr/webhooks/evenements-abonnements/ lang: fr lastUpdated: 2026-10-23 --- # Événements : abonnements > Box et PrestaShop > > Cette page vaut pour les boutiques box comme pour les boutiques PrestaShop. Quatre clés : `created_subscription`, `updated_subscription`, `deleted_subscription`, et `updated_change_choices` (hors catalogue). Configuration générale : [Comprendre un envoi de webhook](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/). ## Objet abonnement Chaque envoi porte l’abonnement complet, avec sa formule, son adresse et son transporteur. | Champ | Type | Nullable | Sens | | -------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `id` | entier | non | identifiant interne | | `uuid` | chaîne | non | identifiant public | | `plan` | objet | oui | voir [Objet formule](#objet-formule) | | `address` | objet | oui | voir [page clients/adresses](https://www.ciklik.academy/fr/webhooks/evenements-clients-adresses-optins/) | | `transporter` | objet | oui | voir [Objet transporteur](https://www.ciklik.academy/fr/webhooks/evenements-expeditions/#objet-transporteur) | | `created_at` | date | non | création | | `end_date` | date | oui | fin de période en cours | | `engaged_date` | date | oui | fin d’engagement | | `auto_pause_at` | date | oui | pause auto programmée | | `start_date` | date | oui | début d’abonnement | | `active` | booléen | non | abonnement actif | | `paused` | booléen | non | abonnement en pause | | `next_billing` | date | oui | prochain prélèvement | | `update_transporter_at` | date | oui | transporteur programmé | | `relay` | objet | oui | point relais | | `graceMonths` | entier | oui | mois de pause restants | | `user_uuid` | chaîne | non | client (`cus_...`) | | `user_id` | entier | non | id client | | `email` | chaîne | non | e-mail du client | | `revenue` | chaîne | non | CA généré (point décimal) | | `refunded` | chaîne | non | remboursé | | `customerRevenue` | chaîne | non | CA côté client | | `customerRefund` | chaîne | non | remboursé côté client | | `totalTransactionsSuccess` | entier | non | transactions réussies | | `subTransactionsSuccess` | entier | non | transactions réussies sur la dernière commande | | `countTransactions` | entier | non | nombre de transactions de la dernière commande | | `customization_products` | tableau | oui | personnalisation | | `retry_link` | (toujours nul) | oui | lien de reprise | | `is_auto` | booléen | non | vrai si une pause automatique démarre dans les 5 jours | | `interval` | chaîne | oui | périodicité | | `interval_count` | entier | oui | multiplicateur | | `switch_plan_uuid` | chaîne | oui | bascule programmée | | `switch_plan_date` | date | oui | date de bascule | | `referrer` | chaîne | oui | source d’acquisition (parrainage, campagne) | | `display_interval` | chaîne | oui | libellé de périodicité | | `display_content` | chaîne | non | produits (virgule) | | `external_fingerprint` | chaîne | oui | empreinte PrestaShop | | `content` | tableau | non | produits abonnement | ## Objet formule L’objet `plan` suit la structure décrite ci-dessous. | Champ | Type | Nullable | Sens | | ------------------ | ------- | -------- | ---------------------- | | `id` | entier | non | identifiant interne | | `uuid` | chaîne | non | identifiant public | | `name` | chaîne | non | nom de la formule | | `short_name` | chaîne | oui | nom court | | `more` | chaîne | oui | description | | `image` | chaîne | oui | URL image | | `start_at` | date | oui | début de disponibilité | | `price` | nombre | non | prix hors port | | `tax` | nombre | non | TVA (`0.2` = 20 %) | | `interval` | chaîne | non | périodicité | | `interval_count` | entier | non | multiplicateur | | `shipped_count` | entier | non | envois par cycle | | `position` | entier | oui | ordre d’affichage | | `engaged_interval` | chaîne | oui | durée d’engagement | | `engaged` | booléen | non | formule engageante | | `active` | booléen | non | formule active | L’objet `transporter` suit la même structure que dans les expéditions, détaillée sur [Objet transporteur](https://www.ciklik.academy/fr/webhooks/evenements-expeditions/#objet-transporteur). ## `created_subscription` Objet envoyé : abonnement complet. Délai avant envoi : aucun. ### Quand il part - Création sur le site Ciklik, ou depuis une commande (composable ou PrestaShop). - **Activation d’une carte cadeau** : mêmes mécanismes, donc un `created_subscription` **ordinaire** (`gift_activation_code` en base, non exposé). ### Quand il ne part pas - Import d’abonnements par CSV, tâche de fond ou ligne de commande : écritures silencieuses. ### Ce que contient changed Toujours un tableau vide (`[]`). ### Effets en cascade Sans inscription marketing existante pour la boutique, un `created_optin` part aussi (voir [page clients/adresses/inscriptions](https://www.ciklik.academy/fr/webhooks/evenements-clients-adresses-optins/)). ### Exemple ```json { "id": 1, "uuid": "sub_N8PxGUEdS2U7DP", "plan": { "id": 1, "uuid": "boutique-exemple-box-mensuelle-1", "name": "Box mensuelle", "short_name": "Mensuelle", "more": "Une sélection de trois thés chaque mois", "image": "https://s3.eu-central-1.amazonaws.com/ciklik-media/plans/box-mensuelle.jpg", "start_at": null, "price": 29.9, "tax": 0.2, "interval": "month", "interval_count": 1, "shipped_count": 1, "position": 1, "engaged_interval": null, "engaged": false, "active": true }, "address": { "id": 1, "user_id": 1, "address": "12 rue des Lilas", "address1": "Bâtiment B, 3e étage", "postcode": "69003", "city": "Lyon", "phone": "+33612345678", "first_name": "Claire", "last_name": "Martin", "region_id": 1, "division": null, "division_name": null, "deletable": false, "company_name": null, "country": { "id": 1, "name": "France", "alphaCode": "FR" }, "external_id": 4821 }, "transporter": { "id": 1, "countries": [ { "id": 1, "name": "France" } ], "plan_blacklisted": [], "name": "Colissimo domicile", "description": "Livraison à domicile sous 48h", "price": 4.9, "gift": false, "active": true, "shipped_count": 1, "type": "subs", "relayOptions": null }, "created_at": "2026-09-10T08:15:42.000000Z", "end_date": "2026-10-09T00:00:00.000000Z", "engaged_date": null, "auto_pause_at": null, "start_date": "2026-06-10T00:00:00.000000Z", "active": true, "paused": false, "next_billing": "2026-10-10T08:15:42.000000Z", "update_transporter_at": null, "relay": null, "graceMonths": null, "user_uuid": "cus_Qx7hR3eaEowcv1DX", "user_id": 1, "email": "claire.martin@example.com", "revenue": "0.00", "refunded": "0.00", "customerRevenue": "0.00", "customerRefund": "0.00", "totalTransactionsSuccess": 0, "subTransactionsSuccess": 0, "countTransactions": 1, "customization_products": [ { "id": 1, "quantity": 1 } ], "retry_link": null, "is_auto": false, "interval": "month", "interval_count": 1, "switch_plan_uuid": null, "switch_plan_date": null, "referrer": "newsletter", "display_interval": "Monthly", "display_content": "Box découverte", "external_fingerprint": null, "content": [ { "external_id": "1042", "quantity": 1, "product_id": 1, "subscription_id": 1 } ], "changed": [] } ``` ## `updated_subscription` Objet envoyé : abonnement complet, dans son état au moment de l’envoi (état relu au moment de l’envoi). Délai avant envoi : aucun. ### Quand il part Événement le plus fréquent, avec des `changed` très différents selon le geste : - Annulation par le client ou par vous (`canceled_at` renseigné, `active` à `0`, `next_billing`/`switch_plan_date` vidés, `plan_id` si bascule programmée). - Réactivation de l’abonnement (`active` à `1`, `next_billing` recalculé, avec cascade si le prélèvement est immédiat). - Restauration d’un abonnement supprimé (`deleted_at` vidé, seul signal de la résurrection). - Report anti-churn (`next_billing`, `end_date` déplacés). - Résiliation depuis le back-office (action **Résilier l’abonnement** de la fiche abonnement), avec ou sans l’option **Fermer les commandes en attente**. - Changement d’adresse, de transporteur, de déclinaison, de point relais ou de personnalisation, avec cascade. - Mise à jour par l’API vendors, `PUT /subscriptions/{id}`. ### Quand il ne part pas - **La bascule de formule programmée, à son échéance : le piège le plus coûteux de cette page.** `plan_id`, `next_billing`, `switch_plan_date`, `switch_plan_uuid`, `auto_pause_at`, `engaged_date` changent en base **sans aucun webhook**. - Coupon sur la prochaine échéance, import CSV, décalage de `next_billing` par l’équipe, ajustement d’`interval`/`interval_count`, désactivation en masse à la suppression d’un site, simple enregistrement d’une ligne d’historique, écritures techniques PrestaShop. ### Ce que contient changed Objet `{colonne: valeur brute}`, dates au format base. Champs courants : `active`, `next_billing`, `end_date`, `canceled_at`, `plan_id`, `address_id`, `transporter_id`, `declinaison_id`, `customization_products`, `relay`, `grace_period`, `deleted_at`, `updated_at`. ### Effets en cascade - **Annulation** : jusqu’à **deux** `updated_subscription` (le second si l’abonnement était en pause). Fermeture des commandes activée : un `updated_checkoutorder` par commande `pending`. **Jamais un `deleted_subscription`.** - **Réactivation avec prélèvement immédiat** : enchaîne `created_checkoutorder`, `created_checkouttransaction`, souvent `created_checkoutinvoice`, chronologie **0, 10, 10, 15 s** (voir [page commandes/transactions/factures](https://www.ciklik.academy/fr/webhooks/evenements-commandes-transactions-factures/)). - **Résiliation depuis le back-office avec l’option Fermer les commandes en attente** : un `updated_checkoutorder` par commande **en attente et en cours de création**, plus large que la fermeture automatique réglée sur votre boutique. - **Report anti-churn** : suivi d’**autant de `created_shippingbox` que de mois reportés**. > La cascade la plus coûteuse en volume > > Adresse, transporteur, déclinaison, relais ou personnalisation modifiés déclenchent un `updated_shippingbox` par **expédition planifiée depuis le premier jour de l’avant-dernier mois (M-2, par exemple le 1er juillet pour un envoi en septembre)**, déjà parties incluses, plus un ou deux `updated_checkoutorder` par commande en cours de création. 12 expéditions récentes = **12 envois** pour un seul changement d’adresse. Détail sur [Événements : expéditions](https://www.ciklik.academy/fr/webhooks/evenements-expeditions/). ### Exemple ```json { "changed": { "next_billing": "2026-11-10 08:15:42", "end_date": "2026-11-09 21:59:59", "updated_at": "2026-09-10T08:15:42.000000Z" } } ``` ## `deleted_subscription` Objet envoyé : abonnement complet, même après suppression (l’état est relu au moment de l’envoi). Délai avant envoi : aucun. ### Quand il part - Suppression via l’API vendors, `DELETE /subscriptions/{id}`, acceptée seulement sur un abonnement inactif (annulé), 422 sinon. - Suppression depuis le back-office (icône corbeille de la fiche abonnement), possible seulement sur un abonnement **inactif**. ### Quand il ne part pas - **Une annulation** : produit un `updated_subscription`, jamais ce webhook, ce sont deux actions distinctes. - La restauration d’un abonnement supprimé : un `updated_subscription` (voir plus haut). ### Ce que contient changed Toujours `{"deleted": true}`. ### Effets en cascade Avant l’envoi, chaque commande `pending` passe en échec (un `updated_checkoutorder` par commande). Ciklik prévient ensuite PrestaShop par un autre canal, qui n’est pas un webhook marchand. ### Exemple ```json { "changed": { "deleted": true } } ``` ## `updated_change_choices` sur demande Objet envoyé : abonnement complet, même structure que `updated_subscription`. Délai avant envoi : aucun. Hors des 17 clés officielles : refusée par `POST /webhooks` (422, voir [Configurer les webhooks par l’API](https://www.ciklik.academy/fr/webhooks/configurer-les-webhooks-par-lapi/)), à ajouter dans le champ **Webhooks** de l’onglet **Avancé** de votre site. ### Quand il part Quand `customization_products` change sur un abonnement. Envoyé **en plus** de l’`updated_subscription` habituel, pas à sa place. ### Quand il ne part pas - Tout autre changement sur l’abonnement ne produit qu’un `updated_subscription`, sans cette clé. - Impossible à activer par l’API, refusé en 422. ### Ce que contient changed Les mêmes champs que l’`updated_subscription` envoyé pour le même geste, dont toujours `customization_products` : piège de format, la valeur n’est **pas** un objet mais une **chaîne** contenant du JSON encodé, telle que stockée en base. ### Effets en cascade `customization_products` fait partie des champs suivis pour la cascade expéditions : un `updated_shippingbox` part par expédition planifiée depuis le mois M-2 (voir l’encadré plus haut). ### Exemple ```json { "changed": { "customization_products": "[{\"id\":1,\"quantity\":2}]" } } ``` ## Voir aussi [Comprendre un envoi de webhook](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/) [Événements : expéditions](https://www.ciklik.academy/fr/webhooks/evenements-expeditions/) [Événements : commandes, transactions et factures](https://www.ciklik.academy/fr/webhooks/evenements-commandes-transactions-factures/)