# Coupons > Créez les réductions que les clients obtiennent avec un code promotionnel, pour un paiement, quelques mois, ou chaque paiement. Source : https://abuna.app/docs/api/coupons?hl=fr 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](https://abuna.app/docs/api/promotion-codes.md?hl=fr). Vous pouvez aussi appliquer un coupon vous-même quand vous [créez une session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout) ou [un abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#create). Pour organiser une vente de bout en bout, voyez [Organiser une vente avec des codes promotionnels](https://abuna.app/docs/guides/promotion-codes.md?hl=fr). ## L'objet coupon **Attributs** - `id` (string): Identifiant unique du coupon. - `app_id` (string): L'application à laquelle le coupon appartient. - `name` (string, nullable): Un 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_off` (integer, nullable): Le pourcentage retiré, de 1 à 99. Null quand le coupon retire un montant fixe. - `amount_off` (integer, nullable): Le montant fixe retiré, dans la plus petite unité de la devise. Null quand le coupon retire un pourcentage. - `currency` (string, nullable): `XAF`, `XOF` ou `USD`. Défini avec `amount_off`, et null avec `percent_off`. - `duration` (string): `once` : la première période facturée. `repeating` : les périodes comprises dans `duration_in_months`. `forever` : chaque période. Voir [Combien de temps dure une réduction](https://abuna.app/docs/guides/promotion-codes.md?hl=fr#duration). - `duration_in_months` (integer, nullable): Le nombre de mois d'un coupon `repeating`, comptés depuis le début de l'abonnement. Null pour `once` et `forever`. - `max_redemptions` (integer, nullable): Le nombre maximum d'abonnements qui peuvent utiliser le coupon. Null pour aucune limite. - `redeem_by` (timestamp, nullable): Le dernier moment où le coupon peut être utilisé, en secondes Unix. Null pour aucune fin. - `times_redeemed` (integer): Le nombre d'abonnements qui l'ont utilisé, par l'un de ses codes ou par une réduction que vous avez définie. - `metadata` (object): Vos propres clés et valeurs. `{}` quand il n'y en a pas. - `created_at` (timestamp): Quand le coupon a été créé, en secondes Unix. - `applies_to` (object, nullable): Les produits auxquels le coupon s'applique, sous la forme `{ "products": [...] }`. Null quand il s'applique à tous les produits. - `valid` (boolean): Si 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. **L'objet coupon** ```json { "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` Crée un coupon. Envoyez `percent_off` ou `amount_off`, pas les deux, et une `duration`. **Paramètres** - `name` (string): Un 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_off` (integer): Le pourcentage à retirer, de 1 à 99. Arrondi à la plus petite unité de la devise, vers le bas. - `amount_off` (integer): Le montant fixe à retirer, dans la plus petite unité de la devise, par exemple 1000 pour 1 000 FCFA. Envoyez currency avec. - `currency` (string): `XAF`, `XOF` ou `USD`. Obligatoire avec `amount_off`, et interdit avec `percent_off`. - `duration` (string, obligatoire): `once`, `repeating` ou `forever`. - `duration_in_months` (integer): Obligatoire avec `repeating` : le nombre de mois de la réduction, à partir de 1. Interdit avec les autres durées. - `max_redemptions` (integer): Le nombre maximum d'abonnements qui peuvent utiliser le coupon, au moins 1. Omettez-le pour aucune limite. - `redeem_by` (timestamp): Le dernier moment où le coupon peut être utilisé, en secondes Unix. Il doit être dans le futur. - `applies_to` (object): Les produits auxquels le coupon s'applique. Omettez-le pour couvrir tous les produits. - `products` (array): Des identifiants de produit, jusqu'à 100. Une liste vide couvre tous les produits. - `metadata` (object): Vos 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`. **POST /v1/apps/{appID}/coupons** 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) ``` **Réponse** ```json { "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** - `limit` (integer): Combien de coupons renvoyer, de 1 à 100. Par défaut : 50. - `cursor` (string): 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](https://abuna.app/docs/lists-and-filters.md?hl=fr#pages). 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}/coupons** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/coupons", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/coupons", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/coupons", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Réponse** ```json { "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`. **GET /v1/apps/{appID}/coupons/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", { headers: { Authorization: "Bearer sk_test_..." }, }); const coupon = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", headers={"Authorization": "Bearer sk_test_..."}, ) coupon = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $coupon = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", nil) req.Header.Set("Authorization", "Bearer sk_test_...") 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) ``` **Réponse** ```json { "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** - `name` (string): Le nouveau nom, jusqu'à 100 caractères. Envoyez `null` pour le retirer. - `metadata` (object): Vos 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`. **PATCH /v1/apps/{appID}/coupons/{id}** cURL : ```bash 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" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ name: "Black Friday sale", }), }); const coupon = await response.json(); ``` Python : ```python import requests response = requests.patch( "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", headers={"Authorization": "Bearer sk_test_..."}, json={ "name": "Black Friday sale", }, ) coupon = response.json() ``` PHP : ```php "PATCH", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "name" => "Black Friday sale", ]), CURLOPT_RETURNTRANSFER => true, ]); $coupon = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "name": "Black Friday sale", }) req, _ := http.NewRequest("PATCH", "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", 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) ``` **Réponse** ```json { "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`. **DELETE /v1/apps/{appID}/coupons/{id}** cURL : ```bash curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", { method: "DELETE", headers: { Authorization: "Bearer sk_test_..." }, }); const deleted = await response.json(); ``` Python : ```python import requests response = requests.delete( "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", headers={"Authorization": "Bearer sk_test_..."}, ) deleted = response.json() ``` PHP : ```php "DELETE", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $deleted = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("DELETE", "https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var deleted map[string]any json.NewDecoder(res.Body).Decode(&deleted) ``` **Réponse** ```json { "id": "Kf4Wn7Qa", "deleted": true, "deleted_at": 1727686400 } ```