API reference
Coupons
Create the discounts customers get with a promotion code, and keep them for one payment, some months, or every payment.
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. You can also apply a coupon yourself when you create a checkout session or a subscription. To run a sale from start to finish, see Run a sale with promotion codes.
The coupon object
Attributes
idstringUnique identifier for the coupon.app_idstringThe app the coupon belongs to.namestringnullableA name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon.percent_offintegernullableThe percentage taken off, from 1 to 99. Null when the coupon takes off a fixed amount.amount_offintegernullableThe fixed amount taken off, in the currency's smallest unit. Null when the coupon takes off a percentage.currencystringnullableXAF,XOForUSD. Set withamount_off, and null withpercent_off.durationstringonce: the first charged period.repeating: the periods induration_in_months.forever: every period. See How long a discount lasts.duration_in_monthsintegernullableHow many months arepeatingcoupon lasts, counted from the subscription's start. Null foronceandforever.max_redemptionsintegernullableThe most subscriptions that can use the coupon. Null for no limit.redeem_bytimestampnullableThe last moment the coupon can be used, in Unix seconds. Null for no end.times_redeemedintegerHow many subscriptions have used it, through any of its codes or a discount you set.metadataobjectYour own keys and values.{}when there are none.created_attimestampWhen the coupon was created, in Unix seconds.applies_toobjectnullableThe products the coupon is for, as{ "products": [...] }. Null when it applies to every product.validbooleanWhether a new subscription can use the coupon now: it isn't deleted, its redeem_by hasn't passed, and it is under max_redemptions.
{
"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
Accepts an Idempotency-Key header.
Creates a coupon. Send percent_off or amount_off, not both, and a duration.
Parameters
namestringA name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon.percent_offintegerThe percentage to take off, from 1 to 99. Rounded down to the currency's smallest unit.amount_offintegerThe fixed amount to take off, in the currency's smallest unit, like 1000 for FCFA 1,000. Send currency with it.currencystringXAF,XOForUSD. Required withamount_off, and not allowed withpercent_off.durationstringrequiredonce,repeatingorforever.duration_in_monthsintegerRequired withrepeating: how many months the discount lasts, from 1 up. Not allowed with the other durations.max_redemptionsintegerThe most subscriptions that can use the coupon, at least 1. Omit it for no limit.redeem_bytimestampThe last moment the coupon can be used, in Unix seconds. It must be in the future.applies_toobjectThe products the coupon is for. Omit it to cover every product.Show child parametersHide child parameters
productsarrayProduct IDs, up to 100. An empty list covers every product.
metadataobjectYour 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.
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"
}'{
"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
limitintegerHow many coupons to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Returns items and next_cursor, as described in Lists and filters. A value that isn't allowed, like a limit above 100, returns 422 with code invalid and the parameter's name in errors.
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
-H "Authorization: Bearer sk_test_..."{
"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.
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
-H "Authorization: Bearer sk_test_..."{
"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
namestringThe new name, up to 100 characters. Sendnullto remove it.metadataobjectYour 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.
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"
}'{
"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.
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
-H "Authorization: Bearer sk_test_..."{
"id": "Kf4Wn7Qa",
"deleted": true,
"deleted_at": 1727686400
}Next steps
- Promotion codesGive a coupon codes customers type at checkout, each with its own end date, limit and first-time rule.
- Run a sale with promotion codesCreate a coupon and a code, let customers apply it at checkout, and know what they pay and how long it lasts.
- 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.