# Coupons > Create the discounts customers get with a promotion code, and keep them for one payment, some months, or every payment. Source: https://abuna.app/docs/api/coupons A coupon is a discount: a percentage off or a fixed amount, for one payment, a number of months, or every payment. Customers use it through a [promotion code](https://abuna.app/docs/api/promotion-codes.md). You can also apply a coupon yourself when you [create a checkout session](https://abuna.app/docs/api/sessions.md#create-checkout) or [a subscription](https://abuna.app/docs/api/subscriptions.md#create). To run a sale from start to finish, see [Run a sale with promotion codes](https://abuna.app/docs/guides/promotion-codes.md). ## The coupon object **Attributes** - `id` (string): Unique identifier for the coupon. - `app_id` (string): The app the coupon belongs to. - `name` (string, nullable): A name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon. - `percent_off` (integer, nullable): The percentage taken off, from 1 to 99. Null when the coupon takes off a fixed amount. - `amount_off` (integer, nullable): The fixed amount taken off, in the currency's smallest unit. Null when the coupon takes off a percentage. - `currency` (string, nullable): `XAF`, `XOF` or `USD`. Set with `amount_off`, and null with `percent_off`. - `duration` (string): `once`: the first charged period. `repeating`: the periods in `duration_in_months`. `forever`: every period. See [How long a discount lasts](https://abuna.app/docs/guides/promotion-codes.md#duration). - `duration_in_months` (integer, nullable): How many months a `repeating` coupon lasts, counted from the subscription's start. Null for `once` and `forever`. - `max_redemptions` (integer, nullable): The most subscriptions that can use the coupon. Null for no limit. - `redeem_by` (timestamp, nullable): The last moment the coupon can be used, in Unix seconds. Null for no end. - `times_redeemed` (integer): How many subscriptions have used it, through any of its codes or a discount you set. - `metadata` (object): Your own keys and values. `{}` when there are none. - `created_at` (timestamp): When the coupon was created, in Unix seconds. - `applies_to` (object, nullable): The products the coupon is for, as `{ "products": [...] }`. Null when it applies to every product. - `valid` (boolean): Whether a new subscription can use the coupon now: it isn't deleted, its redeem_by hasn't passed, and it is under max_redemptions. **The coupon object** ```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 } ``` ## Create a coupon `POST /v1/apps/{appID}/coupons` Creates a coupon. Send `percent_off` or `amount_off`, not both, and a `duration`. **Parameters** - `name` (string): A name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon. - `percent_off` (integer): The percentage to take off, from 1 to 99. Rounded down to the currency's smallest unit. - `amount_off` (integer): The fixed amount to take off, in the currency's smallest unit, like 1000 for FCFA 1,000. Send currency with it. - `currency` (string): `XAF`, `XOF` or `USD`. Required with `amount_off`, and not allowed with `percent_off`. - `duration` (string, required): `once`, `repeating` or `forever`. - `duration_in_months` (integer): Required with `repeating`: how many months the discount lasts, from 1 up. Not allowed with the other durations. - `max_redemptions` (integer): The most subscriptions that can use the coupon, at least 1. Omit it for no limit. - `redeem_by` (timestamp): The last moment the coupon can be used, in Unix seconds. It must be in the future. - `applies_to` (object): The products the coupon is for. Omit it to cover every product. - `products` (array): Product IDs, up to 100. An empty list covers every product. - `metadata` (object): Your own keys and values. Returns the coupon with status `201`. A missing or wrong field returns `422` with code `invalid` and an `errors` item for it. A product ID that isn't in the app returns `422` with an `errors` item for `applies_to.products` and 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) ``` **Response** ```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 } ``` ## List coupons `GET /v1/apps/{appID}/coupons` Lists the app's coupons, newest first, one page at a time. Deleted coupons aren't listed. **Query parameters** - `limit` (integer): How many coupons to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. Returns `items` and `next_cursor`, as described in [Lists and filters](https://abuna.app/docs/lists-and-filters.md#pages). A value that isn't allowed, like a `limit` above 100, returns `422` with code `invalid` and the parameter's name in `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) ``` **Response** ```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 } ``` ## Retrieve a coupon `GET /v1/apps/{appID}/coupons/{id}` Returns the coupon. A deleted coupon is not found. If the app has no coupon with that ID, returns `404` with 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) ``` **Response** ```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 } ``` ## Update a coupon `PATCH /v1/apps/{appID}/coupons/{id}` Changes the coupon's name, its metadata, or both. The discount stays as you created it: to change the percentage, the amount, or the duration, create another coupon. Send at least one field. **Parameters** - `name` (string): The new name, up to 100 characters. Send `null` to remove it. - `metadata` (object): Your own keys and values. It replaces the metadata you set before. Returns the coupon. A body with neither field returns `422` with code `invalid` and an `errors` item for `name`. Any other field returns `400` with code `invalid_json` and an `errors` item with code `unknown_field`. If the app has no coupon with that ID, returns `404` with 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) ``` **Response** ```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 } ``` ## Delete a coupon `DELETE /v1/apps/{appID}/coupons/{id}` Deletes the coupon. No new subscription can use it or its promotion codes. A subscription that already holds it keeps its discount, and new invoices for that subscription still show it. You can't undo it. Returns the coupon's ID, `deleted: true`, and when it was deleted. If the app has no coupon with that ID, or the coupon is already deleted, returns `404` with 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) ``` **Response** ```json { "id": "Kf4Wn7Qa", "deleted": true, "deleted_at": 1727686400 } ```