# Événements > Le journal de tout ce qui s'est passé dans une application, et chaque type d'événement. Source : https://abuna.app/docs/api/events?hl=fr Lisez les événements survenus dans votre application, comme une facture payée, pour garder vos données à jour avec Abuna. Abuna enregistre chaque événement, et l'envoie aussi à l'URL du webhook si vous en avez défini une. ## L'objet event Un événement a la même forme ici et dans un corps de webhook. Un webhook pour l'événement porte le même `id`. **Attributs** - `id` (string): Identifiant unique de l'événement. Les ID d'événement se trient dans l'ordre où les événements ont eu lieu. Voir [Ordre des événements](https://abuna.app/docs/api/events.md?hl=fr#order). - `type` (string): Le [type](https://abuna.app/docs/api/events.md?hl=fr#types) de l'événement. - `environment` (string): `test` ou `live`. - `created_at` (timestamp): Quand l'événement a eu lieu, en secondes Unix. - `data` (object): Les données de l'événement. Leurs champs dépendent du [type](https://abuna.app/docs/api/events.md?hl=fr#types). **L'objet event** ```json { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ``` ## Lister les événements `GET /v1/apps/{appID}/events` Liste les événements de l'application, du plus récent au plus ancien, une page à la fois. Chaque page continue avec des événements plus anciens. Voir [Listes et filtres](https://abuna.app/docs/lists-and-filters.md?hl=fr). **Paramètres de requête** - `type` (string): Uniquement les événements de ce type, comme `invoice.paid`. - `limit` (integer): Combien d'événements renvoyer, de 1 à 100. Par défaut : 50. - `cursor` (string): La valeur `next_cursor` de la page précédente. Envoyez les mêmes filtres avec. **Attributs de la réponse** - `items` (array): Les [événements](https://abuna.app/docs/api/events.md?hl=fr#object) de la page, du plus récent au plus ancien. Vide quand rien ne correspond. - `next_cursor` (string, nullable): Passez-le comme cursor pour obtenir la page suivante, plus ancienne. Il vaut null sur la dernière page. Traitez-le comme opaque. Renvoie `200`. Un `limit` en dehors de 1 à 100 renvoie `422` avec le code `invalid` et un élément `errors` pour `limit`. **GET /v1/apps/{appID}/events** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Réponse** ```json { "items": [ { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ], "next_cursor": "MDFKOVpROEUxRjJHM0g0SjVLNk03TjhQOVE" } ``` ## Récupérer un événement `GET /v1/apps/{appID}/events/{id}` Récupère un événement, dans la même forme que le corps de son webhook. Utilisez-le pour récupérer à nouveau un événement par l'`id` qu'un webhook vous a donné. Renvoie l'événement. Si l'application n'a aucun événement avec cet ID, renvoie `404` avec le code `not_found`. **GET /v1/apps/{appID}/events/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4 \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", { headers: { Authorization: "Bearer sk_test_..." }, }); const event = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", headers={"Authorization": "Bearer sk_test_..."}, ) event = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $event = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var event map[string]any json.NewDecoder(res.Body).Decode(&event) ``` **Réponse** ```json { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ``` ## Ordre des événements Les ID d'événement se trient dans l'ordre où les événements ont eu lieu. Comparez-les comme de simples chaînes : l'ID d'un événement plus tardif se trie après celui d'un événement plus ancien. `created_at` est en secondes entières, donc les événements d'un même changement le partagent souvent. Ordonnez les événements par `id`, pas par `created_at`. Un même changement enregistre plusieurs événements à la fois. Ils arrivent dans cet ordre : - **Nouvel abonnement sans essai** : `subscription.created`, puis `invoice.created`. - **Renouvellement** : `subscription.updated` si un passage à une formule moins chère programmé commence avec la nouvelle période, `subscription.renewed`, `subscription.past_due` si la nouvelle période a déjà commencé, puis `invoice.created`. Un renouvellement émis avant la fin de la période payée envoie `subscription.past_due` de son côté plus tard, à la fin de la période payée, s'il est encore impayé à ce moment-là. - **Paiement** : `customer.updated` s'il donne au client son premier numéro de téléphone, `subscription.updated` s'il paie une montée de formule, `session.completed` s'il a été payé via une session `payment` ou termine une session `plan_change`, `invoice.paid`, puis au premier paiement `subscription.paid` et le `session.completed` du checkout, et enfin `subscription.recovered` si l'abonnement était `past_due`. - **Suppression d'un client** : `subscription.canceled` pour chaque abonnement que la suppression a terminé, puis `customer.deleted`. ## Rattraper les événements manqués Si votre serveur a manqué des webhooks, listez les événements que vous n'avez pas traités et traitez-les maintenant. Commencez sans `cursor`, puis passez le `next_cursor` de chaque page jusqu'à ce qu'il soit `null`, ou jusqu'à atteindre des événements créés 5 minutes avant le plus récent que vous avez traité. Un événement peut être listé quelques secondes après un plus récent, donc ignorez ceux que vous avez déjà traités par `id` plutôt que de vous arrêter au premier. Traitez ce que vous avez collecté du plus ancien au plus récent. **Rattraper les événements manqués** Node.js : ```javascript const base = "https://api.abuna.app/v1/apps/8ddhXCDW/events?limit=100"; const headers = { Authorization: "Bearer sk_test_..." }; const newestHandledAt = 1727600600; // created_at of the newest event you handled const stopAt = newestHandledAt - 5 * 60; const missed = []; let cursor = null; let done = false; while (!done) { const url = base + (cursor ? "&cursor=" + encodeURIComponent(cursor) : ""); const page = await (await fetch(url, { headers })).json(); for (const event of page.items) { if (event.created_at < stopAt) { done = true; break; } if (!(await alreadyHandled(event.id))) missed.push(event); } cursor = page.next_cursor; if (!cursor) done = true; } // Oldest first, in the order the events happened. for (const event of missed.reverse()) { await handle(event); } ``` Python : ```python import requests base = "https://api.abuna.app/v1/apps/8ddhXCDW/events" headers = {"Authorization": "Bearer sk_test_..."} newest_handled_at = 1727600600 # created_at of the newest event you handled stop_at = newest_handled_at - 5 * 60 missed = [] params = {"limit": 100} done = False while not done: page = requests.get(base, headers=headers, params=params).json() for event in page["items"]: if event["created_at"] < stop_at: done = True break if not already_handled(event["id"]): missed.append(event) if page["next_cursor"] is None: done = True params["cursor"] = page["next_cursor"] # Oldest first, in the order the events happened. for event in reversed(missed): handle(event) ``` ## Types d'événement Chaque type ci-dessous liste les champs de son `data`. Les ID sont des chaînes, les montants sont des entiers dans la plus petite unité de la devise, et les heures sont en secondes Unix. Chaque événement dont le `data` contient un `subscription_id` contient aussi `subscription` : l'[objet subscription](https://abuna.app/docs/api/subscriptions.md?hl=fr#object) complet, tel que [Récupérer un abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#retrieve) le renvoie sous `subscription`, tel qu'il est juste après le changement que l'événement signale. Un événement de session dont le `subscription_id` est null n'a pas de `subscription`. Les listes ci-dessous omettent `subscription`. L'abonnement inclut `trial_ends_at` : la fin de l'essai en secondes Unix, ou `null` sans essai. Son statut est `trialing` pendant un essai gratuit. Les événements d'abonnement, de facture et d'offre de formule portent les [métadonnées](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata) de l'abonnement au moment où l'événement est enregistré. Les événements de session portent le`metadata` propre à la session, pas celui de l'abonnement. Passez du metadata à chaque session que vous créez. Sans cela, les événements de session portent `{}`. Les listes ci-dessous omettent le metadata sauf indication contraire. ### session.completed Une [session](https://abuna.app/docs/api/sessions.md?hl=fr) s'est terminée. Une session se termine au plus une fois, et une session expirée ne se termine jamais. Le `data` dépend du `type` de la session. Chaque type a `session_id`, `type`, `subscription_id`, `customer_id`, `metadata` (le metadata que vous avez passé à la création de la session) et `completed_at`. - `checkout` ([Créer une session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout)) : sans essai, le premier paiement a réussi et l'abonnement est maintenant `active`. Pour un essai gratuit, la session se termine à son démarrage, avec `status: trialing` et sans paiement. Sans essai, `subscription.paid` est enregistré au même moment. Ajoute `price_id`, le prix de l'abonnement, et `updates`, les [`updates`](https://abuna.app/docs/api/customers.md?hl=fr#object) du client. Quand la page d'abonnement a plutôt changé la formule d'un [client qui revient](https://abuna.app/docs/api/sessions.md?hl=fr#returning-customers), la session s'est terminée une fois le changement confirmé, ou payé pour une montée de formule. `subscription_id` est son abonnement existant, et les données ajoutent les champs `plan_change` ci-dessous au lieu de `updates`. - `payment` ([Créer une session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment)) : la facture a été payée via la session. `invoice.paid` est aussi envoyé. Ajoute `invoice_id`. - `plan_change` ([Créer une session de changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change)) : le client a confirmé le changement, et l'a payé s'il s'agissait d'une montée de formule avec quelque chose à payer. Ajoute les champs ci-dessous. - `cancel` ([Créer une session de résiliation](https://abuna.app/docs/api/sessions.md?hl=fr#create-cancel)) : le client a confirmé la résiliation, programmée ou immédiate. `subscription.updated` (programmée) ou `subscription.canceled` (immédiate) est aussi envoyé. Ajoute les champs ci-dessous. - `portal` ([Créer une session d'espace client](https://abuna.app/docs/api/sessions.md?hl=fr#create-portal)) : le client a ouvert son espace client pour la première fois. Cela ne signifie pas qu'il a changé quelque chose. Ce qu'il y fait envoie ses propres événements, comme `subscription.updated`, `subscription.canceled`, `invoice.paid` et `customer.updated`. N'ajoute rien. **plan_change data, et le changement de formule d'une checkout, ajoutés** - `plan_offer_id` (string): L'offre de formule derrière la session. - `previous_price_id` (string): Le prix avant le changement. - `price_id` (string): Le nouveau prix. - `direction` (string): `upgrade` ou `downgrade`. - `effective_at` (timestamp): Quand le nouveau prix commence. Pour un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, la fin de la période payée : `subscription.updated` se déclenche alors avec le changement de prix. **cancel data ajoutés** - `cancel_at` (timestamp, nullable): Quand l'abonnement prend fin. `subscription.canceled` se déclenche alors. Null quand il a pris fin tout de suite. - `immediate` (boolean): `true` quand l'abonnement a pris fin tout de suite. ### session.expired Une session ouverte a expiré à son `expires_at`, ou vous l'avez [fait expirer](https://abuna.app/docs/api/sessions.md?hl=fr#expire). Abuna ne fait pas expirer une session checkout de lui-même pendant que son paiement est en attente. Un abonnement `pending` démarré par une session checkout reste, et prend fin avec `checkout_expired` s'il n'est pas payé à temps. Une session `payment` expire aussi quand sa facture est payée autrement, annulée, ou quand son abonnement prend fin. Une session `plan_change` expire aussi quand son offre est remplacée, annulée ou expirée, ou quand une montée de formule qu'elle a démarrée expire faute de paiement. Une session `checkout` qui a proposé un changement de formule expire de la même façon, au lieu de 24 heures après. Une session `cancel` expire 24 heures après sa création si le client ne confirme pas, et une session `portal` 1 heure après sa création si personne ne l'ouvre. Voir [Types de session](https://abuna.app/docs/api/sessions.md?hl=fr#types). **data** - `session_id` (string): La session. - `type` (string): Le type de la session : `checkout`, `payment`, `plan_change`, `cancel` ou `portal`. - `subscription_id` (string, nullable): L'abonnement que la session a démarré ou sur lequel elle agit. Pour checkout, null si le client n'est pas allé jusque-là. - `customer_id` (string, nullable): Le client que vous avez passé, ou celui créé à partir des coordonnées du client. Null si aucun des deux. - `price_id` (string, nullable): Le prix de la session, ou null pour les sessions payment, cancel et portal. - `invoice_id` (string, nullable): La facture de la session payment, ou null pour les autres types. - `plan_offer_id` (string, nullable): L'offre d'une session plan_change, ou d'une session checkout qui a proposé un changement de formule. Null sinon. - `metadata` (object): Le metadata que vous avez passé à la création de la session. - `expired_at` (timestamp): Quand la session a expiré. **session.expired data** ```json { "customer_id": "GzeUZeSV", "expired_at": 1794780106, "invoice_id": null, "metadata": { "user_id": "42" }, "plan_offer_id": null, "price_id": null, "session_id": "XYKz5u9G", "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH", "type": "cancel" } ``` ### subscription.created Un abonnement a été créé, via l'API, une session checkout ou un lien d'abonnement. Il est `trialing` si un essai gratuit s'applique, ou `pending` sans essai. **data** - `subscription_id` (string): Le nouvel abonnement. - `customer_id` (string): Son client. - `price_id` (string): Son prix. - `period_id` (string): Sa période d'essai gratuit, ou sa première période de facturation sans essai. ### subscription.paid La première période a été payée et l'abonnement est maintenant `active`. Après un essai gratuit, c'est le paiement de la première facture, quel que soit le moment où le client la paie. Le début d'un essai ne l'envoie pas. Les paiements suivants envoient `invoice.paid`, et `subscription.recovered` quand ils ramènent un abonnement `past_due` à `active`. **data** - `subscription_id` (string): L'abonnement. - `customer_id` (string): Son client. - `price_id` (string): Son prix. - `period_id` (string): La première période payée. - `activated_at` (timestamp): Quand l'abonnement a commencé : le début de l'essai, ou le premier paiement sans essai. ### subscription.trial_ending Un essai gratuit se termine bientôt. Abuna émet cet événement selon le délai habituel des rappels de renouvellement de votre application. La date de fin est `data.subscription.trial_ends_at`, en secondes Unix. L'événement contient l'abonnement et ses métadonnées, comme décrit plus haut. Voir [Essais gratuits](https://abuna.app/docs/guides/trials.md?hl=fr). Une URL de webhook ajoutée à partir de maintenant reçoit cet événement par défaut. Une URL configurée avant l'arrivée des essais gratuits ne le reçoit pas tant que vous ne l'activez pas : un propriétaire d'équipe ouvre **Webhooks** dans le tableau de bord, modifie les **Événements** et le coche. ### subscription.renewed Après un essai, la première période payante commence à `trial_ends_at`, même si le client paie en avance. Abuna a émis la période de facturation suivante et sa facture. Cela se produit avant la fin de la période payée ou de l'essai, d'autant de jours à l'avance que l'indique [`renewal_lead_days`](https://abuna.app/docs/api/apps.md?hl=fr#object) de l'application (3 par défaut), ou quand elle se termine avec `0`. La nouvelle période commence quand la période payée se termine, et le client peut la payer dès maintenant. Si elle est encore impayée à la fin de la période payée, `subscription.past_due` suit alors. **data** - `subscription_id` (string): L'abonnement. - `period_id` (string): La nouvelle période de facturation. - `amount` (integer): Le montant dû pour la nouvelle période. - `currency` (string): `XAF`, `XOF` ou `USD`. ### subscription.past_due La période payée ou l'essai a pris fin et la période suivante n'est pas payée, donc l'abonnement est maintenant impayé (`past_due`). Un renouvellement payé avant la période payée ne l'envoie jamais. Gardez l'accès du client tant qu'il est `past_due`. Si la période n'est pas payée à sa date limite de paiement, `subscription.canceled` suit avec la raison `non_payment`. **data** - `subscription_id` (string): L'abonnement. - `metadata` (object): Les métadonnées de l'abonnement. ### subscription.recovered La facture d'un abonnement `past_due` a été payée, donc il est de nouveau `active`. Il vient juste après `invoice.paid`. Il vient aussi quand un paiement qui arrive après une résiliation pour non-paiement ramène l'abonnement ; voir [Paiements qui arrivent en retard](https://abuna.app/docs/api/subscriptions.md?hl=fr#late-payments). Le `data` est le même que celui de `subscription.past_due`. ### subscription.updated Un abonnement en cours, y compris un essai, a changé. Cet événement est émis quand une résiliation à la fin de la période payée ou de l'essai est programmée ou retirée, quand le prix change (une montée de formule prend effet, ou un passage à une formule moins chère programmé commence), quand un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, est programmé ou retiré, quand une montée de formule en attente de paiement expire, et quand un nouveau changement en efface un précédent. Pour une résiliation programmée, `subscription.canceled` suit quand elle prend fin. Voir [Changer de formule](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan). **data** - `subscription_id` (string): L'abonnement. - `price_id` (string): Le prix sur lequel l'abonnement est actuellement. - `cancel_at` (timestamp, nullable): Quand l'abonnement prendra fin, si une résiliation est programmée. Null sinon. - `cancel_at_period_end` (boolean): `true` tant qu'une résiliation est programmée pour la fin de la période payée, `false` sinon. - `scheduled_price_change` (object, nullable): Le passage à une formule moins chère, ou la montée de formule au prochain renouvellement, programmé pour la fin de la période payée. Null quand il n'y en a pas. - `price_id` (string): Le prix vers lequel l'abonnement passe. - `effective_at` (timestamp): Quand il passe. - `change` (object): Ce qui est arrivé au prix. Présent uniquement quand le prix a changé, ou qu'un passage à une formule moins chère ou une montée de formule au prochain renouvellement a été programmé ou retiré. Une montée de formule expirée, une résiliation à la fin de la période, et une montée de formule qui commence à attendre un paiement n'en ont pas. - `type` (string): `price_changed`, `downgrade_scheduled`, `downgrade_undone`, `upgrade_scheduled` ou `upgrade_undone`. - `old_price_id` (string): Le prix avant. - `new_price_id` (string): Le nouveau prix, ou celui programmé. - `effective_at` (timestamp): Quand le changement a pris effet, ou quand le changement programmé le fera. - `updated_by` (string): `merchant` quand vous l'avez changé, ou `customer` quand le client l'a changé dans son espace client ou a changé de formule sur une page d'abonnement. Quand un changement de formule est exécuté plus tard (une montée de formule payée, un passage à une formule moins chère qui commence, une montée de formule qui expire), c'est celui qui l'a demandé : `customer` depuis l'espace client ou une page d'abonnement, ou `merchant` quand il a confirmé un changement vers lequel vous l'avez envoyé. ### subscription.canceled L'abonnement a pris fin. Il se déclenche quand l'abonnement prend vraiment fin : tout de suite pour une résiliation immédiate, ou à la fin de la période payée pour une résiliation programmée. Programmer une résiliation envoie `subscription.updated` à la place. Le `subscription` dans le `data` a `ended_reason` `unpaid` pour `non_payment` et `checkout_expired`, et `canceled` pour les autres. **data** - `subscription_id` (string): L'abonnement. - `reason` (string): Pourquoi il a pris fin : `merchant` (vous l'avez résilié), `customer` (le client l'a résilié dans son espace client), `non_payment` (un renouvellement a dépassé sa date limite de paiement), ou `checkout_expired` (la première période n'a jamais été payée). Une résiliation programmée qui prend fin garde qui l'a programmée, `merchant` ou `customer`. ### plan_offer.created Une [session de changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change) a créé une offre de formule, une page d'abonnement a proposé à un [client qui revient de changer de formule](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch), ou vous avez proposé un changement depuis le tableau de bord et Abuna a envoyé le lien au client. Une session de changement de formule n'envoie pas d'e-mail ; un changement demandé au paiement envoie son lien de confirmation uniquement par e-mail. Renvoyer le lien depuis le tableau de bord ne le déclenche pas à nouveau. Les quatre `plan_offer` événements partagent le même `data`. **data** - `offer_id` (string): L'offre. - `subscription_id` (string): L'abonnement. - `price_id` (string): Le prix proposé. - `expires_at` (timestamp): Quand l'offre cesse de fonctionner. ### plan_offer.confirmed Le client a accepté l'offre. Un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, est maintenant programmé, ou une montée de formule est appliquée ou en attente de paiement. `subscription.updated` se déclenche quand le prix change ou que le changement est programmé. ### plan_offer.canceled L'offre a cessé avant que le client l'accepte. Le `data` ajoute `reason` : `merchant` quand vous l'avez annulée, ou `replaced` quand une nouvelle offre ou le propre changement de formule du client a pris sa place, ou que l'abonnement a été résilié. Une résiliation enregistre `plan_offer.canceled` juste avant `subscription.canceled`, qui a donc l'`id` d'événement le plus grand. ### plan_offer.expired L'offre a atteint son `expires_at` sans être acceptée. ### invoice.created Abuna a émis une facture pour une nouvelle période de facturation, ou pour une montée de formule. Une montée de formule en attente de paiement reçoit les dates de sa période quand elle est payée, et `invoice.paid` les porte. **data** - `invoice_id` (string): La facture. - `invoice_number` (string): Son numéro. - `subscription_id` (string): Son abonnement. - `period_id` (string): La période de facturation qu'elle facture. - `kind` (string): `period` pour une période de facturation, ou `plan_change` pour la première période d'une montée de formule. - `amount` (integer): Le montant dû. - `credit` (integer): Le temps inutilisé de la période en cours déduit du nouveau prix. `0` sur une facture `period`. - `discount` (integer): Ce que le coupon de la facture a retiré. `0` sans coupon. `amount` est déjà après cette réduction. Voir [l'objet invoice](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-object). - `coupon_id` (string, nullable): Le coupon qui a accordé la réduction. Null sans coupon. - `promotion_code_id` (string, nullable): Le code promotionnel qui a apporté le coupon. Null quand vous avez appliqué le coupon directement, sans code. - `currency` (string): `XAF`, `XOF` ou `USD`. - `period_start` (timestamp): Quand la période commence. - `period_end` (timestamp): Quand la période se termine. ### invoice.paid Une facture a été payée. Un renouvellement payé avant le début de sa période est tout de même pour cette période : `period_start` ne bouge pas. Une facture qui a été annulée peut aussi devenir payée, quand un paiement que le client a approuvé avant son annulation aboutit ; voir [Paiements qui arrivent en retard](https://abuna.app/docs/api/subscriptions.md?hl=fr#late-payments). Le `data` a tous les champs de `invoice.created`, plus deux. Ses `amount` et `currency` restent ceux de la facture, dans la devise du prix. **data** - `paid_at` (timestamp): Quand elle a été payée. - `payment` (object): Le paiement qui a réglé la facture, sous la forme de l'[objet payment](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#payment-object). Ses `amount` et `currency` sont ce que le client a payé, en FCFA pour le mobile money. Quand la facture était dans une autre devise, `original_amount`, `original_currency` et `exchange_rate` montrent la conversion. ### invoice.payment_failed Un paiement sur une facture a échoué. La facture reste ouverte, donc le client peut réessayer avant la date limite de paiement. Certains paiements sont signalés comme échoués avant que le prestataire ait confirmé leur issue, par exemple quand il ne répond pas à temps. Un tel paiement peut encore aboutir plus tard, en général dans les 7 jours suivant son début. Un paiement échoué pour une raison précise, comme `insufficient_funds`, reste échoué, sauf si le prestataire indique ensuite qu'il a été payé. Dès qu'un paiement échoué est payé, vous recevez [`invoice.paid`](https://abuna.app/docs/api/events.md?hl=fr#invoice-paid), et la facture est `paid`. Considérez `invoice.paid` comme la réponse définitive : ne remboursez pas le client et ne coupez pas son accès sur la seule base de `invoice.payment_failed`. **data** - `subscription_id` (string): L'abonnement. - `period_id` (string): La période de facturation. - `invoice_id` (string): La facture. - `invoice_number` (string): Son numéro. - `provider_reference` (string): L'ID du prestataire pour le débit. Vide s'il n'en a donné aucun. - `failure` (string): La raison de l'échec, avec les mêmes [codes](https://abuna.app/docs/errors.md?hl=fr) qu'un débit refusé en `402`, comme `insufficient_funds`. Vaut `payment_declined` si le prestataire n'a donné aucune raison. - `message` (string): Une courte note sur l'échec, à lire. Ne l'analysez pas, car sa formulation peut changer. Branchez sur `failure`. Vide quand il n'y a pas de note. - `payment` (object): Le paiement qui a échoué, sous la forme de l'[objet payment](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#payment-object), avec le montant qu'il a tenté de débiter. ### customer.updated Le nom, l'e-mail, le numéro de téléphone ou les métadonnées d'un client ont changé. Il est aussi envoyé quand un client sans numéro de téléphone paie pour la première fois : son `phone_number` est maintenant le numéro qui a payé, et `updated_by` vaut `customer`. **data** - `customer_id` (string): Le client. - `name` (string, nullable): Son nom maintenant. - `email` (string): Son adresse e-mail maintenant. - `phone_number` (string, nullable): Son numéro de téléphone maintenant. Null jusqu'à son premier paiement s'il est venu par la page d'abonnement. - `metadata` (object): Les [métadonnées](https://abuna.app/docs/api/customers.md?hl=fr#object) du client. - `updated_by` (string): `merchant` quand vous l'avez changé, ou `customer` quand le client l'a changé dans son espace client ou que son premier paiement lui a donné un numéro de téléphone. - `updates` (object): Les [`updates`](https://abuna.app/docs/api/customers.md?hl=fr#object) du client maintenant. ### customer.updates_changed Le statut Telegram ou WhatsApp d'un client a changé. Cela arrive quand le client s'abonne sur une page d'abonnement, connecte une messagerie à l'étape de paiement de la page d'abonnement ou dans son espace client, l'active (dans Telegram, ou en confirmant son numéro WhatsApp avec un code), l'arrête en envoyant « arrêt » dans la discussion, le désactive dans son espace client, ou, pour WhatsApp, a un numéro qui ne peut pas recevoir de messages. Un changement que vous faites aux paramètres de messagerie de votre application ne l'envoie pas. Chaque changement envoie un événement, et un statut qui reste le même n'en envoie aucun. **data** - `customer_id` (string): Le client. - `channel` (string): La messagerie dont le statut a changé : `telegram` ou `whatsapp`. - `status` (string): Le statut maintenant : `off`, `active`, `stopped`, ou, pour Telegram, `pending`, et, pour WhatsApp, `failed`. - `previous_status` (string): Le statut avant. - `updates` (object): Les [`updates`](https://abuna.app/docs/api/customers.md?hl=fr#object) du client maintenant. **customer.updates_changed data** ```json { "customer_id": "Cu5tM8rA", "channel": "telegram", "status": "active", "previous_status": "pending", "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` Listez ces événements pour voir combien de clients ont activé une messagerie : **GET /v1/apps/{appID}/events** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` ### customer.deleted Vous avez [supprimé un client](https://abuna.app/docs/api/customers.md?hl=fr#delete). Ses abonnements ont pris fin et ses données personnelles sont effacées, donc l'événement n'en contient aucune. Quand vous le recevez, supprimez votre propre copie des données du client. Il arrive après les événements `subscription.canceled` de cette suppression. Supprimer de nouveau le même client n'envoie rien. **data** - `customer_id` (string): Le client. - `deleted_by` (string): `merchant` : vous avez supprimé le client, avec votre clé secrète ou dans le tableau de bord. C'est la seule valeur aujourd'hui. **customer.deleted data** ```json { "customer_id": "Cu5tM8rA", "deleted_by": "merchant" } ``` ### price_change.scheduled Vous avez [programmé un nouveau montant](https://abuna.app/docs/api/prices.md?hl=fr#change) pour un prix, ou remplacé celui qui était en attente. Les trois `price_change` événements partagent le même `data`. **data** - `price_change_id` (string): Le changement. - `price_id` (string): Le prix. - `amount` (integer): Le nouveau montant. - `previous_amount` (integer): Le montant avant le changement. - `currency` (string): `XAF`, `XOF` ou `USD`. - `effective_at` (timestamp): Minuit au début du jour à partir duquel le nouveau montant s'applique, dans timezone. - `timezone` (string): Le fuseau horaire de votre application, comme `Africa/Douala`. C'est le [`timezone`](https://abuna.app/docs/api/apps.md?hl=fr#object) de l'application. - `keep_current_subscribers` (boolean): `true` quand toutes les personnes abonnées ce jour-là gardent l'ancien montant. ### price_change.canceled Un changement en attente s'est arrêté avant son jour. Le `data` ajoute `reason` : `merchant` quand vous l'avez annulé, ou `replaced` quand vous avez programmé un nouveau changement à sa place. Un remplacement envoie aussi `price_change.scheduled`. ### price_change.applied Le montant du prix est passé au nouveau à son `effective_at`. L'événement arrive dans environ une minute après ce moment. À partir de là, les checkouts et les nouveaux abonnements le paient. Les abonnés actuels y passent à leur prochain renouvellement, sauf si `keep_current_subscribers` est `true`. ### notification.captured Mode Test uniquement. Abuna a rédigé un message pour un client Test et en a conservé une copie ici. La plupart des messages Test ne sont pas envoyés ; `sent` indique lesquels l'ont été. Cet événement ne va jamais vers l'URL du webhook. **data** - `customer_id` (string): Le client. Absent pour `profile_code`, car la personne n'est peut-être pas encore cliente. - `kind` (string): Ce sur quoi porte le message. Voir [types de messages aux clients](https://abuna.app/docs/api/notices.md?hl=fr#object). Un type de plus n'apparaît qu'ici : `profile_code`, le code des informations enregistrées d'un client sur la page d'abonnement. - `channel` (string): `email`, `telegram` ou `whatsapp`. - `recipient` (string): L'adresse e-mail, le numéro WhatsApp ou la conversation Telegram auxquels il est allé, ou serait allé. - `subject` (string): La ligne d'objet. Pour un code par e-mail, elle contient le code. - `text` (string): Le message, en texte brut. - `sent` (boolean): `true` pour les trois codes par e-mail que le mode Test envoie comme en production : `trial_email_code`, `email_code` et `profile_code`. `false` pour tous les autres messages, qui n'ont pas été envoyés.