Skip to content
ABUNA
DocumentationOrganiser une vente avec des codes promotionnels

Guides

Organiser une vente avec des codes promotionnels

Créez un coupon et un code, laissez les clients l'appliquer sur la page d'abonnement, et sachez ce qu'ils paient et combien de temps cela dure.

Voir en Markdown

Organisez une vente sans changer vos prix : créez un coupon, donnez-lui un code comme BLACKFRIDAY, et laissez les clients l'appliquer sur la page d'abonnement. Le client paie moins dès le premier paiement, et les renouvellements suivent la durée du coupon.

Créer un coupon

Un coupon porte la réduction. Envoyez un pourcentage, ou un montant fixe avec sa devise, et sa durée.

Créer un coupon de 25 % pour un seul paiement
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "percent_off": 25,
    "duration": "once"
  }'

Ajoutez applies_to.products pour le limiter à certains produits. Sans ce champ, le coupon couvre tous les produits. Ajoutez max_redemptions pour limiter le nombre d'abonnements, et redeem_by pour l'arrêter à une date. Voir Créer un coupon.

Ajouter un code promotionnel

Donnez au coupon un ou plusieurs codes. Les clients tapent un code sur la page d'abonnement pour obtenir le coupon.

Donner au coupon un code BLACKFRIDAY
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "coupon": "Kf4Wn7Qa",
    "code": "BLACKFRIDAY",
    "max_redemptions": 100,
    "expires_at": 1798761600
  }'

Les codes ignorent la casse, donc blackfriday fonctionne aussi. Omettez code et Abuna crée un code de 8 caractères, comme K7M2QX9P. Un code fonctionne seulement tant que le code et son coupon l'autorisent. Mettez restrictions.first_time_transaction à true pour le garder aux clients qui n'ont jamais payé cette application. Voir Créer un code promotionnel.

Laisser les clients taper le code

Les clients peuvent taper un code sur une session checkout et sur un lien d'abonnement. Vous n'avez rien à envoyer. La page affiche Ajouter un code promo sous le récapitulatif tant que votre application a au moins 1 code utilisable sur ce prix : activé, non expiré, pas épuisé, et valable pour ce produit et cette devise. Quand aucun code n'est utilisable, le champ reste masqué, pour que les clients ne cherchent pas un code qui n'existe pas. La page ne liste jamais vos codes.

Le client tape le code et appuie sur Appliquer. La page affiche alors une ligne Réduction avec le code, le montant retiré, le sous-total et le nouveau total. Le × à côté du code le retire.

Quand un code ne peut pas être utilisé, la page affiche la raison à côté du champ, et le client peut payer sans. La page dit pourquoi avec des mots simples : le code ne fonctionne pas, ne s'applique pas à cette formule, retire trop de ce prix, ou est réservé aux nouveaux clients. Un code réservé aux nouveaux clients est vérifié quand le client valide la page, ou dès qu'il l'applique si vous avez envoyé son e-mail avec la session. Si un code cesse de fonctionner avant le paiement, la page indique qu'il ne s'applique plus et affiche le total complet ; le client le retire pour continuer.

Masquer le champ de code

Pour qu'une session checkout ne prenne pas de code, envoyez allow_promotion_codes: false. Pour afficher le champ même quand aucun code n'est encore utilisable, envoyez true. Une session avec discounts n'a pas de champ de code. Un lien d'abonnement affiche le champ dès qu'un code est utilisable sur son prix.

Créer une page d'abonnement sans champ de code
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-no-codes-1" \
  -d '{
    "type": "checkout",
    "price_id": "Zt6YbN3q",
    "allow_promotion_codes": false,
    "success_url": "https://example.com/welcome?session_id={SESSION_ID}"
  }'

Appliquer une réduction d'avance

Pour accorder la réduction sans demander de code, envoyez discounts sur la page d'abonnement. Il prend une seule entrée, avec coupon ou promotion_code, par identifiant. Vous pouvez faire de même quand vous créez un abonnement.

