Guides
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.
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.
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"
}'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.
Add a promotion code
Give the coupon one or more codes. Customers type a code at checkout to get the coupon.
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
}'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.
Let customers type the code
Customers can type a code on a checkout session and on 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.
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}"
}'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.
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}"
}'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 withinduration_in_monthsof 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.
{
"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 and invoice.paid webhooks carry the same fields. The pay page shows the discount too.
Next steps
- CouponsCreate the discounts customers get with a promotion code, and keep them for one payment, some months, or every payment.
- Promotion codesGive a coupon codes customers type at checkout, each with its own end date, limit and first-time rule.
- SessionsSend a customer to a hosted page to subscribe, pay an invoice, change plan, cancel or open the customer portal. Then list, read and expire those sessions.
- SubscriptionsStart, list, read, update, cancel, keep and change the plan of a customer's subscription.