# 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. Source : https://abuna.app/docs/guides/promotion-codes?hl=fr 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 : ```bash 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" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/coupons", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ name: "Black Friday", percent_off: 25, duration: "once", }), }); const coupon = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/coupons", headers={"Authorization": "Bearer sk_test_..."}, json={ "name": "Black Friday", "percent_off": 25, "duration": "once", }, ) coupon = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "name" => "Black Friday", "percent_off" => 25, "duration" => "once", ]), CURLOPT_RETURNTRANSFER => true, ]); $coupon = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "name": "Black Friday", "percent_off": 25, "duration": "once", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/coupons", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var coupon map[string]any json.NewDecoder(res.Body).Decode(&coupon) ``` 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](https://abuna.app/docs/api/coupons.md?hl=fr#create). ## 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 : ```bash 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 }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ coupon: "Kf4Wn7Qa", code: "BLACKFRIDAY", max_redemptions: 100, expires_at: 1798761600, }), }); const code = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes", headers={"Authorization": "Bearer sk_test_..."}, json={ "coupon": "Kf4Wn7Qa", "code": "BLACKFRIDAY", "max_redemptions": 100, "expires_at": 1798761600, }, ) code = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "coupon" => "Kf4Wn7Qa", "code" => "BLACKFRIDAY", "max_redemptions" => 100, "expires_at" => 1798761600, ]), CURLOPT_RETURNTRANSFER => true, ]); $code = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "coupon": "Kf4Wn7Qa", "code": "BLACKFRIDAY", "max_redemptions": 100, "expires_at": 1798761600, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var code map[string]any json.NewDecoder(res.Body).Decode(&code) ``` 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](https://abuna.app/docs/api/promotion-codes.md?hl=fr#create). ## Laisser les clients taper le code Les clients peuvent taper un code sur une [session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout) et sur un [lien d'abonnement](https://abuna.app/docs/quickstart.md?hl=fr#use-a-checkout-link). 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 : ```bash 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}" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "checkout-no-codes-1", }, body: JSON.stringify({ type: "checkout", price_id: "Zt6YbN3q", allow_promotion_codes: false, success_url: "https://example.com/welcome?session_id={SESSION_ID}", }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "checkout-no-codes-1"}, json={ "type": "checkout", "price_id": "Zt6YbN3q", "allow_promotion_codes": False, "success_url": "https://example.com/welcome?session_id={SESSION_ID}", }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: checkout-no-codes-1"], CURLOPT_POSTFIELDS => json_encode([ "type" => "checkout", "price_id" => "Zt6YbN3q", "allow_promotion_codes" => false, "success_url" => "https://example.com/welcome?session_id={SESSION_ID}", ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "allow_promotion_codes": false, "success_url": "https://example.com/welcome?session_id={SESSION_ID}", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "checkout-no-codes-1") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` > **Remarque :** N'envoyez pas `allow_promotion_codes: true` avec `discounts`. Une session qui reçoit les deux renvoie `422` avec un élément `errors` pour `discounts`. ### 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](https://abuna.app/docs/api/subscriptions.md?hl=fr#create). **Créer une page d'abonnement avec la réduction déjà appliquée** cURL : ```bash 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}" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "checkout-black-friday-2", }, body: JSON.stringify({ type: "checkout", price_id: "Zt6YbN3q", discounts: [{ promotion_code: "Wm9Tb2Xs" }], success_url: "https://example.com/welcome?session_id={SESSION_ID}", }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "checkout-black-friday-2"}, json={ "type": "checkout", "price_id": "Zt6YbN3q", "discounts": [{"promotion_code": "Wm9Tb2Xs"}], "success_url": "https://example.com/welcome?session_id={SESSION_ID}", }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: checkout-black-friday-2"], CURLOPT_POSTFIELDS => json_encode([ "type" => "checkout", "price_id" => "Zt6YbN3q", "discounts" => [["promotion_code" => "Wm9Tb2Xs"]], "success_url" => "https://example.com/welcome?session_id={SESSION_ID}", ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "discounts": []any{map[string]any{"promotion_code": "Wm9Tb2Xs"}}, "success_url": "https://example.com/welcome?session_id={SESSION_ID}", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "checkout-black-friday-2") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` 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** ```json { "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`](https://abuna.app/docs/api/events.md?hl=fr#invoice-created) et [`invoice.paid`](https://abuna.app/docs/api/events.md?hl=fr#invoice-paid) portent les mêmes champs. La page de paiement affiche aussi la réduction.