Référence de l'API
Codes promotionnels
Donnez à 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.
Un code promotionnel est le mot qu'un client tape pour obtenir un coupon, comme BLACKFRIDAY. Un coupon peut avoir plusieurs codes, chacun actif ou non, avec sa propre date de fin et sa propre limite. Les codes ignorent la casse : blackfriday fonctionne aussi.
L'objet promotion code
Attributs
idstringIdentifiant unique du code. Les clients tapent le code, pas cet identifiant.app_idstringL'application à laquelle le code appartient.codestringLe texte que les clients tapent sur la page d'abonnement, comme BLACKFRIDAY.activebooleanSi les clients peuvent utiliser le code. Un code désactivé garde ses utilisations et son coupon.expires_attimestampnullableLe dernier moment où le code peut être utilisé, en secondes Unix. Null pour aucune fin.max_redemptionsintegernullableLe nombre maximum d'abonnements qui peuvent utiliser le code. Null pour aucune limite.times_redeemedintegerLe nombre d'abonnements qui ont utilisé le code. Il peut dépassermax_redemptions; voir Lister les codes promotionnels.metadataobjectVos propres clés et valeurs.{}quand il n'y en a pas.created_attimestampQuand le code a été créé, en secondes Unix.couponobjectLe coupon que le code donne.restrictionsobjectQui peut utiliser le code.Afficher les attributsMasquer les attributs
first_time_transactionbooleanQuand il vaut true, seul un client de cette application qui n'a jamais payé de facture peut l'utiliser. La vérification se fait avec l'adresse e-mail du client.
{
"id": "Wm9Tb2Xs",
"app_id": "8ddhXCDW",
"code": "BLACKFRIDAY",
"active": true,
"expires_at": 1798761600,
"max_redemptions": 100,
"times_redeemed": 4,
"metadata": {},
"created_at": 1727600000,
"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
},
"restrictions": {
"first_time_transaction": false
}
}Créer un code promotionnel
POST/v1/apps/{appID}/promotion-codes
Accepte un en-tête Idempotency-Key.
Crée un code pour l'un des coupons de l'application.
Paramètres
couponstringobligatoireL'identifiant du coupon que le code donne. Le coupon ne doit pas être supprimé, dépasser son redeem_by, ou être à court d'utilisations.codestringLe texte que les clients tapent. Utilisez de 1 à 50 lettres, chiffres, traits d'union ou traits de soulignement. Les codes ignorent la casse et doivent être uniques dans l'application. Omettez ce champ et Abuna crée un code de 8 caractères que vous pouvez lire à voix haute.activebooleanSi les clients peuvent l'utiliser tout de suite. Vauttruepar défaut.expires_attimestampLe dernier moment où le code peut être utilisé, en secondes Unix. Il doit être dans le futur.max_redemptionsintegerLe nombre maximum d'abonnements qui peuvent utiliser le code, au moins 1. Omettez-le pour aucune limite.restrictionsobjectQui peut utiliser le code. Omettez-le pour tout le monde.Afficher les paramètresMasquer les paramètres
first_time_transactionbooleanMettez true pour que seul un client qui n'a jamais payé cette application puisse utiliser le code.
metadataobjectVos propres clés et valeurs.
Renvoie le code avec son coupon et 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 coupon absent de l'application renvoie 422 avec le code not_found pour coupon. Un coupon qui ne peut pas être utilisé renvoie 422 avec le code invalid pour coupon. Un code déjà pris par un autre code promotionnel de l'application renvoie 409 avec le code code_taken pour code.
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
}'{
"id": "Wm9Tb2Xs",
"app_id": "8ddhXCDW",
"code": "BLACKFRIDAY",
"active": true,
"expires_at": 1798761600,
"max_redemptions": 100,
"times_redeemed": 0,
"metadata": {},
"created_at": 1727600000,
"coupon": {
"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
},
"restrictions": {
"first_time_transaction": false
}
}Lister les codes promotionnels
GET/v1/apps/{appID}/promotion-codes
Liste les codes promotionnels de l'application, du plus récent au plus ancien, une page à la fois. Chaque élément porte son coupon.
Paramètres de requête
codestringSeulement le code avec ce texte. La casse n'a pas d'importance.couponstringSeulement les codes de ce coupon.limitintegerCombien de codes promotionnels 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.
Un code peut être utilisé par plus d'abonnements que son max_redemptions si des clients payaient déjà au moment où la dernière place s'est remplie. times_redeemed indique le nombre réel.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "Wm9Tb2Xs",
"app_id": "8ddhXCDW",
"code": "BLACKFRIDAY",
"active": true,
"expires_at": 1798761600,
"max_redemptions": 100,
"times_redeemed": 4,
"metadata": {},
"created_at": 1727600000,
"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
},
"restrictions": {
"first_time_transaction": false
}
}
],
"next_cursor": null
}Lire un code promotionnel
GET/v1/apps/{appID}/promotion-codes/{id}
Renvoie le code et son coupon.
Si l'application n'a pas de code avec cet identifiant, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
-H "Authorization: Bearer sk_test_..."{
"id": "Wm9Tb2Xs",
"app_id": "8ddhXCDW",
"code": "BLACKFRIDAY",
"active": true,
"expires_at": 1798761600,
"max_redemptions": 100,
"times_redeemed": 4,
"metadata": {},
"created_at": 1727600000,
"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
},
"restrictions": {
"first_time_transaction": false
}
}Mettre à jour un code promotionnel
PATCH/v1/apps/{appID}/promotion-codes/{id}
Active ou désactive le code, change ses métadonnées, ou les deux. Le code, son coupon, sa date de fin et ses limites restent tels que vous les avez créés. Envoyez au moins un champ.
Paramètres
activebooleanSi les clients peuvent utiliser le code. Envoyez false pour arrêter les nouvelles utilisations. Les abonnements qui l'ont déjà utilisé gardent leur réduction.metadataobjectVos propres clés et valeurs. Il remplace les métadonnées définies avant.
Renvoie le code. Un corps sans aucun des deux champs renvoie 422 avec le code invalid et un élément errors pour active. 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 code avec cet identifiant, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-X PATCH \
-d '{
"active": false
}'{
"id": "Wm9Tb2Xs",
"app_id": "8ddhXCDW",
"code": "BLACKFRIDAY",
"active": false,
"expires_at": 1798761600,
"max_redemptions": 100,
"times_redeemed": 7,
"metadata": {},
"created_at": 1727600000,
"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
},
"restrictions": {
"first_time_transaction": false
}
}Étapes suivantes
- CouponsCréez les réductions que les clients obtiennent avec un code promotionnel, pour un paiement, quelques mois, ou chaque paiement.
- 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.