API reference
Prices
Set how much a product costs and how often it renews: every day, week, month or year.
Prices set how much a product costs and how often it renews: every day, week, month or year. A product can have several prices, for example a monthly and a yearly one.
The price object
Attributes
idstringUnique identifier for the price.product_idstringThe product the price belongs to.namestringThe price's name, for example Monthly.currencystringXAF,XOForUSD.amountintegerWhat the customer pays each billing period, in the currency's smallest unit: francs for XAF and XOF, cents for USD.intervalstringThe unit of a billing period:day,week,monthoryear.interval_countintegerHow many intervals make up one billing period.monthwith3bills every 3 months.created_attimestampWhen the price was created, in Unix seconds.trial_daysintegernullableDefault free trial length, from 1 to 365 days. Null means no trial. Set at creation and cannot be changed.archived_attimestampnullableWhen the price was archived. An archived price starts no new subscriptions.pending_changeobjectnullableThe amount change scheduled for the price, or null when none is. A price has at most one.Show child attributesHide child attributes
idstringUnique identifier for the change. Price change events carry it as price_change_id.amountintegerThe new amount, in the currency's smallest unit.previous_amountintegerThe amount before the change.currencystringThe price's currency.effective_attimestampMidnight at the start of the day the new amount applies from, in timezone.timezonestringYour app's time zone, for exampleAfrica/Douala, the same as the app'stimezone.effective_atis midnight there.keep_current_subscribersbooleantruewhen everyone subscribed on that day keeps the old amount.created_attimestampWhen the change was scheduled, in Unix seconds.
{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}Create a price
POST/v1/apps/{appID}/prices
Accepts an Idempotency-Key header.
Creates a price for one of the app's products.
Customers pay by mobile money in FCFA, whatever the price's currency. A USD price is charged at the day's exchange rate plus 2%, rounded up to a whole franc, and the 2% is part of what you receive. Between XOF and XAF the amount converts 1 to 1. The rate is saved on each payment. See Paying in FCFA.
Parameters
product_idstringrequiredThe product to price.namestringrequiredThe price's name, for example Monthly.currencystringrequiredXAF,XOForUSD. Lowercase works too.amountintegerrequiredWhat the customer pays each billing period, in the currency's smallest unit: francs for XAF and XOF, cents for USD, so1000is $10.00. Must be greater than 0.intervalstringrequiredday,week,monthoryear.trial_daysintegerOptional free trial length, from 1 to 365 days. Omit it or sendnullfor no trial. It cannot be changed later. See Free trials.interval_countintegerHow many intervals make up one billing period. Defaults to1. At most 365 days, 52 weeks, 12 months or 1 year.
Returns the price with status 201. An invalid field returns 422 with code invalid. If the app has no product with that product_id, returns 404 with code not_found and an errors item for product_id.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}'{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}List prices
GET/v1/apps/{appID}/prices
Lists the app's prices, across all products and including archived ones, newest first, one page at a time.
Query parameters
limitintegerHow many prices 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/prices \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}
],
"next_cursor": null
}Update a price
PATCH/v1/apps/{appID}/prices/{id}
Renames the price. Its amount, currency, billing period and checkout link stay the same. To change what customers pay, schedule a price change.
The trial length cannot change. Create a new price to set a different trial_days default.
Parameters
namestringrequiredThe new name, for example Monthly plan.
Returns the price. A blank name returns 422 with code invalid. If the app has no price with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q \
-X PATCH \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Monthly plan"}'{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly plan",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}Archive a price
POST/v1/apps/{appID}/prices/{id}/archive
Accepts an Idempotency-Key header.
Archives the price. It starts no new subscriptions, and subscriptions already on it keep renewing. Archiving an archived price changes nothing. To undo it, unarchive the price.
Returns the price. If the app has no price with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": 1727686400,
"pending_change": null
}Unarchive a price
POST/v1/apps/{appID}/prices/{id}/unarchive
Accepts an Idempotency-Key header.
Unarchives the price. It can start new subscriptions again, and its checkout link works again. Unarchiving a price that isn't archived changes nothing.
Returns the price. If the app has no price with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}Schedule a price change
POST/v1/apps/{appID}/prices/{id}/change
Accepts an Idempotency-Key header.
Schedules a new amount for the price, starting on a day at least 14 days ahead. The amount never changes right away. The currency and billing period can't change. For a different one, create a new price.
From the start of that day in your app's time zone, checkouts and new subscriptions pay the new amount. Each current subscriber pays it from their first renewal on or after that day. Abuna emails each of them now with the amount they will pay, after any discount they hold, and the date it first applies to them, and messages them on Telegram if they chose it. Customers who subscribe while the change is pending get the same message when they subscribe.
With keep_current_subscribers, everyone subscribed on that day keeps paying the old amount for as long as they stay subscribed, and only later subscribers pay the new one. A subscriber who moves to another price and back pays the price's amount at that time.
A price has one pending change. Scheduling another replaces it. If the replacement keeps current subscribers on the old amount, those told about the earlier change get an email saying their price stays. Abuna records a price_change.scheduled event, and price_change.applied when the new amount starts.
Parameters
amountintegerrequiredThe new amount, in the currency's smallest unit. Must be greater than 0 and different from the current amount.effective_attimestamprequiredAny time on the day the new amount starts, in Unix seconds. Abuna moves it to the start of that day in your app's time zone. The day must be at least 14 days after today there.keep_current_subscribersbooleanKeep everyone subscribed on that day on the old amount. Defaults tofalse.
Returns the price with pending_change set. A failed check returns 422 with code invalid, and each errors item names the field: amount with invalid or unchanged, or effective_at with required or too_soon. Any other field, such as currency or interval, returns 400 with code invalid_json. If the app has no price with that ID, returns 404 with code not_found. Once the pending change reaches its effective_at, it can't be replaced until it is applied, and the request returns 409 with code change_in_effect. See When the change takes effect.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change \
-X POST \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"amount": 6000, "effective_at": 1730458800, "keep_current_subscribers": false}'{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": {
"id": "W4hN7gPc",
"amount": 6000,
"previous_amount": 5000,
"currency": "XAF",
"effective_at": 1730415600,
"timezone": "Africa/Douala",
"keep_current_subscribers": false,
"created_at": 1727700000
}
}Cancel a price change
POST/v1/apps/{appID}/prices/{id}/change/cancel
Accepts an Idempotency-Key header.
Cancels the price's pending change, so the amount stays as it is. If current subscribers were going to move to the new amount, Abuna emails them that their price stays. Abuna records a price_change.canceled event.
Returns the price with pending_change set to null. If the app has no price with that ID, returns 404 with code not_found. With no pending change, returns 409 with code no_pending_change. Once the change reaches its effective_at, it can't be canceled, and the request returns 409 with code change_in_effect.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"trial_days": null,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}When the change takes effect
A change takes effect at its effective_at, and Abuna records price_change.applied within about a minute of that time. In between, pending_change still shows the change, and canceling or replacing it returns 409 with code change_in_effect. Once price_change.applied is recorded, pending_change is null and you can schedule a new change.