# Run a sale with promotion codes > Create a coupon and a code, let customers apply it at checkout, and know what they pay and how long it lasts. Source: https://abuna.app/docs/guides/promotion-codes Run a sale without changing your prices: create a coupon, give it a code like `BLACKFRIDAY`, and let customers apply it at checkout. A customer pays less from the first payment, and renewals follow the coupon's duration. ## Create a coupon A coupon holds the discount. Send a percentage, or a fixed amount with its currency, and how long it lasts. **Create a 25% coupon for one payment** 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) ``` Add `applies_to.products` to limit it to some products. Without it, the coupon covers every product. Add `max_redemptions` to cap the number of subscriptions, and `redeem_by` to stop it at a date. See [Create a coupon](https://abuna.app/docs/api/coupons.md#create). ## Add a promotion code Give the coupon one or more codes. Customers type a code at checkout to get the coupon. **Give the coupon a BLACKFRIDAY code** 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) ``` Codes ignore case, so `blackfriday` works too. Omit `code` and Abuna makes one of 8 characters, such as `K7M2QX9P`. A code works only while both the code and its coupon allow it. Set `restrictions.first_time_transaction` to `true` to keep it for customers who never paid this app. See [Create a promotion code](https://abuna.app/docs/api/promotion-codes.md#create). ## Let customers type the code Customers can type a code on a [checkout session](https://abuna.app/docs/api/sessions.md#create-checkout) and on a [checkout link](https://abuna.app/docs/quickstart.md#use-a-checkout-link). You don't need to send anything. The page shows **Add promotion code** under the summary while your app has at least 1 code a customer can use on that price: turned on, not expired, not used up, and for that product and currency. When no code can be used, the field stays hidden, so customers don't look for a code that doesn't exist. The page never lists your codes. The customer types the code and presses **Apply**. The page then shows a **Discount** line with the code, the amount off, the subtotal and the new total. The **×** beside the code removes it. When a code can't be used, the page shows the reason beside the field, and the customer can pay without it. The page says why in plain words: the code doesn't work, doesn't apply to this plan, takes too much off this price, or is for first-time customers only. A first-time-only code is checked when the customer submits the checkout, or when they apply it if you sent their email on the session. If a code stops working before they pay, the page marks it as no longer applying and shows the full total; the customer removes it to continue. ### Hide the code field To keep codes off a checkout session, send `allow_promotion_codes: false`. To show the field even when no code can be used yet, send `true`. A session with `discounts` has no code field. A checkout link shows the field whenever a code can be used on its price. **Create a checkout without the code field** 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) ``` > **Note:** Don't send `allow_promotion_codes: true` with `discounts`. A session that takes both returns `422` with an `errors` item for `discounts`. ### Pre-apply a discount To give the discount without asking for a code, send `discounts` on the checkout. It takes one entry, with `coupon` or `promotion_code`, by ID. You can do the same when you [create a subscription](https://abuna.app/docs/api/subscriptions.md#create). **Create a checkout with the discount already applied** 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) ``` The customer sees the discount line with the code, or the coupon's name when you sent a coupon, and its terms. There is no code field, and they can't remove it. If the discount no longer fits the price when they submit, the checkout refuses it; with a code, the customer can remove it and continue. ## What the customer pays A percentage is rounded down to the currency's smallest unit. A fixed amount comes off as it is, in its own currency. A charge never goes below **FCFA 100** for `XAF` and `XOF`, or **50 US cents** for `USD`. If the discount would go lower, the checkout refuses the code. At renewals the discount shrinks instead, so the charge stays at that floor. The customer sees it on the pay page and the invoice, as a discount line. ## How long a discount lasts - `once`: the first charged period only. If the subscription starts with a free trial, that is the first paid period after it. - `repeating`: every period that starts within `duration_in_months` of the subscription's start. A 3-month coupon covers 3 monthly periods. - `forever`: every period for as long as the subscription runs. The months of a `repeating` coupon count from the subscription's start, not from the first payment. A free trial longer than the coupon can use the discount up before the customer pays anything. ## When a code stops working A customer can't use a code that is turned off, has passed its `expires_at`, or whose coupon is deleted, past its `redeem_by`, or out of uses. A coupon for other products, a fixed amount in another currency, or a discount below the floor is refused too. `max_redemptions` is checked when a customer uses the code. If several customers are already checking out when the last place fills, they all get the discount, so `times_redeemed` can pass the cap. Customers who start after that are refused. A use counts when the trial starts or the first payment goes through. ## Plan changes A subscription keeps its discount when it changes plan only if the coupon covers the new product: the coupon lists no products, or lists the product of the new price. A fixed amount also needs the new price in the coupon's currency. Otherwise the discount ends with the change. A `repeating` coupon keeps its original end date, so a plan change never makes it last longer. A `once` coupon that already took its payment doesn't come back. ## What you get back A subscription with a discount has a `discount` object. It holds the coupon, the ID of the code that brought it, and when the discount starts and ends. `end` is set for `repeating` and null for `once` and `forever`. **The discount on a subscription** ```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 } ``` An invoice's `amount` is already after its discount. `discount` says what was taken off, and `coupon_id` and `promotion_code_id` name the source. The invoice page and the [`invoice.created`](https://abuna.app/docs/api/events.md#invoice-created) and [`invoice.paid`](https://abuna.app/docs/api/events.md#invoice-paid) webhooks carry the same fields. The pay page shows the discount too.