Événements

Un événement enregistre quelque chose qui s'est produit dans votre application, comme une facture payée. Abuna enregistre chaque événement, et l'envoie aussi à votre URL de webhook si vous en avez défini une.

{
  "created_at": 1791143442,
  "data": {
    "amount": 5000,
    "credit": 0,
    "currency": "XAF",
    "invoice_id": "hUPYtkyo",
    "invoice_number": "ACME-000001",
    "kind": "period",
    "metadata": {
      "user_id": "42"
    },
    "paid_at": 1791143442,
    "period_end": 1793821842,
    "period_id": "tKhKXYjr",
    "period_start": 1791143442,
    "subscription": {
      "activated_at": 1791143442,
      "app_id": "VyYjSLf1",
      "cancel_at": null,
      "canceled_at": null,
      "created_at": 1791143442,
      "current_period_end": 1793821842,
      "current_period_start": 1791143442,
      "customer_id": "OljRiqBE",
      "ended_reason": null,
      "id": "coRNVNUz",
      "manage_token": "d6f6ca3a8b285784aed37bd593bab9dea12e",
      "metadata": {
        "user_id": "42"
      },
      "price_id": "UKjuDVyN",
      "starts_at": 1791143442,
      "status": "active"
    },
    "subscription_id": "coRNVNUz"
  },
  "environment": "test",
  "id": "01M447FXSP98350QH3TKE3YG6D",
  "type": "invoice.paid"
}

curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid" \
  -H "Authorization: Bearer sk_test_..."

{
  "items": [
    {
      "created_at": 1791143442,
      "data": {
        "amount": 5000,
        "credit": 0,
        "currency": "XAF",
        "invoice_id": "hUPYtkyo",
        "invoice_number": "ACME-000001",
        "kind": "period",
        "metadata": {
          "user_id": "42"
        },
        "paid_at": 1791143442,
        "period_end": 1793821842,
        "period_id": "tKhKXYjr",
        "period_start": 1791143442,
        "subscription": {
          "activated_at": 1791143442,
          "app_id": "VyYjSLf1",
          "cancel_at": null,
          "canceled_at": null,
          "created_at": 1791143442,
          "current_period_end": 1793821842,
          "current_period_start": 1791143442,
          "customer_id": "OljRiqBE",
          "ended_reason": null,
          "id": "coRNVNUz",
          "manage_token": "d6f6ca3a8b285784aed37bd593bab9dea12e",
          "metadata": {
            "user_id": "42"
          },
          "price_id": "UKjuDVyN",
          "starts_at": 1791143442,
          "status": "active"
        },
        "subscription_id": "coRNVNUz"
      },
      "environment": "test",
      "id": "01M447FXSP98350QH3TKE3YG6D",
      "type": "invoice.paid"
    }
  ],
  "next_cursor": "MDFKOVpROEUxRjJHM0g0SjVLNk03TjhQOVE"
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/events/01M447FXSP98350QH3TKE3YG6D \
  -H "Authorization: Bearer sk_test_..."

{
  "created_at": 1791143442,
  "data": {
    "amount": 5000,
    "credit": 0,
    "currency": "XAF",
    "invoice_id": "hUPYtkyo",
    "invoice_number": "ACME-000001",
    "kind": "period",
    "metadata": {
      "user_id": "42"
    },
    "paid_at": 1791143442,
    "period_end": 1793821842,
    "period_id": "tKhKXYjr",
    "period_start": 1791143442,
    "subscription": {
      "activated_at": 1791143442,
      "app_id": "VyYjSLf1",
      "cancel_at": null,
      "canceled_at": null,
      "created_at": 1791143442,
      "current_period_end": 1793821842,
      "current_period_start": 1791143442,
      "customer_id": "OljRiqBE",
      "ended_reason": null,
      "id": "coRNVNUz",
      "manage_token": "d6f6ca3a8b285784aed37bd593bab9dea12e",
      "metadata": {
        "user_id": "42"
      },
      "price_id": "UKjuDVyN",
      "starts_at": 1791143442,
      "status": "active"
    },
    "subscription_id": "coRNVNUz"
  },
  "environment": "test",
  "id": "01M447FXSP98350QH3TKE3YG6D",
  "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 : subscription.created, puis invoice.created.
• Renouvellement : subscription.updated si un passage à un tarif inférieur 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 : 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.

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.

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.

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) : le premier paiement a réussi et l'abonnement est maintenant active. subscription.paid est enregistré au même moment. Ajoute price_id, le tarif de l'abonnement.
• 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 d'annulation) : le client a confirmé l'annulation, 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.

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 tombe en désuétude faute de paiement. 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.

{
  "customer_id": "OljRiqBE",
  "expired_at": 1791143442,
  "invoice_id": null,
  "metadata": {
    "user_id": "42"
  },
  "plan_offer_id": null,
  "price_id": null,
  "session_id": "ErXGrkep",
  "subscription": {
    "activated_at": 1791143442,
    "app_id": "VyYjSLf1",
    "cancel_at": null,
    "canceled_at": null,
    "created_at": 1791143442,
    "current_period_end": 1793821842,
    "current_period_start": 1791143442,
    "customer_id": "OljRiqBE",
    "ended_reason": null,
    "id": "coRNVNUz",
    "manage_token": "d6f6ca3a8b285784aed37bd593bab9dea12e",
    "metadata": {
      "user_id": "42"
    },
    "price_id": "UKjuDVyN",
    "starts_at": 1791143442,
    "status": "active"
  },
  "subscription_id": "coRNVNUz",
  "type": "cancel"
}

subscription.created

Un abonnement a été créé, via l'API, une session checkout ou un lien de paiement. Il est encore pending.

subscription.paid

La première période de facturation a été payée, donc l'abonnement est maintenant active. Les paiements suivants envoient invoice.paid, et subscription.recovered quand ils ramènent un abonnement past_due à active.

subscription.renewed

Abuna a émis la période de facturation suivante et sa facture. Cela se produit avant la fin de la période payée, 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.

subscription.past_due

La période payée a pris fin et son renouvellement n'est pas payé, donc l'abonnement est maintenant 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.

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

Quelque chose a été programmé ou a changé sur un abonnement actif. Il se déclenche quand une annulation à la fin de la période payée est programmée ou annulée, quand le tarif change (une montée de formule prend effet, ou un passage à un tarif inférieur programmé commence), quand un passage à un tarif inférieur est programmé ou annulé, quand une montée de formule en attente de paiement tombe en désuétude, et quand un nouveau changement en efface un précédent. Pour une annulation programmée, subscription.canceled suit quand elle prend fin. Voir Changer de formule.

subscription.canceled

L'abonnement a pris fin. Il se déclenche quand l'abonnement prend vraiment fin : tout de suite pour une annulation immédiate, ou à la fin de la période payée pour une annulation programmée. Programmer une annulation 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.

plan_offer.created

Une session de changement de formule a créé une offre de formule, ou vous avez proposé un changement depuis le tableau de bord et Abuna a envoyé le lien au client. Une session n'envoie rien au client. 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.

plan_offer.confirmed

Le client a accepté l'offre. Un passage à un tarif inférieur est maintenant programmé, ou une montée de formule est appliquée ou en attente de paiement. subscription.updated se déclenche quand le tarif change ou que le passage à un tarif inférieur 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.

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.

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

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.

customer.updated

Le nom, l'e-mail ou le numéro de téléphone d'un client a changé.

price_change.scheduled

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

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 tarif 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 écrit un avis à un client Test et l'a conservé au lieu de l'envoyer. Cet événement ne va jamais vers votre URL de webhook.