Skip to content
ABUNA
DocumentationÉvénements

Référence de l'API

Événements

Le journal de tout ce qui s'est passé dans une application, et chaque type d'événement.

Voir en Markdown

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

  • idstring

    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.
  • typestring

    Le type de l'événement.
  • environmentstring

    test ou live.
  • created_attimestamp

    Quand l'événement a eu lieu, en secondes Unix.
  • dataobject

    Les données de l'événement. Leurs champs dépendent du type.
L'objet event
{
  "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.

Paramètres de requête

  • typestring

    Uniquement les événements de ce type, comme invoice.paid.
  • limitinteger

    Combien d'événements renvoyer, de 1 à 100. Par défaut : 50.
  • cursorstring

    La valeur next_cursor de la page précédente. Envoyez les mêmes filtres avec.

Attributs de la réponse

  • itemsarray

    Les événements de la page, du plus récent au plus ancien. Vide quand rien ne correspond.
  • next_cursorstringnullable

    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 "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid" \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "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 https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4 \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "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
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);
}

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 complet, tel que Récupérer un abonnement 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 de l'abonnement au moment où l'événement est enregistré. Les événements de session portent lemetadata 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 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) : 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 du client. Quand la page d'abonnement a plutôt changé la formule d'un client qui revient, 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) : 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) : 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) : 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) : 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_idstring

    L'offre de formule derrière la session.
  • previous_price_idstring

    Le prix avant le changement.
  • price_idstring

    Le nouveau prix.
  • directionstring

    upgrade ou downgrade.
  • effective_attimestamp

    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_attimestampnullable

    Quand l'abonnement prend fin. subscription.canceled se déclenche alors. Null quand il a pris fin tout de suite.
  • immediateboolean

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

data

  • session_idstring

    La session.
  • typestring

    Le type de la session : checkout, payment, plan_change, cancel ou portal.
  • subscription_idstringnullable

    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_idstringnullable

    Le client que vous avez passé, ou celui créé à partir des coordonnées du client. Null si aucun des deux.
  • price_idstringnullable

    Le prix de la session, ou null pour les sessions payment, cancel et portal.
  • invoice_idstringnullable

    La facture de la session payment, ou null pour les autres types.
  • plan_offer_idstringnullable

    L'offre d'une session plan_change, ou d'une session checkout qui a proposé un changement de formule. Null sinon.
  • metadataobject

    Le metadata que vous avez passé à la création de la session.
  • expired_attimestamp

    Quand la session a expiré.
