API reference
Subscriptions
Start, list, read, update, cancel, keep and change the plan of a customer's subscription.
Use subscriptions to bill a customer for a price, one billing period at a time. A subscription starts trialing during a free trial, or pending without one, becomes active when the customer pays the first period, is unpaid (past_due) while a renewal waits for payment, and ends canceled. See Statuses.
The subscription object
Attributes
idstringUnique identifier for the subscription.app_idstringThe app the subscription belongs to.customer_idstringThe customer who pays.price_idstringThe price the customer pays.statusstringtrialingduring a free trial. Without a trial,pendinguntil the first period is paid, thenactive.past_duewhen a paid period has ended and its renewal isn't paid yet, thenactiveagain once it is.canceledonce it ends. See Statuses.starts_attimestampWhen the subscription starts, including its free trial if any, in Unix seconds.activated_attimestampnullableWhen the trial started, or the first period was paid without a trial.trial_ends_attimestampnullableWhen the free trial ends, in Unix seconds. Null for a subscription without a trial.canceled_attimestampnullableWhen the subscription was canceled.cancel_attimestampnullableWhen the subscription will end, if a cancel is scheduled for the end of the paid period or trial. Null otherwise. It staysactiveortrialinguntil then.cancel_at_period_endbooleantruewhile a cancel is scheduled for the end of the paid period or trial, socancel_atis set.falseotherwise, including once the subscription has ended.current_period_starttimestampnullableWhen the newest paid period or free trial started, in Unix seconds. An early-paid renewal can start in the future. Null until the first payment or trial. It stays set after the subscription ends.current_period_endtimestampnullableWhen the newest paid period or free trial ends, in Unix seconds. Null until the first payment or trial. It stays set after the subscription ends.ended_reasonstringnullableWhy the subscription ended.canceledwhen you or the customer canceled it, now or at the end of the paid period.unpaidwhen a billing period wasn't paid by its pay-by date, including a first period never paid. Null unlessstatusiscanceled.metadataobjectYour own keys and values.{}when there are none. A subscription started by a checkout session gets the session's. See Metadata.created_attimestampWhen the subscription was created, in Unix seconds.manage_tokenstringThe token in the customer portal link. Anyone with the link can see and cancel the subscription, so keep it private.discountobjectnullableThe coupon the subscription holds. Null without one. See Run a sale with promotion codes.Show child attributesHide child attributes
couponobjectThe coupon.promotion_codestringnullableThe ID of the promotion code that brought the coupon. Null when you applied the coupon directly, without a code.starttimestampWhen the discount started, in Unix seconds.endtimestampnullableForrepeating, when the discount stops. Null foronceandforever.
{
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}Create a subscription
POST/v1/apps/{appID}/subscriptions
Accepts an Idempotency-Key header.
Without a trial, starts a pending subscription and its first billing period, which starts now. Abuna issues the period's invoice and sends the customer a message with its pay link. To have the customer sign up and pay on the checkout page instead, use Create a checkout session.
With an eligible trial, starts trialing instead, without an immediate charge. The first paid period starts at trial_ends_at. See Free trials for billing, eligibility and webhooks.
Parameters
customer_idstringrequiredThe customer to bill.price_idstringrequiredThe price to bill them.trial_daysintegerOverride the price's trial with 1 to 365 days. Send0to disable it. Omit it to use the price's default. Only one trial per customer, product and app; a used trial falls back to normal billing without an error.discountsarrayA discount for this subscription: one entry withcouponorpromotion_code, by ID, not both. A discount that can't be used returns422with codecoupon_invalidfordiscounts. See Run a sale with promotion codes.metadataobjectYour own keys and values. See Metadata for the limits.
Returns an object with the subscription and its first period (free trial or billed), period, with status 201. If the app has no customer or price with that ID, returns 404 with code not_found and an errors item for customer_id or price_id. If the price is archived, returns 410 with code price_archived. If a Live app can't take payments yet, returns 422 with code not_accepting_payments. If the customer would pass the Live subscriber limit of your team's plan, returns 403 with code plan_limit.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}'{
"subscription": {
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "pending",
"starts_at": 1727600000,
"activated_at": null,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": null,
"current_period_end": null,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
},
"period": {
"id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"price_id": "Zt6YbN3q",
"pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"starts_at": 1727600000,
"ends_at": 1730192000,
"period_index": 0,
"grace_period_ends_at": 1727686400,
"paid_at": null,
"paused_at": null,
"in_force": true,
"created_at": 1727600000
}
}List subscriptions
GET/v1/apps/{appID}/subscriptions
Lists the app's subscriptions, newest first, one page at a time. Each item has the subscription's fields, including cancel_at, current_period_start, current_period_end, ended_reason and metadata, without app_id and manage_token, plus three more.
Query parameters
statusstringReturns only subscriptions with this status:pending,trialing,active,past_dueorcanceled.customer_idstringReturns only this customer's subscriptions.emailstringReturns only subscriptions whose customer's email contains this text. Case doesn't matter.limitintegerHow many subscriptions to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Extra attributes
customerobjectWho pays.Show child attributesHide child attributes
namestringnullableThe customer's name.emailstringThe customer's email address.
priceobjectWhat they pay.Show child attributesHide child attributes
namestringThe price's name.amountintegerThe amount for each period, in the currency's smallest unit.currencystringXAF,XOForUSD.intervalstringday,week,monthoryear.interval_countintegerHow many intervals make up one period.
next_payment_attimestampnullableWhen the next payment is due. While the latest period is unpaid, it is that period's start, even if that is in the past. Once it is paid, it is the next period's start. Null once canceled, and null while a cancel is scheduled.
Returns items and next_cursor, as described in Lists and filters. An unknown status or a limit outside 1 to 100 returns 422 with code invalid.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"customer": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"price": {
"name": "Monthly",
"amount": 5000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"next_payment_at": 1730192000
}
],
"next_cursor": null
}Retrieve a subscription
GET/v1/apps/{appID}/subscriptions/{id}
Retrieves a subscription with its customer, price, billing periods and payments.
Response attributes
subscriptionobjectThe subscription object.subscription_page_urlstringThe customer portal link, where the customer sees and cancels the subscription.customerobjectThe customer object, plustelegram_connected.priceobjectThe price object.periodsarrayEvery billing period in force, oldest first. An upgrade's period waiting for payment, or one that lapsed, isn't listed. The waiting one shows inpending_change, and its invoice is still in the invoice list.Show child attributesHide child attributes
idstringThe billing period's ID.starts_attimestampWhen the period starts.ends_attimestampWhen the period ends.grace_period_ends_attimestampThe pay-by date.paid_attimestampnullableWhen the period was paid.pay_urlstringThe pay link for the period.invoiceobjectnullableThe period's invoice object.invoice_urlstringnullableA link to the invoice page. It expires after 7 days.
paymentsarrayEvery payment on the subscription, newest first.pending_changeobjectnullableThe plan change waiting to happen: an upgrade waiting for payment, or a downgrade, or an upgrade at the next renewal, scheduled for the end of the paid period. Null when there is none. A scheduled cancel shows incancel_atinstead.Show child attributesHide child attributes
idstringThe plan change.typestringupgradeordowngrade.priceobjectThe new price:id,name,amount,currency,intervalandinterval_count.requested_bystringcustomerwhen they chose it in the customer portal or at a checkout, ormerchantwhen they confirmed a change you sent them to.created_attimestampWhen the change was requested.amount_dueintegernullableWhat the customer pays to switch now. Null for a downgrade, and 0 for an upgrade at the next renewal.creditintegernullableThe unused time of the current period taken off the new price. Null for a downgrade, and 0 for an upgrade at the next renewal.expires_attimestampnullableIf the upgrade isn't paid by then, it lapses and the current plan carries on. Null for a scheduled change.pay_urlstringnullableThe pay link for the upgrade. Null for a scheduled change.effective_attimestampnullableWhen a scheduled change starts. Null for an upgrade waiting for payment.
plan_offerobjectnullableThe plan change waiting for the customer to confirm, or null. It is null once it is past itsexpires_at.Show child attributesHide child attributes
idstringThe offer.priceobjectThe price offered:id,name,amount,currency,intervalandinterval_count.statusstringAlwayspendinghere.urlstringThe page where the customer confirms the change.created_attimestampWhen the offer was made.expires_attimestampWhen the offer runs out if the customer hasn't confirmed it.sent_attimestampnullableWhen Abuna sent the customer the link, or null when it didn't send one.
plan_changesarrayEvery plan change on the subscription, newest first.Show child attributesHide child attributes
idstringThe plan change.directionstringupgradeordowngrade.statusstringawaiting_payment(an upgrade not paid yet),scheduled(a downgrade, or an upgrade at the next renewal, waiting for the period end),applied,lapsed(an upgrade not paid in time),undone(a scheduled change taken back),replaced(another change took its place) orcanceled(the subscription ended first).from_priceobjectThe price before, in the same shape as above.to_priceobjectThe new price.requested_bystringcustomerormerchant.amountintegernullableWhat the upgrade charges. Null for a downgrade.creditintegernullableThe unused time taken off the upgrade. Null for a downgrade.effective_attimestampnullableWhen it took effect, or for a downgrade, when it will. Null for an upgrade that hasn't taken effect.created_attimestampWhen it was requested.resolved_attimestampnullableWhen it left the pending state.
If the app has no subscription with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \
-H "Authorization: Bearer sk_test_..."{
"subscription": {
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
},
"subscription_page_url": "https://app.abuna.app/portal/8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"customer": {
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane@example.com",
"created_at": 1727600000,
"metadata": {},
"language": null,
"updates": {
"channel": null,
"email": { "status": "active" },
"telegram": { "status": "off", "connected_at": null, "connect_url": null },
"whatsapp": { "status": "off", "connected_at": null, "connect_url": null }
},
"telegram_connected": false
},
"price": {
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"created_at": 1727600000,
"archived_at": null
},
"periods": [
{
"id": "T6yVr3Dp",
"starts_at": 1727600000,
"ends_at": 1730192000,
"grace_period_ends_at": 1727686400,
"paid_at": 1727600100,
"pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"invoice": {
"id": "V2nC8xEi",
"app_id": "8ddhXCDW",
"period_id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"number": "MYST-000124",
"status": "paid",
"kind": "period",
"amount": 5000,
"credit": 0,
"currency": "XAF",
"item_label": "Monthly",
"buyer_name": "Jane Doe",
"buyer_email": "jane@example.com",
"seller_name": "My store",
"period_start": 1727600000,
"period_end": 1730192000,
"due_at": 1727686400,
"created_at": 1727600000,
"paid_at": 1727600100,
"voided_at": null,
"discount": 0,
"coupon_id": null,
"promotion_code_id": null
},
"invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d"
}
],
"payments": [
{
"id": "m7Yw4NcJ",
"app_id": "8ddhXCDW",
"period_id": "T6yVr3Dp",
"driver": "sandbox",
"provider": "test",
"provider_reference": "test_9f3b7d1a5c2e8f4b6d0a",
"amount": 5000,
"currency": "XAF",
"status": "succeeded",
"message": null,
"created_at": 1727600090,
"fee": 100,
"net": null,
"session_id": null,
"note": null,
"marked_by_user_id": null,
"marked_by_api_key_id": null,
"method_label": "Successful payment (test)"
}
],
"pending_change": {
"id": "H3nM8cGb",
"type": "downgrade",
"price": {
"id": "Kw3FgT7e",
"name": "Basic monthly",
"amount": 2000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"requested_by": "customer",
"created_at": 1728464000,
"amount_due": null,
"credit": null,
"expires_at": null,
"pay_url": null,
"effective_at": 1730192000
},
"plan_offer": null,
"plan_changes": [
{
"id": "H3nM8cGb",
"direction": "downgrade",
"status": "scheduled",
"from_price": {
"id": "Zt6YbN3q",
"name": "Monthly",
"amount": 5000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"to_price": {
"id": "Kw3FgT7e",
"name": "Basic monthly",
"amount": 2000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"requested_by": "customer",
"amount": null,
"credit": null,
"effective_at": 1730192000,
"created_at": 1728464000,
"resolved_at": null
}
]
}Update a subscription
PATCH/v1/apps/{appID}/subscriptions/{id}
Sets the subscription's metadata. The map you send replaces the whole map: keys you leave out are removed. Send {} to clear it.
Parameters
metadataobjectrequiredThe new metadata. See Metadata for the limits.
Returns the subscription. Metadata past its limits returns 422 with code invalid and an errors item for metadata. If the app has no subscription with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \
-X PATCH \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"metadata": {"user_id": "42"}}'{
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}Cancel a subscription
POST/v1/apps/{appID}/subscriptions/{id}/cancel
Accepts an Idempotency-Key header.
Ends the subscription, now or at the end of the paid period. Send at_period_end to choose. An empty body, or false, cancels now. To have the customer confirm the cancel themselves, use Create a cancel session.
During a trial, at_period_end: true sets cancel_at to trial_ends_at. The subscription stays trialing until then, with access and no invoice to pay. An immediate API cancel still ends it now.
Body parameters
at_period_endbooleanOptional,falseby default. Withtrue, the subscription staysactiveuntil the current paid period ends, and then ends by itself. A value that isn't a boolean returns400with codeinvalid_json.
Now. The subscription is canceled at once, with canceled_at set and cancel_at null. Abuna voids its open invoices, sends a subscription.canceled event with reason merchant, and tells the customer. Canceling now on a subscription with a scheduled cancel ends it now and clears the schedule. It also voids an upgrade waiting for payment and withdraws a pending plan change offer.
At the end of the paid period. The response has status active and cancel_at set to the end of the paid period. Abuna sends a subscription.updated event and tells the customer when it ends and how to keep it. Until then it issues no renewal and sends no renewal reminders, and next_payment_at in the list is null. When the date arrives, the subscription becomes canceled and Abuna sends subscription.canceled. Sending at_period_end again while a cancel is scheduled returns 200 and changes nothing: no new event and no new email. A scheduled cancel replaces a scheduled downgrade or an upgrade waiting for payment. See One change at a time.
Outside a trial, if the current period isn't paid yet, or has already ended, at_period_end: true cancels now instead. Check status in the response to see which happened. A renewal invoice sent before the end and not paid yet is voided, so the customer can't pay for a period after the end. If they already paid it, the subscription ends when that renewal ends.
Returns the subscription. If the app has no subscription with that ID, or it is already canceled, returns 404 with code not_found. If at_period_end would replace an upgrade whose payment is in progress, returns 409 with code payment_in_progress.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel \
-X POST \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"at_period_end": true}'{
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": 1730192000,
"cancel_at_period_end": true,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}Keep a subscription
POST/v1/apps/{appID}/subscriptions/{id}/resume
Accepts an Idempotency-Key header.
Undoes a scheduled cancel. Billing carries on as before: cancel_at is null again and the next renewal is issued on time. Abuna sends a subscription.updated event and tells the customer the subscription continues.
It also undoes a scheduled downgrade, or an upgrade at the next renewal, so the next period stays at the current price. Abuna sends subscription.updated with a downgrade_undone or upgrade_undone change, and no email.
If nothing is scheduled on an active subscription, returns 200 and changes nothing. If the subscription is already canceled, returns 409 with code subscription_canceled. If the app has no subscription with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}List plan options
GET/v1/apps/{appID}/subscriptions/{id}/plan-options
Lists the prices the subscription can move to, each quoted as of now. Amounts change as the period runs down, so quote again right before you show them. See Changing plan for how each number is worked out.
Each option
priceobjectThe price:id,name,amount,currency,intervalandinterval_count.directionstringupgradeordowngrade.amount_dueintegerFor an upgrade, what the customer pays now. It can be0. Always0for a downgrade.creditintegerFor an upgrade, the unused time of the current period taken off the new price. Always0for a downgrade.new_billing_datetimestampnullableFor an upgrade, when the new period would end if paid now. Null for a downgrade.effective_attimestampnullableFor a downgrade, when the new price starts: the end of the paid period. Null for an upgrade.
Returns { "data": [...] }. The list is empty when no other price is eligible or the subscription isn't active or past_due. If the app has no subscription with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options \
-H "Authorization: Bearer sk_test_..."{
"data": [
{
"price": {
"id": "Hc8LmV2s",
"name": "Pro monthly",
"amount": 10000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"direction": "upgrade",
"amount_due": 6666,
"credit": 3334,
"new_billing_date": 1731142400,
"effective_at": null
},
{
"price": {
"id": "Kw3FgT7e",
"name": "Basic monthly",
"amount": 2000,
"currency": "XAF",
"interval": "month",
"interval_count": 1
},
"direction": "downgrade",
"amount_due": 0,
"credit": 0,
"new_billing_date": null,
"effective_at": 1730192000
}
]
}Statuses
trialing: free access untiltrial_ends_at. Keep access during the trial. Customers in Live count toward your team's subscriber limit; Test has no subscriber limit.pending: created, and waiting for the first payment. If the first period isn't paid by its pay-by date, the subscription iscanceledwithended_reasonunpaid.active: every period that has started is paid.past_due: unpaid. A renewal has started and isn't paid yet.canceled: ended.ended_reasonsays why. A canceled subscription can't be restarted.
Renewals and unpaid subscriptions
Abuna issues the next billing period and its invoice before the paid period ends. Your app's renewal_lead_days sets how many days ahead: 0 to 7, 3 by default, and never earlier than half the period. Abuna sends subscription.renewed and invoice.created, and emails the customer the invoice with its pay link. The subscription stays active, and the customer can pay right away. The new period always starts when the paid one ends, even if the customer pays early.
If the renewal is still unpaid when the paid period ends, the subscription becomes past_due and Abuna sends subscription.past_due. When the invoice is paid, the subscription is active again, and Abuna sends subscription.recovered. A renewal paid before the paid period ends never goes through past_due. With renewal_lead_days at 0, or while a downgrade waits for the period's end, the invoice goes out as the period ends, so the subscription is past_due until the customer pays.
If the period isn't paid by its pay-by date, the subscription is canceled with ended_reason unpaid, and Abuna sends subscription.canceled with reason non_payment. The pay-by date is the billing period's grace_period_ends_at: the period's start plus your app's days to pay, grace_period_days (1 to 14, 3 by default), and never later than the period's end.
current_period_start and current_period_end keep showing the last paid period while the subscription is past_due. A past_due subscription can still:
- Be paid through its pay link, a payment session or the customer portal.
- Be canceled. A cancel at the end of the paid period ends it now, because the current period isn't paid.
- Changing plan. An upgrade starts a full period at the new price now, and a downgrade waits for the current period's end. See Upgrades.
Payments that arrive late
A mobile money payment the customer approved can be confirmed hours later. If the invoice was voided in the meantime, Abuna still records the payment: it is succeeded, the invoice becomes paid, Abuna sends invoice.paid, and the customer gets a receipt.
- If the subscription ended only because this payment hadn't arrived (
ended_reasonunpaid), and the period it pays for hasn't ended yet, the subscription comes back:statusisactive,canceled_atandended_reasonare null again, and Abuna sendssubscription.recovered, orsubscription.paidfor a first payment. A first payment needs room in the Live subscriber limit of your team's plan, as at checkout. - Otherwise the subscription stays as it is: canceled by you or the customer, replaced, past the paid period, or an upgrade that expired. You may want to refund the customer.
Either way, team members who get emails about payments or cancellations get one about it.
Metadata
metadata holds your own keys and values on a subscription, for example your user ID. Set it when you create the subscription, pass it to a checkout session, or update it later. Every read returns it.
- Up to 20 keys.
- Each key is 1 to 40 characters.
- Each value is a string of up to 500 characters. Numbers, booleans, objects and null aren't allowed.
The subscription, invoice and plan_offer events carry this subscription's metadata. Session events carry the session's own metadata instead. Pass metadata on every session you create. See Event types.
Canceling a subscription
During a free trial, a customer's cancel is scheduled for trial_ends_at, with access until then. Any unpaid first invoice is canceled, so nothing remains to pay. The API can still cancel immediately.
A cancel can take effect now or at the end of the paid period. You choose when you cancel from the dashboard or the API. For customers who cancel in the customer portal, the app's When customers cancel setting decides, which is customer_cancel. New apps start with at_period_end. A cancel session uses that setting too, unless you send at_period_end.
- Now. The subscription ends at once and any unpaid invoice is voided.
- End of the paid period. The subscription stays
activeand carriescancel_at. The customer keeps access they paid for. Abuna issues no renewal and sends no renewal reminders, and voids a renewal invoice it already sent and that isn't paid. A renewal the customer already paid counts as paid period, so the subscription ends when it ends. The dashboard and the customer portal show "Ends on" with the date. At that moment the subscription becomescanceled. - Unpaid period. If the current period isn't paid yet, an end-of-period cancel ends the subscription now and voids the unpaid invoice. The dashboard and the customer portal say so before the person confirms.
- Undo. Until the end date, you can keep the subscription in the dashboard or with the resume endpoint, and the customer can keep it in the portal. Billing carries on as before.
The customer gets one email when a cancel is scheduled, with the end date and how to keep the subscription, one when it ends, and one short confirmation if it is undone. Your webhook URL gets subscription.updated when a cancel is scheduled or undone, and subscription.canceled when the subscription ends. See Customer notifications.
Test mode works the same way. Abuna records the emails for a Test customer instead of sending them, and Test and Live apps keep their own When customers cancel setting.
Changing plan
An active or past_due subscription can move to another price. The customer does it in the customer portal, or confirms a change you send them to with a plan change session. A customer who comes back to a checkout for another price of the same product is offered the change there too: see Switching plan at checkout. You can't change the price directly, because an upgrade needs the customer to pay.
Which prices
Any other price of the same product in the same currency, unless it is archived. Never a price of another product or in another currency: a change to a price in another currency returns 422 with code price_not_eligible. If no price is eligible, the portal shows no option to change plan. A subscription that is still pending can't change plan.
Upgrade or downgrade
Abuna compares cost per day: the price's amount divided by the length in days of one of its periods starting now. A price that costs more per day is an upgrade. One that costs the same or less is a downgrade. This works across intervals, so moving from monthly to yearly follows the same rule.
Upgrades
If the current period is paid, the customer pays the difference now and keeps the old plan until that payment succeeds. A renewal invoice already sent for the old price and not paid is voided, and the next one is issued at the new price. If the customer already paid the next period before it started, an upgrade waits until that period starts: until then the portal offers no upgrade, and a change returns 409 with code renewal_paid_early. At that moment the new plan starts with a fresh full period at the new price, and the billing date moves to the payment date.
The amount is the new price minus the unused value of the current period. The unused value is the period's value times the whole days left, divided by the days in the period. The period's value is what its invoice charged plus any credit on it, so a second upgrade in the same period loses nothing. The result is rounded down and never goes below 0. With 20 of 30 days left on a FCFA 5,000 period, moving to a FCFA 10,000 price costs 10000 − 3334 = 6666, and credit is 3334. An amount above 0 but under the minimum charge, FCFA 100 or 50 US cents, is raised to it, and credit is lower by the same amount. With a discount that covers the new price, the new price is the discounted one.
- Nothing to pay. When the amount is
0, the upgrade takes effect at once. Its invoice is created already paid. - Not paid in time. The upgrade lapses at its
expires_at: your app's days to pay from the request, or the end of the current period if that comes first. Its invoice is voided and the old plan carries on. There is no penalty. If the upgrade replaced a scheduled cancel, the cancel is scheduled again for its original date, andsubscription.updatedcarries itscancel_at. - Unpaid current period. If the current period isn't paid yet, as while the subscription is
past_due, Abuna voids its invoice and starts a full period at the new price now. The new plan is in force at once and the customer pays it through its pay link, with the usual days to pay. There is no credit. While a payment on the old invoice is in progress, the change returns409with codepayment_in_progress.
A switch at a checkout session created with upgrade_timing next_renewal is the exception: the upgrade costs nothing now and is scheduled for the end of the paid period, like a downgrade. It shows in pending_change and scheduled_price_change, sends subscription.updated with an upgrade_scheduled change, and can be undone the same way.
An upgrade's invoice has kind plan_change and the unused time in credit. Its amount is what the customer pays.
An upgrade with something to pay needs your app to take payments. Until it can, the change returns 422 with code not_accepting_payments. An upgrade with nothing to pay, and a downgrade, work either way.
Downgrades
A downgrade costs nothing now and refunds nothing. The customer keeps the current plan until the paid period ends, and the next period is issued at the new price when the paid period ends, not before. A renewal invoice already sent for the old price and not paid is voided. If the customer already paid the next period, the downgrade starts when that period ends. Until then, the customer can undo it in the customer portal, and you can with Keep a subscription. A scheduled downgrade shows in pending_change and in scheduled_price_change on subscription.updated.
A downgrade can be scheduled while the current period is still unpaid. It still starts at that period's end, and if the period stays unpaid, the subscription ends for non-payment as usual. While a downgrade is scheduled, the renewal reminder quotes the new price.
One change at a time
A subscription holds at most one of these: a scheduled cancel, a scheduled downgrade or upgrade, or an upgrade waiting for payment. Starting one replaces the other. A replaced upgrade has its invoice voided, and the replaced change gets status replaced. While that upgrade's payment is in progress, it can't be replaced: the request returns 409 with code payment_in_progress.
Asking again for the change already waiting, to the same price, changes nothing and returns it as it stands.
A change you send the customer with a plan change session waits for them to confirm it. A subscription has at most one change waiting to be confirmed. A new one, or a plan change the customer makes in the portal, replaces it. Confirming it replaces a scheduled cancel, a scheduled downgrade or an upgrade waiting for payment, and the confirm page says so first. Canceling the subscription now voids an upgrade waiting for payment and withdraws the change waiting to be confirmed.
In the customer portal
The customer portal lists each eligible price with what it costs now: the amount to pay and the new billing date for an upgrade, or the date it starts for a downgrade. An upgrade sends the customer to its pay link, unless there is nothing to pay. While an upgrade waits for payment, the portal shows it with its pay link. Keeping the subscription in the portal also undoes a scheduled downgrade. To send a customer to the portal with a link back to your app, use Create a portal session.
The confirm page
The url of a plan change session opens a page with the current plan, the new one and what the change costs, worked out when the page loads. The customer confirms there, and the change follows the same rules as in the portal. The page stops working when the session expires (7 days, or the end of the current period if that comes first), when a newer change replaces it, or once it is used.
Abuna doesn't email the customer when you create a plan change session, so send them to its url yourself. The customer gets an email when an upgrade takes effect and when a downgrade is scheduled. Nothing is sent when an upgrade starts waiting for payment, when it lapses, or when a downgrade is undone. See Customer notifications. In Test mode, Abuna records these emails instead of sending them.