# Promotion codes > Give a coupon codes customers type at checkout, each with its own end date, limit and first-time rule. Source: https://abuna.app/docs/api/promotion-codes A promotion code is the word a customer types to get a [coupon](https://abuna.app/docs/api/coupons.md), like `BLACKFRIDAY`. One coupon can have many codes, each active or not, with its own end date and limit. Codes ignore case, so `blackfriday` works too. ## The promotion code object **Attributes** - `id` (string): Unique identifier for the code. Customers type the code, not this ID. - `app_id` (string): The app the code belongs to. - `code` (string): The text customers type at checkout, like BLACKFRIDAY. - `active` (boolean): Whether customers can use the code. A code you turn off keeps its uses and its coupon. - `expires_at` (timestamp, nullable): The last moment the code can be used, in Unix seconds. Null for no end. - `max_redemptions` (integer, nullable): The most subscriptions that can use the code. Null for no limit. - `times_redeemed` (integer): How many subscriptions have used the code. It can pass `max_redemptions`; see [List promotion codes](https://abuna.app/docs/api/promotion-codes.md#list). - `metadata` (object): Your own keys and values. `{}` when there are none. - `created_at` (timestamp): When the code was created, in Unix seconds. - `coupon` (object): The [coupon](https://abuna.app/docs/api/coupons.md#object) the code gives. - `restrictions` (object): Who can use the code. - `first_time_transaction` (boolean): When true, only a customer of this app who has never paid an invoice can use it. The check uses the customer's email address. **The promotion code object** ```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 } } ``` ## Create a promotion code `POST /v1/apps/{appID}/promotion-codes` Creates a code for one of the app's coupons. **Parameters** - `coupon` (string, required): The ID of the coupon the code gives. The coupon must not be deleted, past its redeem_by, or out of uses. - `code` (string): The text customers type. Use 1 to 50 letters, digits, hyphens, or underscores. Codes ignore case and must be unique in the app. Omit it and Abuna makes a code of 8 characters you can read out. - `active` (boolean): Whether customers can use it right away. Defaults to `true`. - `expires_at` (timestamp): The last moment the code can be used, in Unix seconds. It must be in the future. - `max_redemptions` (integer): The most subscriptions that can use the code, at least 1. Omit it for no limit. - `restrictions` (object): Who can use the code. Omit it for everyone. - `first_time_transaction` (boolean): Set it to true so only a customer who never paid this app can use the code. - `metadata` (object): Your own keys and values. Returns the code with its coupon and status `201`. A missing or wrong field returns `422` with code `invalid` and an `errors` item for it. A coupon ID that isn't in the app returns `422` with code `not_found` for `coupon`. A coupon that can't be used returns `422` with code `invalid` for `coupon`. A code another promotion code in the app already has returns `409` with code `code_taken` for `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) ``` **Response** ```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 } } ``` ## List promotion codes `GET /v1/apps/{appID}/promotion-codes` Lists the app's promotion codes, newest first, one page at a time. Each item carries its coupon. **Query parameters** - `code` (string): Only the code with this text. Case doesn't matter. - `coupon` (string): Only this coupon's codes. - `limit` (integer): How many promotion codes 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`. A code can be used by more subscriptions than its `max_redemptions` if customers were already paying when the last place filled. `times_redeemed` shows the real count. **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) ``` **Response** ```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 } ``` ## Retrieve a promotion code `GET /v1/apps/{appID}/promotion-codes/{id}` Returns the code and its coupon. If the app has no code with that ID, returns `404` with 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) ``` **Response** ```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 } } ``` ## Update a promotion code `PATCH /v1/apps/{appID}/promotion-codes/{id}` Turns the code on or off, changes its metadata, or both. The code, its coupon, its end date and its limits stay as you created them. Send at least one field. **Parameters** - `active` (boolean): Whether customers can use the code. Send false to stop new uses. Subscriptions that already used it keep their discount. - `metadata` (object): Your own keys and values. It replaces the metadata you set before. Returns the code. A body with neither field returns `422` with code `invalid` and an `errors` item for `active`. Any other field returns `400` with code `invalid_json` and an `errors` item with code `unknown_field`. If the app has no code with that ID, returns `404` with 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) ``` **Response** ```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 } } ```