Abonnements

Un abonnement facture un client pour un tarif, une période de facturation à la fois. Il démarre pending, devient active quand le client paie la première période, est past_due pendant qu'un renouvellement attend d'être payé, et se termine canceled. Voir Statuts.

{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "active",
  "starts_at": 1727600000,
  "activated_at": 1727600100,
  "canceled_at": null,
  "cancel_at": null,
  "current_period_start": 1727600000,
  "current_period_end": 1730192000,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}'

{
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "status": "pending",
    "starts_at": 1727600000,
    "activated_at": null,
    "canceled_at": null,
    "cancel_at": null,
    "current_period_start": null,
    "current_period_end": null,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
  },
  "period": {
    "id": "T6yVr3Dp",
    "subscription_id": "x9QbL2sK",
    "price_id": "Zt6YbN3q",
    "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
    "starts_at": 1727600000,
    "ends_at": 1730192000,
    "period_index": 0,
    "grace_period_ends_at": 1727686400,
    "paid_at": null,
    "paused_at": null,
    "in_force": true,
    "created_at": 1727600000
  }
}

curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \
  -H "Authorization: Bearer sk_test_..."

{
  "items": [
    {
      "id": "x9QbL2sK",
      "customer_id": "Cu5tM8rA",
      "price_id": "Zt6YbN3q",
      "status": "active",
      "starts_at": 1727600000,
      "activated_at": 1727600100,
      "canceled_at": null,
      "cancel_at": null,
      "current_period_start": 1727600000,
      "current_period_end": 1730192000,
      "ended_reason": null,
      "metadata": {
        "user_id": "42"
      },
      "created_at": 1727600000,
      "customer": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      },
      "price": {
        "name": "Monthly",
        "amount": 5000,
        "currency": "XAF",
        "interval": "month",
        "interval_count": 1
      },
      "next_payment_at": 1730192000
    }
  ],
  "next_cursor": null
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \
  -H "Authorization: Bearer sk_test_..."

{
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "canceled_at": null,
    "cancel_at": null,
    "current_period_start": 1727600000,
    "current_period_end": 1730192000,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
  },
  "subscription_page_url": "https://app.abuna.app/portal/8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
  "customer": {
    "id": "Cu5tM8rA",
    "app_id": "8ddhXCDW",
    "name": "Jane Doe",
    "phone_number": "+237671234567",
    "email": "jane@example.com",
    "created_at": 1727600000,
    "telegram_connected": false
  },
  "price": {
    "id": "Zt6YbN3q",
    "product_id": "pR4dWx9K",
    "name": "Monthly",
    "currency": "XAF",
    "amount": 5000,
    "interval": "month",
    "interval_count": 1,
    "created_at": 1727600000,
    "archived_at": null
  },
  "periods": [
    {
      "id": "T6yVr3Dp",
      "starts_at": 1727600000,
      "ends_at": 1730192000,
      "grace_period_ends_at": 1727686400,
      "paid_at": 1727600100,
      "pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
      "invoice": {
        "id": "V2nC8xEi",
        "app_id": "8ddhXCDW",
        "period_id": "T6yVr3Dp",
        "subscription_id": "x9QbL2sK",
        "number": "MYST-000124",
        "status": "paid",
        "kind": "period",
        "amount": 5000,
        "credit": 0,
        "currency": "XAF",
        "item_label": "Monthly",
        "buyer_name": "Jane Doe",
        "buyer_email": "jane@example.com",
        "seller_name": "My store",
        "period_start": 1727600000,
        "period_end": 1730192000,
        "due_at": 1727686400,
        "created_at": 1727600000,
        "paid_at": 1727600100,
        "voided_at": null
      },
      "invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d"
    }
  ],
  "payments": [
    {
      "id": "m7Yw4NcJ",
      "app_id": "8ddhXCDW",
      "period_id": "T6yVr3Dp",
      "driver": "sandbox",
      "provider": "test",
      "provider_reference": "test_9f3b7d1a5c2e8f4b6d0a",
      "amount": 5000,
      "currency": "XAF",
      "status": "succeeded",
      "message": null,
      "created_at": 1727600090,
      "fee": 100,
      "session_id": null,
      "method_label": "Successful payment (test)"
    }
  ],
  "pending_change": {
    "id": "H3nM8cGb",
    "type": "downgrade",
    "price": {
      "id": "Kw3FgT7e",
      "name": "Basic monthly",
      "amount": 2000,
      "currency": "XAF",
      "interval": "month",
      "interval_count": 1
    },
    "requested_by": "customer",
    "created_at": 1728464000,
    "amount_due": null,
    "credit": null,
    "expires_at": null,
    "pay_url": null,
    "effective_at": 1730192000
  },
  "plan_offer": null,
  "plan_changes": [
    {
      "id": "H3nM8cGb",
      "direction": "downgrade",
      "status": "scheduled",
      "from_price": {
        "id": "Zt6YbN3q",
        "name": "Monthly",
        "amount": 5000,
        "currency": "XAF",
        "interval": "month",
        "interval_count": 1
      },
      "to_price": {
        "id": "Kw3FgT7e",
        "name": "Basic monthly",
        "amount": 2000,
        "currency": "XAF",
        "interval": "month",
        "interval_count": 1
      },
      "requested_by": "customer",
      "amount": null,
      "credit": null,
      "effective_at": 1730192000,
      "created_at": 1728464000,
      "resolved_at": null
    }
  ]
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \
  -X PATCH \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"user_id": "42"}}'