session.expired data
{
  "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_idstring

    Le nouvel abonnement.
  • customer_idstring

    Son client.
  • price_idstring

    Son prix.
  • period_idstring

    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_idstring

    L'abonnement.
  • customer_idstring

    Son client.
  • price_idstring

    Son prix.
  • period_idstring

    La première période payée.
  • activated_attimestamp

    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.

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 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_idstring

    L'abonnement.
  • period_idstring

    La nouvelle période de facturation.
  • amountinteger

    Le montant dû pour la nouvelle période.
  • currencystring

    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_idstring

    L'abonnement.
  • metadataobject

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

data

  • subscription_idstring

    L'abonnement.
  • price_idstring

    Le prix sur lequel l'abonnement est actuellement.
  • cancel_attimestampnullable

    Quand l'abonnement prendra fin, si une résiliation est programmée. Null sinon.
  • cancel_at_period_endboolean

    true tant qu'une résiliation est programmée pour la fin de la période payée, false sinon.
  • scheduled_price_changeobjectnullable

    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.
    Afficher les attributsMasquer les attributs
    • price_idstring

      Le prix vers lequel l'abonnement passe.
    • effective_attimestamp

      Quand il passe.
  • changeobject

    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.
    Afficher les attributsMasquer les attributs
    • typestring

      price_changed, downgrade_scheduled, downgrade_undone, upgrade_scheduled ou upgrade_undone.
    • old_price_idstring

      Le prix avant.
    • new_price_idstring

      Le nouveau prix, ou celui programmé.
    • effective_attimestamp

      Quand le changement a pris effet, ou quand le changement programmé le fera.
  • updated_bystring

    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_idstring

    L'abonnement.
  • reasonstring

    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 a créé une offre de formule, une page d'abonnement a proposé à un client qui revient de changer de formule, 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_idstring

    L'offre.
  • subscription_idstring

    L'abonnement.
  • price_idstring

    Le prix proposé.
  • expires_attimestamp

    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_idstring

    La facture.
  • invoice_numberstring

    Son numéro.
  • subscription_idstring

    Son abonnement.
  • period_idstring

    La période de facturation qu'elle facture.
  • kindstring

    period pour une période de facturation, ou plan_change pour la première période d'une montée de formule.
  • amountinteger

    Le montant dû.
  • creditinteger

    Le temps inutilisé de la période en cours déduit du nouveau prix. 0 sur une facture period.
  • discountinteger

    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.
  • coupon_idstringnullable

    Le coupon qui a accordé la réduction. Null sans coupon.
  • promotion_code_idstringnullable

    Le code promotionnel qui a apporté le coupon. Null quand vous avez appliqué le coupon directement, sans code.
  • currencystring

    XAF, XOF ou USD.
  • period_starttimestamp

    Quand la période commence.
  • period_endtimestamp

    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. 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_attimestamp

    Quand elle a été payée.
  • paymentobject

    Le paiement qui a réglé la facture, sous la forme de l'objet payment. 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, 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_idstring

    L'abonnement.
  • period_idstring

    La période de facturation.
  • invoice_idstring

    La facture.
  • invoice_numberstring

    Son numéro.
  • provider_referencestring

    L'ID du prestataire pour le débit. Vide s'il n'en a donné aucun.
  • failurestring

    La raison de l'échec, avec les mêmes codes qu'un débit refusé en 402, comme insufficient_funds. Vaut payment_declined si le prestataire n'a donné aucune raison.
  • messagestring

    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.
  • paymentobject

    Le paiement qui a échoué, sous la forme de l'objet payment, 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_idstring

    Le client.
  • namestringnullable

    Son nom maintenant.
  • emailstring

    Son adresse e-mail maintenant.
  • phone_numberstringnullable

    Son numéro de téléphone maintenant. Null jusqu'à son premier paiement s'il est venu par la page d'abonnement.
  • metadataobject

    Les métadonnées du client.
  • updated_bystring

    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.
  • updatesobject

    Les updates 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_idstring

    Le client.
  • channelstring

    La messagerie dont le statut a changé : telegram ou whatsapp.
  • statusstring

    Le statut maintenant : off, active, stopped, ou, pour Telegram, pending, et, pour WhatsApp, failed.
  • previous_statusstring

    Le statut avant.
  • updatesobject

    Les updates du client maintenant.
customer.updates_changed data
{
  "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 "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed" \
  -H "Authorization: Bearer sk_test_..."

customer.deleted

Vous avez supprimé un client. 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_idstring

    Le client.
  • deleted_bystring

    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
{
  "customer_id": "Cu5tM8rA",
  "deleted_by": "merchant"
}

price_change.scheduled

Vous avez programmé un nouveau montant pour un prix, ou remplacé celui qui était en attente. Les trois price_change événements partagent le même data.

data

  • price_change_idstring

    Le changement.
  • price_idstring

    Le prix.
  • amountinteger

    Le nouveau montant.
  • previous_amountinteger

    Le montant avant le changement.
  • currencystring

    XAF, XOF ou USD.
  • effective_attimestamp

    Minuit au début du jour à partir duquel le nouveau montant s'applique, dans timezone.
  • timezonestring

    Le fuseau horaire de votre application, comme Africa/Douala. C'est le timezone de l'application.
  • keep_current_subscribersboolean

    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_idstring

    Le client. Absent pour profile_code, car la personne n'est peut-être pas encore cliente.
  • kindstring

    Ce sur quoi porte le message. Voir types de messages aux clients. 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.
  • channelstring

    email, telegram ou whatsapp.
  • recipientstring

    L'adresse e-mail, le numéro WhatsApp ou la conversation Telegram auxquels il est allé, ou serait allé.
  • subjectstring

    La ligne d'objet. Pour un code par e-mail, elle contient le code.
  • textstring

    Le message, en texte brut.
  • sentboolean

    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.

Étapes suivantes