API reference
Promotion codes
Give a coupon codes customers type at checkout, each with its own end date, limit and first-time rule.
A promotion code is the word a customer types to get a coupon, 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
idstringUnique identifier for the code. Customers type the code, not this ID.app_idstringThe app the code belongs to.codestringThe text customers type at checkout, like BLACKFRIDAY.activebooleanWhether customers can use the code. A code you turn off keeps its uses and its coupon.expires_attimestampnullableThe last moment the code can be used, in Unix seconds. Null for no end.max_redemptionsintegernullableThe most subscriptions that can use the code. Null for no limit.times_redeemedintegerHow many subscriptions have used the code. It can passmax_redemptions; see List promotion codes.metadataobjectYour own keys and values.{}when there are none.created_attimestampWhen the code was created, in Unix seconds.couponobjectThe coupon the code gives.restrictionsobjectWho can use the code.Show child attributesHide child attributes
first_time_transactionbooleanWhen true, only a customer of this app who has never paid an invoice can use it. The check uses the customer's email address.
{
"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
Accepts an Idempotency-Key header.
Creates a code for one of the app's coupons.
Parameters
couponstringrequiredThe ID of the coupon the code gives. The coupon must not be deleted, past its redeem_by, or out of uses.codestringThe 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.activebooleanWhether customers can use it right away. Defaults totrue.expires_attimestampThe last moment the code can be used, in Unix seconds. It must be in the future.max_redemptionsintegerThe most subscriptions that can use the code, at least 1. Omit it for no limit.restrictionsobjectWho can use the code. Omit it for everyone.Show child parametersHide child parameters
first_time_transactionbooleanSet it to true so only a customer who never paid this app can use the code.
metadataobjectYour 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.
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
}'{
"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
codestringOnly the code with this text. Case doesn't matter.couponstringOnly this coupon's codes.limitintegerHow many promotion codes 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.
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.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY" \
-H "Authorization: Bearer sk_test_..."{
"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.
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
-H "Authorization: Bearer sk_test_..."{
"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
activebooleanWhether customers can use the code. Send false to stop new uses. Subscriptions that already used it keep their discount.metadataobjectYour 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.
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
}'{
"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
}
}Next steps
- CouponsCreate the discounts customers get with a promotion code, and keep them for one payment, some months, or every payment.
- 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.