# 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. Source : https://abuna.app/docs/api/promotion-codes?hl=fr Un code promotionnel est le mot qu'un client tape pour obtenir un [coupon](https://abuna.app/docs/api/coupons.md?hl=fr), 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** - `id` (string): Identifiant unique du code. Les clients tapent le code, pas cet identifiant. - `app_id` (string): L'application à laquelle le code appartient. - `code` (string): Le texte que les clients tapent sur la page d'abonnement, comme BLACKFRIDAY. - `active` (boolean): Si les clients peuvent utiliser le code. Un code désactivé garde ses utilisations et son coupon. - `expires_at` (timestamp, nullable): Le dernier moment où le code peut être utilisé, en secondes Unix. Null pour aucune fin. - `max_redemptions` (integer, nullable): Le nombre maximum d'abonnements qui peuvent utiliser le code. Null pour aucune limite. - `times_redeemed` (integer): Le nombre d'abonnements qui ont utilisé le code. Il peut dépasser `max_redemptions` ; voir [Lister les codes promotionnels](https://abuna.app/docs/api/promotion-codes.md?hl=fr#list). - `metadata` (object): Vos propres clés et valeurs. `{}` quand il n'y en a pas. - `created_at` (timestamp): Quand le code a été créé, en secondes Unix. - `coupon` (object): Le [coupon](https://abuna.app/docs/api/coupons.md?hl=fr#object) que le code donne. - `restrictions` (object): Qui peut utiliser le code. - `first_time_transaction` (boolean): Quand 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. **L'objet promotion code** ```json { "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` Crée un code pour l'un des coupons de l'application. **Paramètres** - `coupon` (string, obligatoire): L'identifiant du coupon que le code donne. Le coupon ne doit pas être supprimé, dépasser son redeem_by, ou être à court d'utilisations. - `code` (string): Le 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. - `active` (boolean): Si les clients peuvent l'utiliser tout de suite. Vaut `true` par défaut. - `expires_at` (timestamp): Le dernier moment où le code peut être utilisé, en secondes Unix. Il doit être dans le futur. - `max_redemptions` (integer): Le nombre maximum d'abonnements qui peuvent utiliser le code, au moins 1. Omettez-le pour aucune limite. - `restrictions` (object): Qui peut utiliser le code. Omettez-le pour tout le monde. - `first_time_transaction` (boolean): Mettez true pour que seul un client qui n'a jamais payé cette application puisse utiliser le code. - `metadata` (object): Vos 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`. **POST /v1/apps/{appID}/promotion-codes** 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 }' ``` 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, }), }); 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, }, ) 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, ]), 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, }) 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) ``` **Réponse** ```json { "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** - `code` (string): Seulement le code avec ce texte. La casse n'a pas d'importance. - `coupon` (string): Seulement les codes de ce coupon. - `limit` (integer): Combien de codes promotionnels 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`. 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. **GET /v1/apps/{appID}/promotion-codes** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY", 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/promotion-codes?code=BLACKFRIDAY", 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": "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`. **GET /v1/apps/{appID}/promotion-codes/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", { headers: { Authorization: "Bearer sk_test_..." }, }); const code = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", headers={"Authorization": "Bearer sk_test_..."}, ) code = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $code = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", 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 code map[string]any json.NewDecoder(res.Body).Decode(&code) ``` **Réponse** ```json { "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** - `active` (boolean): Si 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. - `metadata` (object): Vos 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`. **PATCH /v1/apps/{appID}/promotion-codes/{id}** cURL : ```bash 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 }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ active: false, }), }); const code = await response.json(); ``` Python : ```python import requests response = requests.patch( "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", headers={"Authorization": "Bearer sk_test_..."}, json={ "active": False, }, ) code = response.json() ``` PHP : ```php "PATCH", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "active" => false, ]), CURLOPT_RETURNTRANSFER => true, ]); $code = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "active": false, }) req, _ := http.NewRequest("PATCH", "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs", 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) ``` **Réponse** ```json { "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 } } ```