Référence de l'API
Coupons
Créez les réductions que les clients obtiennent avec un code promotionnel, pour un paiement, quelques mois, ou chaque paiement.
Un coupon est une réduction : un pourcentage ou un montant fixe, pour un paiement, un nombre de mois, ou chaque paiement. Les clients l'utilisent avec un code promotionnel. Vous pouvez aussi appliquer un coupon vous-même quand vous créez une session checkout ou un abonnement. Pour organiser une vente de bout en bout, voyez Organiser une vente avec des codes promotionnels.
L'objet coupon
Attributs
idstringIdentifiant unique du coupon.app_idstringL'application à laquelle le coupon appartient.namestringnullableUn nom pour vous, jusqu'à 100 caractères. La page d'abonnement l'affiche sur la ligne de réduction quand aucun code n'a apporté le coupon.percent_offintegernullableLe pourcentage retiré, de 1 à 99. Null quand le coupon retire un montant fixe.amount_offintegernullableLe montant fixe retiré, dans la plus petite unité de la devise. Null quand le coupon retire un pourcentage.currencystringnullableXAF,XOFouUSD. Défini avecamount_off, et null avecpercent_off.durationstringonce: la première période facturée.repeating: les périodes comprises dansduration_in_months.forever: chaque période. Voir Combien de temps dure une réduction.duration_in_monthsintegernullableLe nombre de mois d'un couponrepeating, comptés depuis le début de l'abonnement. Null pouronceetforever.max_redemptionsintegernullableLe nombre maximum d'abonnements qui peuvent utiliser le coupon. Null pour aucune limite.redeem_bytimestampnullableLe dernier moment où le coupon peut être utilisé, en secondes Unix. Null pour aucune fin.times_redeemedintegerLe nombre d'abonnements qui l'ont utilisé, par l'un de ses codes ou par une réduction que vous avez définie.metadataobjectVos propres clés et valeurs.{}quand il n'y en a pas.created_attimestampQuand le coupon a été créé, en secondes Unix.applies_toobjectnullableLes produits auxquels le coupon s'applique, sous la forme{ "products": [...] }. Null quand il s'applique à tous les produits.validbooleanSi un nouvel abonnement peut utiliser le coupon maintenant : il n'est pas supprimé, son redeem_by n'est pas passé et il reste sous max_redemptions.
{
"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
}Créer un coupon
POST/v1/apps/{appID}/coupons
Accepte un en-tête Idempotency-Key.
Crée un coupon. Envoyez percent_off ou amount_off, pas les deux, et une duration.
Paramètres
namestringUn nom pour vous, jusqu'à 100 caractères. La page d'abonnement l'affiche sur la ligne de réduction quand aucun code n'a apporté le coupon.percent_offintegerLe pourcentage à retirer, de 1 à 99. Arrondi à la plus petite unité de la devise, vers le bas.amount_offintegerLe montant fixe à retirer, dans la plus petite unité de la devise, par exemple 1000 pour 1 000 FCFA. Envoyez currency avec.currencystringXAF,XOFouUSD. Obligatoire avecamount_off, et interdit avecpercent_off.durationstringobligatoireonce,repeatingouforever.duration_in_monthsintegerObligatoire avecrepeating: le nombre de mois de la réduction, à partir de 1. Interdit avec les autres durées.max_redemptionsintegerLe nombre maximum d'abonnements qui peuvent utiliser le coupon, au moins 1. Omettez-le pour aucune limite.redeem_bytimestampLe dernier moment où le coupon peut être utilisé, en secondes Unix. Il doit être dans le futur.applies_toobjectLes produits auxquels le coupon s'applique. Omettez-le pour couvrir tous les produits.Afficher les paramètresMasquer les paramètres
productsarrayDes identifiants de produit, jusqu'à 100. Une liste vide couvre tous les produits.
metadataobjectVos propres clés et valeurs.
Renvoie le coupon avec le statut 201. Un champ manquant ou incorrect renvoie 422 avec le code invalid et un élément errors pour ce champ. Un identifiant de produit absent de l'application renvoie 422 avec un élément errors pour applies_to.products et le code not_found.
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"
}'{
"id": "Kf4Wn7Qa",
"app_id": "8ddhXCDW",
"name": "Black Friday",
"percent_off": 25,
"amount_off": null,
"currency": null,
"duration": "once",
"duration_in_months": null,
"max_redemptions": null,
"redeem_by": null,
"times_redeemed": 0,
"metadata": {},
"created_at": 1727600000,
"applies_to": null,
"valid": true
}Lister les coupons
GET/v1/apps/{appID}/coupons
Liste les coupons de l'application, du plus récent au plus ancien, une page à la fois. Les coupons supprimés ne sont pas listés.
Paramètres de requête
limitintegerCombien de coupons renvoyer, de 1 à 100. Par défaut : 50.cursorstringLa valeurnext_cursorde 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.
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"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
}
],
"next_cursor": null
}Lire un coupon
GET/v1/apps/{appID}/coupons/{id}
Renvoie le coupon. Un coupon supprimé est introuvable.
Si l'application n'a pas de coupon avec cet identifiant, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
-H "Authorization: Bearer sk_test_..."{
"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
}Mettre à jour un coupon
PATCH/v1/apps/{appID}/coupons/{id}
Change le nom du coupon, ses métadonnées, ou les deux. La réduction reste telle que vous l'avez créée : pour changer le pourcentage, le montant ou la durée, créez un autre coupon. Envoyez au moins un champ.
Paramètres
namestringLe nouveau nom, jusqu'à 100 caractères. Envoyeznullpour le retirer.metadataobjectVos propres clés et valeurs. Il remplace les métadonnées définies avant.
Renvoie le coupon. Un corps sans aucun des deux champs renvoie 422 avec le code invalid et un élément errors pour name. Tout autre champ renvoie 400 avec le code invalid_json et un élément errors avec le code unknown_field. Si l'application n'a pas de coupon avec cet identifiant, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-X PATCH \
-d '{
"name": "Black Friday sale"
}'{
"id": "Kf4Wn7Qa",
"app_id": "8ddhXCDW",
"name": "Black Friday sale",
"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
}Supprimer un coupon
DELETE/v1/apps/{appID}/coupons/{id}
Supprime le coupon. Aucun nouvel abonnement ne peut l'utiliser, ni ses codes promotionnels. Un abonnement qui le détient déjà garde sa réduction, et ses nouvelles factures l'affichent encore. Vous ne pouvez pas annuler la suppression.
Renvoie l'identifiant du coupon, deleted: true, et la date de suppression. Si l'application n'a pas de coupon avec cet identifiant, ou si le coupon est déjà supprimé, renvoie 404 avec le code not_found.
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
-H "Authorization: Bearer sk_test_..."{
"id": "Kf4Wn7Qa",
"deleted": true,
"deleted_at": 1727686400
}Étapes suivantes
- Codes promotionnelsDonnez à un coupon des codes que les clients tapent sur la page d'abonnement, chacun avec sa date de fin, sa limite et sa règle pour les nouveaux clients.
- Organiser une vente avec des codes promotionnelsCré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.
- SessionsEnvoyez un client vers une page hébergée pour s'abonner, payer une facture, changer de formule, résilier ou ouvrir son espace client. Puis listez, lisez et expirez ces sessions.