Skip to content
ABUNA
DocumentationPrix

Référence de l'API

Prix

Fixez le prix d'un produit et sa fréquence de renouvellement : chaque jour, chaque semaine, chaque mois ou chaque année.

Voir en Markdown

Les prix fixent combien coûte un produit et à quel rythme il se renouvelle : chaque jour, chaque semaine, chaque mois ou chaque année. Un produit peut avoir plusieurs prix, par exemple un mensuel et un annuel.

L'objet price

Attributs

  • idstring

    Identifiant unique du prix.
  • product_idstring

    Le produit auquel appartient le prix.
  • namestring

    Le nom du prix, par exemple Monthly.
  • currencystring

    XAF, XOF ou USD.
  • amountinteger

    Ce que le client paie à chaque période de facturation, dans la plus petite unité de la devise : en francs pour le XAF et le XOF, en cents pour l'USD.
  • intervalstring

    L'unité d'une période de facturation : day, week, month ou year.
  • interval_countinteger

    Combien d'intervalles composent une période de facturation. month avec 3 facture tous les 3 mois.
  • created_attimestamp

    Quand le prix a été créé, en secondes Unix.
  • trial_daysintegernullable

    Durée de l'essai gratuit par défaut, de 1 à 365 jours. Null signifie aucun essai. Définie à la création et non modifiable.
  • archived_attimestampnullable

    Quand le prix a été archivé. Un prix archivé ne démarre aucun nouvel abonnement.
  • pending_changeobjectnullable

    Le changement de montant programmé pour le prix, ou null quand il n'y en a pas. Un prix en a au plus un.
    Afficher les attributsMasquer les attributs
    • idstring

      Identifiant unique du changement. Les événements de changement de prix le portent comme price_change_id.
    • amountinteger

      Le nouveau montant, dans la plus petite unité de la devise.
    • previous_amountinteger

      Le montant avant le changement.
    • currencystring

      La devise du prix.
    • effective_attimestamp

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

      Le fuseau horaire de votre application, par exemple Africa/Douala, le même que le timezone de l'application. effective_at est minuit dans ce fuseau.
    • keep_current_subscribersboolean

      true quand toutes les personnes abonnées ce jour-là gardent l'ancien montant.
    • created_attimestamp

      Quand le changement a été programmé, en secondes Unix.
L'objet price
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": null
}

Créer un prix

POST/v1/apps/{appID}/prices

Accepte un en-tête Idempotency-Key.

Crée un prix pour l'un des produits de l'application.

Les clients paient par mobile money en FCFA, quelle que soit la devise du prix. Un prix en USD est débité au taux de change du jour plus 2 %, arrondi au franc supérieur, et les 2 % font partie de ce que vous recevez. Entre XOF et XAF, le montant se convertit 1 pour 1. Le taux est enregistré sur chaque paiement. Voir Paiement en FCFA.

Paramètres

  • product_idstringobligatoire

    Le produit auquel donner ce prix.
  • namestringobligatoire

    Le nom du prix, par exemple Monthly.
  • currencystringobligatoire

    XAF, XOF ou USD. Les minuscules fonctionnent aussi.
  • amountintegerobligatoire

    Ce que le client paie à chaque période de facturation, dans la plus petite unité de la devise : en francs pour le XAF et le XOF, en cents pour l'USD, donc 1000 vaut 10,00 $. Doit être supérieur à 0.
  • intervalstringobligatoire

    day, week, month ou year.
  • trial_daysinteger

    Durée facultative de l'essai gratuit, de 1 à 365 jours. Omettez ce champ ou envoyez null pour ne pas proposer d'essai. Non modifiable ensuite. Voir Essais gratuits.
  • interval_countinteger

    Combien d'intervalles composent une période de facturation. Par défaut 1. Au plus 365 jours, 52 semaines, 12 mois ou 1 an.

Renvoie le prix avec le statut 201. Un champ invalide renvoie 422 avec le code invalid. Si l'application n'a aucun produit avec ce product_id, renvoie 404 avec le code not_found et un élément errors pour product_id.

POST /v1/apps/{appID}/prices
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}'
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": null
}

Lister les prix

GET/v1/apps/{appID}/prices

Liste les prix de l'application, tous produits confondus et archivés compris, du plus récent au plus ancien, une page à la fois.

Paramètres de requête

  • limitinteger

    Combien de prix 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.

Renvoie items et next_cursor, comme décrit dans Listes et filtres. Une valeur non autorisée, comme un limit supérieur à 100, renvoie 422 avec le code invalid et le nom du paramètre dans errors.

GET /v1/apps/{appID}/prices
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "items": [
    {
      "id": "Zt6YbN3q",
      "product_id": "pR4dWx9K",
      "name": "Monthly",
      "currency": "XAF",
      "amount": 5000,
      "interval": "month",
      "interval_count": 1,
      "trial_days": null,
      "created_at": 1727600000,
      "archived_at": null,
      "pending_change": null
    }
  ],
  "next_cursor": null
}

Modifier un prix

PATCH/v1/apps/{appID}/prices/{id}

Renomme le prix. Son montant, sa devise, sa période de facturation et son lien d'abonnement restent les mêmes. Pour changer ce que paient les clients, programmez un changement de prix.

La durée de l'essai ne peut pas changer. Créez un nouveau prix pour définir une autre valeur de trial_days.

Paramètres

  • namestringobligatoire

    Le nouveau nom, par exemple Monthly plan.

Renvoie le prix. Un nom vide renvoie 422 avec le code invalid. Si l'application n'a aucun prix avec cet ID, renvoie 404 avec le code not_found.

PATCH /v1/apps/{appID}/prices/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q \
  -X PATCH \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Monthly plan"}'
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly plan",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": null
}