Créer une page d'abonnement avec la réduction déjà appliquée
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-black-friday-2" \
  -d '{
    "type": "checkout",
    "price_id": "Zt6YbN3q",
    "discounts": [{"promotion_code": "Wm9Tb2Xs"}],
    "success_url": "https://example.com/welcome?session_id={SESSION_ID}"
  }'

Le client voit la ligne de réduction avec le code, ou le nom du coupon quand vous avez envoyé un coupon, et ses conditions. Il n'y a pas de champ de code, et il ne peut pas la retirer. Si la réduction ne correspond plus au prix au moment de valider, la page d'abonnement la refuse ; avec un code, le client peut le retirer et continuer.

Ce que le client paie

Un pourcentage est arrondi à la plus petite unité de la devise, vers le bas. Un montant fixe est retiré tel quel, dans sa propre devise.

Un paiement ne descend jamais sous 100 FCFA pour XAF et XOF, ou 50 cents US pour USD. Si la réduction descendait plus bas, la page d'abonnement refuse le code. Aux renouvellements, la réduction diminue à la place, pour que le paiement reste à ce minimum. Le client la voit sur la page de paiement et sur la facture, sous forme de ligne de réduction.

Combien de temps dure une réduction

  • once : la première période facturée seulement. Si l'abonnement commence par un essai gratuit, c'est la première période payante après l'essai.
  • repeating : chaque période qui commence dans les duration_in_months suivant le début de l'abonnement. Un coupon de 3 mois couvre 3 périodes mensuelles.
  • forever : chaque période, tant que l'abonnement dure.

Les mois d'un coupon repeating comptent depuis le début de l'abonnement, pas depuis le premier paiement. Un essai gratuit plus long que le coupon peut donc utiliser la réduction avant que le client paie quoi que ce soit.

Quand un code cesse de fonctionner

Un client ne peut pas utiliser un code désactivé, dont l'expires_at est passé, ou dont le coupon est supprimé, dont le redeem_by est passé, ou à court d'utilisations. Un coupon réservé à d'autres produits, un montant fixe dans une autre devise, ou une réduction sous le minimum sont refusés aussi.

max_redemptions est vérifié quand un client utilise le code. Si plusieurs clients valident déjà au moment où la dernière place se remplit, ils obtiennent tous la réduction, donc times_redeemed peut dépasser la limite. Les clients qui commencent après sont refusés. Une utilisation compte quand l'essai commence ou quand le premier paiement passe.

Changements de formule

Un abonnement garde sa réduction quand il change de formule seulement si le coupon couvre le nouveau produit : le coupon ne liste aucun produit, ou liste le produit du nouveau prix. Un montant fixe exige aussi que le nouveau prix soit dans la devise du coupon. Sinon, la réduction s'arrête au changement. Un coupon repeating garde sa date de fin d'origine, donc un changement de formule ne le prolonge jamais. Un coupon once qui a déjà pris son paiement ne revient pas.

Ce que vous recevez

Un abonnement avec une réduction a un objet discount. Il contient le coupon, l'identifiant du code qui l'a apporté, et le début et la fin de la réduction. end est défini pour repeating et null pour once et forever.

La réduction sur un abonnement
{
  "coupon": {
    "id": "Kf4Wn7Qa",
    "app_id": "8ddhXCDW",
    "name": "Black Friday",
    "percent_off": 25,
    "amount_off": null,
    "currency": null,
    "duration": "repeating",
    "duration_in_months": 3,
    "max_redemptions": 100,
    "redeem_by": 1798761600,
    "times_redeemed": 4,
    "metadata": {},
    "created_at": 1727600000,
    "applies_to": {
      "products": [
        "pR4dWx9K"
      ]
    },
    "valid": true
  },
  "promotion_code": "Wm9Tb2Xs",
  "start": 1727600000,
  "end": 1730192000
}

Le amount d'une facture est déjà après sa réduction. discount indique ce qui a été retiré, et coupon_id et promotion_code_id nomment la source. La page de la facture, et les webhooks invoice.created et invoice.paid portent les mêmes champs. La page de paiement affiche aussi la réduction.

Étapes suivantes