{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "active",
  "starts_at": 1727600000,
  "activated_at": 1727600100,
  "canceled_at": null,
  "cancel_at": null,
  "current_period_start": 1727600000,
  "current_period_end": 1730192000,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"at_period_end": true}'

{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "active",
  "starts_at": 1727600000,
  "activated_at": 1727600100,
  "canceled_at": null,
  "cancel_at": 1730192000,
  "current_period_start": 1727600000,
  "current_period_end": 1730192000,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume \
  -X POST \
  -H "Authorization: Bearer sk_test_..."

{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "active",
  "starts_at": 1727600000,
  "activated_at": 1727600100,
  "canceled_at": null,
  "cancel_at": null,
  "current_period_start": 1727600000,
  "current_period_end": 1730192000,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options \
  -H "Authorization: Bearer sk_test_..."

{
  "data": [
    {
      "price": {
        "id": "Hc8LmV2s",
        "name": "Pro monthly",
        "amount": 10000,
        "currency": "XAF",
        "interval": "month",
        "interval_count": 1
      },
      "direction": "upgrade",
      "amount_due": 6666,
      "credit": 3334,
      "new_billing_date": 1731142400,
      "effective_at": null
    },
    {
      "price": {
        "id": "Kw3FgT7e",
        "name": "Basic monthly",
        "amount": 2000,
        "currency": "XAF",
        "interval": "month",
        "interval_count": 1
      },
      "direction": "downgrade",
      "amount_due": 0,
      "credit": 0,
      "new_billing_date": null,
      "effective_at": 1730192000
    }
  ]
}

Statuts

• pending : créé, et en attente du premier paiement. Si la première période n'est pas payée avant sa date limite de paiement, l'abonnement est canceled avec ended_reason unpaid.
• active : chaque période qui a commencé est payée.
• past_due : un renouvellement a commencé et n'est pas encore payé.
• canceled : terminé. ended_reason dit pourquoi. Un abonnement annulé ne peut pas être redémarré.

Renouvellements et past_due

Abuna émet la période de facturation suivante et sa facture avant la fin de la période payée, aussi longtemps à l'avance que l'indique le renewal_lead_days de votre application : 0 à 7, 3 par défaut. Abuna envoie subscription.renewed et invoice.created, et envoie au client par e-mail la facture avec son lien de paiement. L'abonnement reste active, et le client peut payer tout de suite. La nouvelle période démarre toujours quand la période payée se termine, même si elle est payée en avance.

Si le renouvellement est encore impayé quand la période payée se termine, l'abonnement devient past_due et Abuna envoie subscription.past_due. Quand la facture est payée, l'abonnement est de nouveau active, et Abuna envoie subscription.recovered. Un renouvellement payé avant la fin de la période payée ne passe jamais par past_due. Avec renewal_lead_days à 0, ou tant qu'une rétrogradation attend la fin de la période, la facture part à la fin de la période, donc l'abonnement est past_due jusqu'à ce que le client paie.

Si la période n'est pas payée avant sa date limite de paiement, l'abonnement est canceled avec ended_reason unpaid, et Abuna envoie subscription.canceled avec la raison non_payment. La date limite de paiement est legrace_period_ends_at de la période de facturation : le début de la période plus le grace_period_days de votre application, et jamais après la fin de la période.

current_period_start et current_period_end continuent de montrer la dernière période payée tant que l'abonnement est past_due. Un abonnement past_due peut encore :

• Être payé via son lien de paiement, une session de paiement, ou l'espace client.
• Être annulé. Une annulation à la fin de la période payée le termine maintenant, parce que la période en cours n'est pas payée.
• Changer de formule. Une mise à niveau démarre tout de suite une période complète au nouveau tarif, et une rétrogradation attend la fin de la période en cours. Voir Mises à niveau.

Paiements qui arrivent en retard

Un paiement par mobile money que le client a approuvé peut être confirmé par le prestataire des heures plus tard. Si la facture a été annulée entre-temps, Abuna enregistre quand même le paiement : il est succeeded, la facture devient paid, Abuna envoie invoice.paid, et le client reçoit un reçu.

• Si l'abonnement a pris fin uniquement parce que ce paiement n'était pas arrivé (ended_reason unpaid), et que la période qu'il paie n'est pas encore terminée, l'abonnement revient : status est active, canceled_at et ended_reason sont de nouveau null, et Abuna envoie subscription.recovered, ou subscription.paid pour un premier paiement. Un premier paiement a besoin de place dans la limite d'abonnés Réels de votre forfait, comme au paiement.
• Sinon l'abonnement reste tel quel : annulé par vous ou le client, remplacé, au-delà de la période payée, ou une mise à niveau qui a expiré. Vous voudrez peut-être rembourser le client.

Dans les deux cas, les membres de l'équipe qui reçoivent les e-mails sur les paiements ou les annulations en reçoivent un à ce sujet.

Métadonnées

metadata contient vos propres clés et valeurs sur un abonnement, comme l'ID de votre utilisateur. Définissez-le quand vous créez l'abonnement, transmettez-le à une session de paiement, ou mettez-le à jour plus tard. Chaque lecture le renvoie.

• Jusqu'à 20 clés.
• Chaque clé fait 1 à 40 caractères.
• Chaque valeur est une chaîne de 500 caractères au plus. Les nombres, les booléens, les objets et null ne sont pas autorisés.

Les événements subscription, invoice et plan_offer portent le metadata de cet abonnement. Les événements de session portent plutôt le metadata de la session. Transmettez le metadata sur chaque session que vous créez. Voir Types d'événement.

Annuler un abonnement

Une annulation peut prendre effet maintenant ou à la fin de la période payée. Vous choisissez le moment quand vous annulez dans le tableau de bord ou l'API. Pour les clients qui annulent dans l'espace client, c'est le réglage Quand les clients annulent de l'application qui décide, soit customer_cancel. Les nouvelles applications démarrent avec at_period_end. Une session d'annulation utilise aussi ce réglage, sauf si vous envoyez at_period_end.

• Maintenant. L'abonnement prend fin immédiatement et toute facture impayée est annulée.
• Fin de la période payée. L'abonnement reste active et porte cancel_at. Le client garde l'accès qu'il a payé. Abuna n'émet aucun renouvellement et n'envoie aucun rappel de renouvellement, et annule une facture de renouvellement déjà envoyée et qui n'est pas payée. Un renouvellement que le client a déjà payé compte comme période payée, donc l'abonnement prend fin quand elle se termine. Le tableau de bord et l'espace client affichent « Prend fin le » avec la date. À ce moment-là, l'abonnement devient canceled.
• Période impayée. Si la période en cours n'est pas encore payée, une annulation de fin de période met fin à l'abonnement maintenant et annule la facture impayée. Le tableau de bord et l'espace client le disent avant que la personne confirme.
• Revenir en arrière. Jusqu'à la date de fin, vous pouvez conserver l'abonnement dans le tableau de bord ou avec l'endpoint de reprise, et le client peut le conserver dans l'espace client. La facturation continue comme avant.

Le client reçoit un e-mail quand une annulation est programmée, avec la date de fin et comment conserver l'abonnement, un quand elle prend fin, et une courte confirmation si elle est annulée. Votre endpoint de webhook reçoit subscription.updated quand une annulation est programmée ou annulée, et subscription.canceled quand l'abonnement prend fin. Voir Notifications aux clients.

Le mode Test fonctionne de la même façon. Abuna enregistre les e-mails pour un client Test au lieu de les envoyer, et les applications Test et Réelles gardent leur propre réglage Quand les clients annulent.

Changer de formule

Un abonnement active ou past_due peut passer à un autre tarif. Le client le fait dans son espace client, ou confirme un changement que vous lui envoyez avec une session de changement de formule. Vous ne pouvez pas changer le tarif directement, parce qu'une mise à niveau a besoin que le client paie.

Quels tarifs

Tout autre tarif du même produit dans la même devise, sauf s'il est archivé. Jamais un tarif d'un autre produit ni dans une autre devise. Si aucun tarif n'est éligible, l'espace client n'affiche aucune option de changement de formule. Un abonnement encore pending ne peut pas changer de formule.

Mise à niveau ou rétrogradation

Abuna compare le coût par jour : le montant du tarif divisé par la durée en jours d'une de ses périodes démarrant maintenant. Un tarif qui coûte plus par jour est une mise à niveau. Un tarif qui coûte autant ou moins est une rétrogradation. Cela fonctionne entre intervalles, donc passer d'un mensuel à un annuel suit la même règle.

Mises à niveau

Si la période en cours est payée, le client paie la différence maintenant et garde l'ancienne formule jusqu'à ce que ce paiement réussisse. Une facture de renouvellement déjà envoyée pour l'ancien tarif et non payée est annulée, et la suivante est émise au nouveau tarif. Si le client a déjà payé la période suivante avant qu'elle commence, une mise à niveau attend que cette période démarre : jusque-là, l'espace client ne propose aucune mise à niveau, et un changement renvoie 409 avec le code renewal_paid_early. À ce moment-là, la nouvelle formule démarre avec une période complète entière au nouveau tarif, et la date de facturation passe à la date de paiement.

Le montant est le nouveau tarif moins la valeur inutilisée de la période en cours. La valeur inutilisée est la valeur de la période multipliée par les jours entiers restants, divisée par les jours de la période. La valeur de la période est ce que sa facture a facturé plus tout crédit qu'elle porte, donc une deuxième mise à niveau dans la même période ne perd rien. Le résultat est arrondi à l'entier inférieur et ne descend jamais sous 0. Avec 20 jours restants sur 30 d'une période de 5 000 FCFA, passer à un tarif de 10 000 FCFA coûte 10000 − 3334 = 6666, et credit vaut 3334.

• Rien à payer. Quand le montant est 0, la mise à niveau prend effet immédiatement. Sa facture est créée déjà payée.
• Pas payée à temps. La mise à niveau expire à son expires_at : les jours de paiement de votre application à partir de la demande, ou la fin de la période en cours si elle arrive avant. Sa facture est annulée et l'ancienne formule continue. Il n'y a aucune pénalité. Si la mise à niveau a remplacé une annulation programmée, l'annulation est reprogrammée à sa date d'origine, et subscription.updated porte son cancel_at.
• Période en cours impayée. Si la période en cours n'est pas encore payée, comme tant que l'abonnement est past_due, Abuna annule sa facture et démarre une période complète au nouveau tarif maintenant. La nouvelle formule est en vigueur immédiatement et le client la paie via son lien de paiement, avec les jours de paiement habituels. Il n'y a aucun crédit. Tant qu'un paiement sur l'ancienne facture est en cours, le changement renvoie 409 avec le code payment_in_progress.

La facture d'une mise à niveau a kind plan_change et le temps inutilisé dans credit. Son amount est ce que le client paie.

Une mise à niveau avec quelque chose à payer exige que votre application accepte les paiements. Jusque-là, le changement renvoie 422 avec le code not_accepting_payments. Une mise à niveau sans rien à payer, et une rétrogradation, fonctionnent dans les deux cas.

Rétrogradations

Une rétrogradation ne coûte rien maintenant et ne rembourse rien. Le client garde la formule actuelle jusqu'à la fin de la période payée, et la période suivante est émise au nouveau tarif quand la période payée se termine, pas avant. Une facture de renouvellement déjà envoyée pour l'ancien tarif et non payée est annulée. Si le client a déjà payé la période suivante, la rétrogradation démarre quand cette période se termine. Jusque-là, le client peut l'annuler dans son espace client, et vous pouvez le faire avec Conserver un abonnement. Une rétrogradation programmée figure dans pending_change et dans scheduled_price_change sur subscription.updated.

Une rétrogradation peut être programmée tant que la période en cours est encore impayée. Elle démarre tout de même à la fin de cette période, et si la période reste impayée, l'abonnement prend fin pour non-paiement comme d'habitude. Tant qu'une rétrogradation est programmée, le rappel de renouvellement indique le nouveau tarif.

Un changement à la fois

Un abonnement contient au plus l'un de ces éléments : une annulation programmée, une rétrogradation programmée, ou une mise à niveau en attente de paiement. En démarrer un remplace l'autre. Une mise à niveau remplacée a sa facture annulée, et le changement remplacé reçoit le statut replaced. Tant que le paiement de cette mise à niveau est en cours, elle ne peut pas être remplacée : la requête renvoie 409 avec le code payment_in_progress.

Redemander le changement déjà en attente, vers le même tarif, ne change rien et le renvoie tel quel.

Un changement que vous envoyez au client avec une session de changement de formule attend qu'il le confirme. Un abonnement a au plus un changement en attente d'être confirmé. Un nouveau, ou un changement de formule que le client fait dans l'espace client, le remplace. Le confirmer remplace une annulation programmée, une rétrogradation programmée ou une mise à niveau en attente de paiement, et la page de confirmation le dit d'abord. Annuler l'abonnement maintenant annule une mise à niveau en attente de paiement et retire le changement en attente d'être confirmé.

Dans l'espace client

L'espace client liste chaque tarif éligible avec ce qu'il coûte maintenant : le montant à payer et la nouvelle date de facturation pour une mise à niveau, ou la date à laquelle elle démarre pour une rétrogradation. Une mise à niveau envoie le client vers son lien de paiement, sauf s'il n'y a rien à payer. Tant qu'une mise à niveau attend le paiement, l'espace client l'affiche avec son lien de paiement. Conserver l'abonnement dans l'espace client annule aussi une rétrogradation programmée. Pour envoyer un client vers l'espace client avec un lien de retour vers votre application, utilisez Créer une session de portail.

La page de confirmation

L'url d'une session de changement de formule ouvre une page avec la formule actuelle, la nouvelle, et ce que coûte le changement, calculé au chargement de la page. Le client confirme là, et le changement suit les mêmes règles que dans l'espace client. La page cesse de fonctionner quand la session expire (7 jours, ou la fin de la période en cours si elle arrive avant), quand un changement plus récent la remplace, ou une fois qu'elle est utilisée.

Abuna n'envoie pas d'e-mail au client quand vous créez une session de changement de formule, alors envoyez-le vous-même vers son url. Le client reçoit un e-mail quand une mise à niveau prend effet et quand une rétrogradation est programmée. Rien n'est envoyé quand une mise à niveau commence à attendre le paiement, quand elle expire, ou quand une rétrogradation est annulée. Voir Notifications aux clients. En mode Test, Abuna enregistre ces e-mails au lieu de les envoyer.