Événements : abonnements

Quatre clés : created_subscription, updated_subscription, deleted_subscription, et updated_change_choices (hors catalogue). Configuration générale : 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
`address`	objet	oui	voir page clients/adresses
`transporter`	objet	oui	voir 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.

`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).

Exemple

{
    "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).
Mise en pause par l’équipe, avec ou sans fermeture des 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).
Mise en pause avec fermeture des commandes : un updated_checkoutorder par commande en attente et en cours de création, plus large que l’annulation.
Report anti-churn : suivi d’autant de created_shippingbox que de mois reportés.

Exemple

{
    "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 manuelle par l’équipe, 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

{
    "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), activable uniquement par l’équipe Ciklik, sur demande.

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

Un seul champ, 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

{
    "changed": {
        "customization_products": "[{\"id\":1,\"quantity\":2}]"
    }
}

Événements : abonnements

Objet abonnement

Objet formule

created_subscription

Quand il part

Quand il ne part pas

Ce que contient changed

Effets en cascade

Exemple

updated_subscription

Quand il part

Quand il ne part pas

Ce que contient changed

Effets en cascade

Exemple

deleted_subscription

Quand il part

Quand il ne part pas

Ce que contient changed

Effets en cascade

Exemple

updated_change_choices sur demande

Quand il part

Quand il ne part pas

Ce que contient changed

Effets en cascade

Exemple

`created_subscription`

`updated_subscription`

`deleted_subscription`

`updated_change_choices` sur demande