Archiver un prix

POST/v1/apps/{appID}/prices/{id}/archive

Accepte un en-tête Idempotency-Key.

Archive le prix. Il ne démarre aucun nouvel abonnement, et les abonnements qui l'utilisent déjà continuent de se renouveler. Archiver un prix déjà archivé ne change rien. Pour revenir en arrière, désarchivez le prix.

Renvoie le prix. Si l'application n'a aucun prix avec cet ID, renvoie 404 avec le code not_found.

POST /v1/apps/{appID}/prices/{id}/archive
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": 1727686400,
  "pending_change": null
}

Désarchiver un prix

POST/v1/apps/{appID}/prices/{id}/unarchive

Accepte un en-tête Idempotency-Key.

Désarchive le prix. Il peut de nouveau démarrer des abonnements, et son lien d'abonnement fonctionne de nouveau. Désarchiver un prix qui n'est pas archivé ne change rien.

Renvoie le prix. Si l'application n'a aucun prix avec cet ID, renvoie 404 avec le code not_found.

POST /v1/apps/{appID}/prices/{id}/unarchive
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": null
}

Programmer un changement de prix

POST/v1/apps/{appID}/prices/{id}/change

Accepte un en-tête Idempotency-Key.

Programme un nouveau montant pour le prix, à partir d'un jour situé au moins 14 jours plus tard. Le montant ne change jamais tout de suite. La devise et la période de facturation ne peuvent pas changer. Pour en changer, créez un nouveau prix.

À partir du début de ce jour dans le fuseau horaire de votre application, les pages d'abonnement et les nouveaux abonnements appliquent le nouveau montant. Chaque abonné en cours le paie à partir de son premier renouvellement à cette date ou après. Abuna leur envoie tous un e-mail maintenant avec le montant qu'ils paieront, après leur réduction éventuelle, et la date à laquelle il s'applique pour la première fois, et leur écrit aussi sur Telegram s'ils l'ont choisi. Les clients qui s'abonnent pendant que le changement est en attente reçoivent le même message au moment de s'abonner.

Avec keep_current_subscribers, toutes les personnes abonnées ce jour-là continuent de payer l'ancien montant tant qu'elles restent abonnées, et seuls les abonnés suivants paient le nouveau. Un abonné qui passe à un autre prix puis revient paie le montant du prix à ce moment-là.

Un prix a un seul changement en attente. En programmer un autre le remplace. Si le remplacement garde les abonnés en cours sur l'ancien montant, ceux qui ont été informés du changement précédent reçoivent un e-mail disant que leur prix ne change pas. Abuna enregistre un price_change.scheduled événement, et price_change.applied quand le nouveau montant démarre.

Paramètres

  • amountintegerobligatoire

    Le nouveau montant, dans la plus petite unité de la devise. Doit être supérieur à 0 et différent du montant actuel.
  • effective_attimestampobligatoire

    N'importe quelle heure du jour où le nouveau montant démarre, en secondes Unix. Abuna la ramène au début de ce jour dans le fuseau horaire de votre application. Ce jour doit être au moins 14 jours après aujourd'hui dans ce fuseau.
  • keep_current_subscribersboolean

    Garder toutes les personnes abonnées ce jour-là sur l'ancien montant. Par défaut false.

Renvoie le prix avec pending_change défini. Une vérification échouée renvoie 422 avec le code invalid, et chaque élément errors nomme le champ : amount avec invalid ou unchanged, ou effective_at avec required ou too_soon. Tout autre champ, comme currency ou interval, renvoie 400 avec le code invalid_json. Si l'application n'a aucun prix avec cet ID, renvoie 404 avec le code not_found. Une fois que le changement en attente atteint son effective_at, il ne peut plus être remplacé avant d'être appliqué, et la requête renvoie 409 avec le code change_in_effect. Voir Quand le changement prend effet.

POST /v1/apps/{appID}/prices/{id}/change
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 6000, "effective_at": 1730458800, "keep_current_subscribers": false}'
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": {
    "id": "W4hN7gPc",
    "amount": 6000,
    "previous_amount": 5000,
    "currency": "XAF",
    "effective_at": 1730415600,
    "timezone": "Africa/Douala",
    "keep_current_subscribers": false,
    "created_at": 1727700000
  }
}

Annuler un changement de prix

POST/v1/apps/{appID}/prices/{id}/change/cancel

Accepte un en-tête Idempotency-Key.

Annule le changement en attente du prix, donc le montant reste tel quel. Si des abonnés en cours devaient passer au nouveau montant, Abuna leur envoie un e-mail disant que leur prix ne change pas. Abuna enregistre un price_change.canceled événement.

Renvoie le prix avec pending_change à null. Si l'application n'a aucun prix avec cet ID, renvoie 404 avec le code not_found. Sans changement en attente, renvoie 409 avec le code no_pending_change. Une fois que le changement atteint son effective_at, il ne peut plus être annulé, et la requête renvoie 409 avec le code change_in_effect.

POST /v1/apps/{appID}/prices/{id}/change/cancel
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Zt6YbN3q",
  "product_id": "pR4dWx9K",
  "name": "Monthly",
  "currency": "XAF",
  "amount": 5000,
  "interval": "month",
  "interval_count": 1,
  "trial_days": null,
  "created_at": 1727600000,
  "archived_at": null,
  "pending_change": null
}

Quand le changement prend effet

Un changement prend effet à son effective_at, et Abuna enregistre price_change.applied dans la minute environ qui suit. Entre-temps, pending_change montre encore le changement, et l'annuler ou le remplacer renvoie 409 avec le code change_in_effect. Une fois price_change.applied enregistré, pending_change est null et vous pouvez programmer un nouveau changement.

Étapes suivantes