API reference
Sessions
Send 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.
Sessions let one customer subscribe, pay an invoice, change plan, cancel, or manage their subscription on a page Abuna hosts. You send the customer to the session's url. Abuna tells your server how it ended with a session.completed or session.expired event. The Sessions guide walks through the whole flow.
You create every session with POST /v1/apps/{appID}/sessions. The type in the body says what the customer does and which other fields the body takes:
checkout: a checkout page that sells one price. Sendprice_id.payment: a pay page for one open invoice. Sendinvoice_id.plan_change: the customer confirms a move to another price. Sendsubscription_idandprice_id.cancel: the customer confirms a cancel. Sendsubscription_id.portal: the customer portal with a link back to your app. Sendsubscription_idandreturn_url.
Every type returns the same session object. You list, retrieve, and expire sessions of every type with the same endpoints. A type Abuna doesn't know returns 422 with code invalid and an errors item for type.
These endpoints take a secret key only. A publishable key or a dashboard sign-in gets 403 with code forbidden. A body field the session's type doesn't take returns 400 with code invalid_json.
The session object
Attributes
idstringUnique identifier for the session.typestringWhat the session is for:checkout,payment,plan_change,cancel, orportal, as you sent it when you created the session.statusstringopenuntil it ends.completedonce the customer finishes, as each type defines it, orexpiredonce it runs out or you expire it. A session that ends never changes again.urlstringThe page to send the customer to. It belongs to this customer, so don't share it.success_urlstringnullableWhere the customer goes after finishing, as you sent it, or your app's Success URL if you sent none. Placeholders like{SESSION_ID}appear as written. Null when neither is set, and always null forportal. See Success URL placeholders.cancel_urlstringnullableWhere the customer goes if they leave before paying, or the session expires. Your app's Cancel URL if you sent none. Null when neither is set, and always null for portal.return_urlstringnullableForportal, where the portal's "Back to" link goes. Null for other types.metadataobjectYour own keys and values, as you sent them.{}when you sent none.customer_idstringnullableThe customer you passed, or the one the customer's details created. For the other types, the subscription's customer. Null until known.price_idstringnullableForcheckout, the price the session sells. Forplan_change, the new price. Null for the other types.subscription_idstringnullableForcheckout, the subscription the session started, set once the customer submits their details, or the customer's existing subscription when the checkout leads back to it (see Returning customers). For the other types, the subscription the session acts on. Null until known.invoice_idstringnullableForpayment, the invoice the customer pays. Null for other types.plan_offer_idstringnullableForplan_change, the plan offer the session created. Forcheckout, the plan offer made once the checkout offers a returning customer a switch, or null. Null for other types.at_period_endbooleannullableForcancel, whether the cancel waits for the end of the paid period (true) or ends the subscription right away (false). Set when the session is created, from your request or the app'scustomer_cancel. Null for other types.updates_channelstringnullableForcheckout, which chat app the checkout offers first for payment reminders once the customer pays, as it applies now:ask,telegram,whatsapp, oremail. A channel your app can't offer shows asask. See Create a checkout session. Null for other types.upgrade_timingstringnullableForcheckout, when a returning customer's switch to a higher price takes effect:nowornext_renewal, as you sent it ornowby default. Null for other types.expires_attimestampWhen the session runs out, in Unix seconds. 24 hours after creation forcheckout,payment, andcancel. 7 days, or the end of the current period if sooner, forplan_change. 1 hour forportal, which must be opened by then. Acheckoutsession that offered a switch takes the switch offer's end instead.trial_daysintegernullableForcheckout, your requested trial override: 1 to 365 days, or0to disable it. Null uses the price's default. Null for other session types. Eligibility is checked when the subscription starts.allow_promotion_codesbooleannullableForcheckout, the value you sent:truealways shows the promotion code field,falsehides it, and null shows it while a code can be used on the price.falsetoo when you sentdiscounts. Null for other types.discountobjectnullableForcheckout, the discount on the session:coupon, the coupon, andpromotion_code, the ID of the code that brought it, or null. It is the one you sent indiscounts, or the code the customer applied. Null without one, and for other types.amount_subtotalintegernullableForcheckout, the price's amount before any discount, in the smallest currency unit. Null for other types.amount_discountintegernullableForcheckout, what the discount takes off the first payment.0without a discount, or when the discount can no longer be used; the checkout then refuses it. Null for other types.amount_totalintegernullableForcheckout, what the first payment costs:amount_subtotalminusamount_discount. With a trial, the customer pays it when the trial ends. Null for other types.completed_attimestampnullableWhen the session completed.created_attimestampWhen the session was created, in Unix seconds.
{
"id": "A4kN1oSs",
"type": "checkout",
"status": "open",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": null,
"price_id": "Zt6YbN3q",
"subscription_id": null,
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": 5000,
"amount_discount": 0,
"amount_total": 5000,
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}Create a checkout session
POST/v1/apps/{appID}/sessions
Accepts an Idempotency-Key header.
Creates a checkout session: a checkout page that sells one price to a new subscriber. Send the customer to its url. To start a subscription without a checkout, use Create a subscription.
Body parameters
typestringrequiredcheckout.price_idstringrequiredThe price to sell. It must not be archived.trial_daysintegerOverride the price's trial with 1 to 365 days. Send0for no trial. Omit it to use the price's default. Only one trial per customer, product and app; after that, normal billing applies without an error. See Free trials.allow_promotion_codesbooleanWhether the page shows a field where the customer types a promotion code. Omit it to show the field while your app has a code that can be used on this price. Sendfalseto hide it, ortrueto always show it. Don't sendtruewithdiscounts. See Run a sale with promotion codes.discountsarrayA discount to apply before the customer arrives: one entry withcouponorpromotion_code, by ID, not both. The page then has no code field. Don't send it withallow_promotion_codes: true. A discount that can't be used returns422with codecoupon_invalidfordiscounts.customer_idstringAn existing customer to bill. The checkout shows their details locked. Don't send it withcustomer.customerobjectDetails to prefill for a new customer. The checkout shows the email and name you send locked, and the customer fills in the rest. Don't send it withcustomer_id.Show child parametersHide child parameters
emailstringTheir email address. It must contain@.namestringTheir name.phone_numberstringTheir phone number with its country code, like+237671234567. Optional. The payment step sends the payment request to it, and the customer can choose another number there. Without it, the payment step asks for the number.
success_urlstringWhere to send the customer once the session completes. Abuna fills in its placeholders, or adds the IDs as query parameters if it has none. Defaults to your app's Success URL.cancel_urlstringWhere to send the customer if they leave before paying. Defaults to your app's Cancel URL.updates_channelstringWhich chat app the checkout offers first for payment reminders, once the customer pays. Email always goes out. One of the four values below. Defaults toask.upgrade_timingstringWhen a returning customer's switch to a higher price of the same product takes effect.now, the default: they pay the difference now and switch once it is paid.next_renewal: nothing is charged now, and they switch at their next renewal.metadataobjectYour own keys and values, sent back in the session's events. The subscription the session starts gets them too. Up to 20 keys. Each key is 1 to 40 characters, and each value is a string of up to 500 characters.
updates_channel
For a free trial, the customer confirms their contact details and consent without a charge. The session completes when the trial starts, and the customer can choose reminders before going on to success_url. Use the webhooks, not the redirect, to grant access.
When your app offers a chat app, the payment step asks the customer to connect WhatsApp or Telegram, and they can pay only once one is on. A free trial asks after it starts instead, on its done screen, where email only is also a choice. Email goes out either way. updates_channel sets which chat app comes first:
ask: your app's chat apps in the usual order: WhatsApp when it is on, then Telegram. This is the default.telegram: Telegram comes first.whatsapp: WhatsApp comes first.email: email only. The checkout offers no chat app and doesn't ask for one.
With any value except email, the customer connects any chat app the payment step offers. Later, they can turn WhatsApp or Telegram on or off in their customer portal. A customer who already has a chat app connected keeps it, and so does one who checks out with saved details that include a chat app: they aren't asked again. The payment step says where their reminders go and lets them change it.
If you send a channel your app doesn't offer, because it is turned off in its settings or, for WhatsApp, isn't on your team's plan, the checkout still opens and works like ask. If your app offers no chat app at all, the checkout offers none and the customer pays with email reminders. The session's updates_channel shows what applies now.
A customer who chooses WhatsApp confirms their WhatsApp number with a 6-digit code sent on WhatsApp. WhatsApp isn't on until they confirm it. See WhatsApp.
A customer who chooses Telegram opens it from the payment step and taps Start, then pays. Once paid, they go on to your success_url. Some close the tab before they get there, so don't give access from the success page. Use the webhooks instead.
Returning customers
A customer can come back to a checkout with the email they already subscribe with in your app. Abuna matches the email, ignoring case and spaces around it. The phone number never identifies a customer, because people often pay from someone else's number. The same phone number with another email is a new customer, and a checkout without an email never matches. With customer_id, that customer's email is the one matched. Checkout links work the same way. What happens depends on the customer's subscriptions to the same product that haven't ended:
- Same price, first payment not made yet: the checkout takes them back to that payment. No new subscription, customer, or invoice is created. The session's
subscription_idis that subscription, and the session completes when it is paid, as usual. This page only takes the payment. It never shows subscription details, invoices, or links to manage the subscription, even after payment. Abuna emails the customer their subscription link with the receipt. - Same price,
activeorpast_due: the checkout is refused with409already_subscribed. The page tells them they are already subscribed and offers to email them their subscription links. Nothing is created or charged, and the session stays open. - Another price of the same product,
activeorpast_due, in the same currency: nothing changes at checkout. Abuna emails the customer a link to switch that subscription to the new price, and the page asks them to check their email. No second subscription is created. See Switching plan at checkout. - Another price of the same product, first payment not made yet: a new subscription starts, as usual. The unpaid one stays as it is: the customer can still pay it, and if they don't, it ends like any first payment that is never made, with
subscription.canceledand reasoncheckout_expired. - Another product, or a subscription that was canceled or has ended: a new subscription, as usual.
Creating a subscription with POST /subscriptions is not affected.
Switching plan at checkout
Anyone can type an email at checkout, so a checkout never changes a subscription by itself. Abuna emails the customer a link to the switch, and the page asks them to check their email. The page says the same whether or not the email has a subscription, and shows no IDs. The link works for up to 7 days, and never past the end of the current paid period. It opens a page with the current plan, the new one, and what the switch costs now. Nothing changes until the customer confirms there. A newer switch request replaces the pending offer, and only the latest email's link can confirm it. The same switch asked for again within 5 minutes keeps its link and sends no second email. In Test mode no email goes out. The email, with its link, is recorded as a notification.captured event, under Events in the dashboard.
The switch follows the plan change rules:
- Downgrade, to a price that costs the same or less: nothing is charged now. The customer keeps the current plan until the paid period ends, then renews on the new price.
- Upgrade, with
upgrade_timingnow, the default: the customer pays now the new price less the unused time of the current period, and the switch applies once that payment succeeds. With nothing to pay, it applies when they confirm. - Upgrade, with
upgrade_timingnext_renewal: nothing is charged now. The customer keeps the current plan until the paid period ends, then renews on the new price.
Checkout links always use now. Abuna sends plan_offer.created when the switch is emailed, even if the customer never confirms, and plan_offer.confirmed when they do. subscription.updated follows, with change downgrade_scheduled or upgrade_scheduled for a switch that waits for the renewal, and price_changed when the new price applies. An upgrade with something to pay sends invoice.created and invoice.paid.
The session's subscription_id is the existing subscription, and its plan_offer_id is set once the switch is emailed. It completes when the customer confirms a downgrade, an upgrade at the next renewal, or an upgrade with nothing to pay, or when they pay an upgrade. Its session.completed data then has the switch fields. The customer goes on to your success URL as usual, with the session's ID and the existing subscription's ID.
Once it emails a switch, the session stays open as long as the offer does, instead of 24 hours: up to 7 days after the switch is offered, and never past the end of the current paid period. Its expires_at moves to the offer's end. It also expires when the offer is replaced or canceled, or when an upgrade it started goes unpaid and lapses. An upgrade the customer confirmed but hasn't paid keeps it open until it is paid or lapses. Abuna then sends session.expired.
Returns the session with status 201. It can also return:
422with codeinvalidwhen a field fails. Eacherrorsitem names the field: noprice_id(required), aprice_idorcustomer_idthe app doesn't have (not_found),customersent withcustomer_id(invalid), anupdates_channelthat isn't one of the four values (invalid), a badcustomer.email(invalid) orcustomer.phone_number(phone_invalid), acustomer.phone_numberfrom a country your payment provider can't charge (phone_country_unsupported), a URL that breaks the URL rules (url_invalid), anupgrade_timingthat isn'tnowornext_renewal(invalid), ormetadatapast its limits (invalid).410with codeprice_archivedwhen the price is archived.422with codenot_accepting_paymentswhen a Live app can't take payments yet.422with codecoupon_invalidwhen a discount indiscountscan't be used, or422with anerrorsitem fordiscountswhen you send it withallow_promotion_codes: true.422with codeidempotency_key_reusedor409with codeidempotency_in_progress. See Idempotent requests.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43" \
-d '{
"type": "checkout",
"price_id": "Zt6YbN3q",
"customer": {"email": "ana@example.com"},
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"metadata": {"user_id": "42"}
}'{
"id": "A4kN1oSs",
"type": "checkout",
"status": "open",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": null,
"price_id": "Zt6YbN3q",
"subscription_id": null,
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": 5000,
"amount_discount": 0,
"amount_total": 5000,
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}Create a payment session
POST/v1/apps/{appID}/sessions
Accepts an Idempotency-Key header.
Creates a payment session: a pay page for one open invoice. Nothing is charged until the customer pays on the page. To charge the customer's saved phone number from your server instead, use Charge an invoice.
Find open invoices with List invoices and status=open, or keep the invoice_id from the invoice.created event.
Body parameters
typestringrequiredpayment.invoice_idstringrequiredThe open invoice the customer pays.success_urlstringWhere to send the customer once the session completes. Abuna fills in its placeholders, or adds the IDs as query parameters if it has none. Defaults to your app's Success URL.cancel_urlstringWhere to send the customer if they leave without paying. Defaults to your app's Cancel URL.metadataobjectYour own keys and values, sent back in the session's events. Up to 20 keys. Each key is 1 to 40 characters, and each value is a string of up to 500 characters.
Returns the session with status 201. It can also return:
422with codeinvalidwhen a field fails: noinvoice_id(required), aninvoice_idthe app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), ormetadatapast its limits (invalid).409with codealready_paidwhen the invoice is already paid, or409with codeinvoice_not_openwhen it is void, including the invoice of a canceled subscription.422with codenot_accepting_paymentswhen a Live app can't take payments yet.422with codeidempotency_key_reusedor409with codeidempotency_in_progress. See Idempotent requests.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "payment",
"invoice_id": "V2nC8xEi",
"success_url": "https://example.com/billing/paid",
"cancel_url": "https://example.com/billing",
"metadata": {"user_id": "42"}
}'{
"id": "z8TmY5Pq",
"type": "payment",
"status": "open",
"url": "https://app.abuna.app/pay/3a8d1f6c9e2b5a7d0f4c8e1b6a9d3f7c2e5b",
"success_url": "https://example.com/billing/paid",
"cancel_url": "https://example.com/billing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": null,
"subscription_id": "x9QbL2sK",
"invoice_id": "V2nC8xEi",
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": null,
"upgrade_timing": null,
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": null,
"amount_discount": null,
"amount_total": null,
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}Create a plan change session
POST/v1/apps/{appID}/sessions
Accepts an Idempotency-Key header.
Creates a plan_change session: a page where the customer confirms a move to another price, and pays for an upgrade. Nothing changes until they confirm. Abuna doesn't email or message the customer, so send them to the url yourself. Changing plan explains upgrades, downgrades, and what each costs.
Body parameters
typestringrequiredplan_change.subscription_idstringrequiredThe subscription to move. It must beactiveorpast_due.price_idstringrequiredThe new price. It must be one of the subscription's plan options.success_urlstringWhere to send the customer once the session completes. Abuna fills in its placeholders, or adds the IDs as query parameters if it has none. Defaults to your app's Success URL.cancel_urlstringThe "Back to" link on the confirm and pay steps. Defaults to your app's Cancel URL.metadataobjectYour own keys and values, sent back in the session's events. Up to 20 keys. Each key is 1 to 40 characters, and each value is a string of up to 500 characters.
Returns the session with status 201. It can also return:
422with codeinvalidwhen a field fails: nosubscription_idorprice_id(required), asubscription_idthe app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), ormetadatapast its limits (invalid).422with codeprice_not_eligiblewhen the price isn't one of the plan options.409with codeplan_change_unavailablewhen the subscription isn'tactiveorpast_due.422with codeidempotency_key_reusedor409with codeidempotency_in_progress. See Idempotent requests.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "plan_change",
"subscription_id": "x9QbL2sK",
"price_id": "Hc8LmV2s",
"success_url": "https://example.com/plan/changed",
"cancel_url": "https://example.com/plan",
"metadata": {"user_id": "42"}
}'{
"id": "G2wP6hCs",
"type": "plan_change",
"status": "open",
"url": "https://app.abuna.app/plan-change/5d2b8e1f4a7c0d3e6b9f2a5c8e1d4b7a0f3c",
"success_url": "https://example.com/plan/changed",
"cancel_url": "https://example.com/plan",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": "Hc8LmV2s",
"subscription_id": "x9QbL2sK",
"invoice_id": null,
"plan_offer_id": "q2WkR5oF",
"at_period_end": null,
"updates_channel": null,
"upgrade_timing": null,
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": null,
"amount_discount": null,
"amount_total": null,
"expires_at": 1728204800,
"completed_at": null,
"created_at": 1727600000
}Create a cancel session
POST/v1/apps/{appID}/sessions
Accepts an Idempotency-Key header.
Creates a cancel session: a page where the customer confirms a cancel. Nothing changes until they confirm. To cancel without asking the customer, use Cancel a subscription.
Body parameters
typestringrequiredcancel.subscription_idstringrequiredThe subscription to cancel. It must betrialing,activeorpast_due.at_period_endbooleantrueends the subscription at the end of the paid period, andfalseends it right away. Defaults to your app'scustomer_cancel, read when the session is created.success_urlstringWhere to send the customer once the session completes. Abuna fills in its placeholders, or adds the IDs as query parameters if it has none. Defaults to your app's Success URL.cancel_urlstringThe "Back to" link on the confirm page. Defaults to your app's Cancel URL.metadataobjectYour own keys and values, sent back in the session's events. Up to 20 keys. Each key is 1 to 40 characters, and each value is a string of up to 500 characters.
Returns the session with status 201. It can also return:
422with codeinvalidwhen a field fails: nosubscription_id(required), asubscription_idthe app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), ormetadatapast its limits (invalid).409with codesubscription_canceledwhen the subscription has ended,409with codesubscription_not_activewhen it ispending, with its first period not paid yet, or409with codecancel_already_scheduledwhen a cancel is already scheduled.422with codeidempotency_key_reusedor409with codeidempotency_in_progress. See Idempotent requests.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "cancel",
"subscription_id": "x9QbL2sK",
"at_period_end": true,
"success_url": "https://example.com/account/canceled",
"cancel_url": "https://example.com/account",
"metadata": {"user_id": "42"}
}'{
"id": "n9RcL3Xu",
"type": "cancel",
"status": "open",
"url": "https://app.abuna.app/cancel/9e4b7a1d3f6c0e8b2d5a9f1c4e7b0d3a6f2c",
"success_url": "https://example.com/account/canceled",
"cancel_url": "https://example.com/account",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": null,
"subscription_id": "x9QbL2sK",
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": true,
"updates_channel": null,
"upgrade_timing": null,
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": null,
"amount_discount": null,
"amount_total": null,
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}Create a portal session
POST/v1/apps/{appID}/sessions
Accepts an Idempotency-Key header.
Creates a portal session: the customer portal for one subscription, with a "Back to" link to your app. The subscription can have any status. Create a new one each time the customer asks to manage billing.
Body parameters
typestringrequiredportal.subscription_idstringrequiredThe subscription to manage.return_urlstringrequiredWhere the portal's "Back to" link goes.metadataobjectYour own keys and values, sent back in the session's events. Up to 20 keys. Each key is 1 to 40 characters, and each value is a string of up to 500 characters.
A portal session takes no success_url or cancel_url. Returns the session with status 201. It can also return:
422with codeinvalidwhen a field fails: nosubscription_idorreturn_url(required), asubscription_idthe app doesn't have (not_found), areturn_urlthat breaks the URL rules (url_invalid), ormetadatapast its limits (invalid).422with codeidempotency_key_reusedor409with codeidempotency_in_progress. See Idempotent requests.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "portal",
"subscription_id": "x9QbL2sK",
"return_url": "https://example.com/account",
"metadata": {"user_id": "42"}
}'{
"id": "D1vT7rQf",
"type": "portal",
"status": "open",
"url": "https://app.abuna.app/portal/2c7f0a3d6b9e1c4f8a2d5b7e0c3f6a9d1b4e",
"success_url": null,
"cancel_url": null,
"return_url": "https://example.com/account",
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": null,
"subscription_id": "x9QbL2sK",
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": null,
"upgrade_timing": null,
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": null,
"amount_discount": null,
"amount_total": null,
"expires_at": 1727603600,
"completed_at": null,
"created_at": 1727600000
}List sessions
GET/v1/apps/{appID}/sessions
Lists the app's sessions, newest first, one page at a time. All parameters are optional, and a blank one is ignored.
Parameters
typestringOnly sessions of this type:checkout,payment,plan_change,cancel, orportal.statusstringopen,completed, orexpired.subscription_idstringOnly sessions for this subscription.limitintegerHow many sessions to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Response attributes
itemsarrayThe page's sessions. Empty when nothing matches.next_cursorstringnullablePass it as cursor to get the next page. It is null on the last page. Treat it as opaque.
Returns 200. A value that isn't allowed returns 422 with code invalid and the parameter's name in errors.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "A4kN1oSs",
"type": "checkout",
"status": "completed",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"subscription_id": "x9QbL2sK",
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": 5000,
"amount_discount": 0,
"amount_total": 5000,
"expires_at": 1727686400,
"completed_at": 1727600600,
"created_at": 1727600000
}
],
"next_cursor": null
}Retrieve a session
GET/v1/apps/{appID}/sessions/{id}
Retrieves a session.
Returns the session. If the app has no session with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs \
-H "Authorization: Bearer sk_test_..."{
"id": "A4kN1oSs",
"type": "checkout",
"status": "completed",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"subscription_id": "x9QbL2sK",
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": 5000,
"amount_discount": 0,
"amount_total": 5000,
"expires_at": 1727686400,
"completed_at": 1727600600,
"created_at": 1727600000
}Expire a session
POST/v1/apps/{appID}/sessions/{id}/expire
Accepts an Idempotency-Key header.
Ends an open session now, before its expires_at. Its page tells the customer the session has expired, and Abuna sends session.expired. A subscription a checkout session already started stays pending, as described in the Sessions guide. Expiring a plan_change session, or a checkout session that offered a switch, also withdraws its plan offer, and Abuna sends plan_offer.canceled.
Returns the session. If it is already completed or expired, returns 409 with code session_not_open. If the app has no session with that ID, returns 404 with code not_found.
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \
-H "Authorization: Bearer sk_test_..."{
"id": "A4kN1oSs",
"type": "checkout",
"status": "expired",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "https://example.com/welcome",
"cancel_url": "https://example.com/pricing",
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": null,
"price_id": "Zt6YbN3q",
"subscription_id": null,
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "telegram",
"upgrade_timing": "next_renewal",
"trial_days": null,
"allow_promotion_codes": null,
"discount": null,
"amount_subtotal": 5000,
"amount_discount": 0,
"amount_total": 5000,
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}Session types
Each type has its own page, its own rule for completing, and its own session.completed data. All of them send session.expired with the data in the events reference.
checkout
A trial checkout first emails the customer a code to confirm their email. Once they enter it, the checkout completes without payment and the subscription starts trialing. It sends session.completed and subscription.created, not subscription.paid. Their subscription includes trial_ends_at in Unix seconds, or null without a trial.
Created by Create a checkout session. The url is a checkout page for price_id. The session completes when the first payment succeeds and the subscription becomes active, or when a free trial starts. It expires 24 hours after creation. Its session.completed data has session_id, type, subscription_id, customer_id, price_id, metadata, completed_at, and the customer's updates.
A returning customer can complete the session on their existing subscription instead. When the session offered a switch, it completes once the switch is confirmed, or paid for an upgrade, and it lasts as long as the switch offer. Its session.completed data then has these fields, the same as a plan_change session's:
session.completed data for a switch
session_idstringThe session.typestringAlwayscheckout.subscription_idstringThe customer's existing subscription.customer_idstringIts customer.metadataobjectThe metadata you passed when you created the session.completed_attimestampWhen the session completed.plan_offer_idstringThe plan offer the checkout made.previous_price_idstringThe price before the switch.price_idstringThe new price, the one the session sells.directionstringupgradeordowngrade.effective_attimestampWhen the new price starts: when the upgrade applied, or the end of the paid period for a downgrade or an upgrade at the next renewal.
{
"session_id": "A4kN1oSs",
"type": "checkout",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600900,
"plan_offer_id": "r7TnK4pW",
"previous_price_id": "Hc8LmV2s",
"price_id": "Zt6YbN3q",
"direction": "upgrade",
"effective_at": 1730192000,
"subscription": {
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Hc8LmV2s",
"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
}
}payment
Created by Create a payment session. The url is a pay page for invoice_id. The session completes when that invoice is paid through it. It expires 24 hours after creation, or sooner once the invoice can't be paid through it: paid another way, voided, or its subscription ended. An invoice paid another way expires the session, so use invoice.paid to know an invoice is settled. The pay links Abuna sends in emails and on WhatsApp and Telegram keep working on their own.
session.completed data
session_idstringThe session.typestringAlwayspayment.invoice_idstringThe invoice the customer paid.subscription_idstringIts subscription.customer_idstringIts customer.metadataobjectThe metadata you passed when you created the session.completed_attimestampWhen the session completed.
{
"session_id": "z8TmY5Pq",
"type": "payment",
"invoice_id": "V2nC8xEi",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600600,
"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
}
}plan_change
Created by Create a plan change session. The url is the confirm page for moving subscription_id to price_id. Creating the session creates a plan offer behind it and sends plan_offer.created, but Abuna doesn't email or message the customer. It replaces any pending offer or plan_change session, and the older session gets session.expired.
The session completes when the change is done:
- A downgrade: when the customer confirms. It is scheduled for the end of the paid period.
- An upgrade: when its payment succeeds. An upgrade that costs
0applies, and completes, at confirm.
It expires 7 days after creation, or at the end of the current period if that comes first. It also expires when its offer is replaced, canceled, or expires, or when an upgrade it started goes unpaid and lapses. A confirmed upgrade waiting for payment stays open until it is paid or lapses.
plan_offer.*, subscription.updated, and invoice.* events still fire as for any plan change. Use session.completed to know the customer finished the flow you started, and subscription.updated to know the price changed. A downgrade changes the price at the end of the period, after the session completes.
session.completed data
session_idstringThe session.typestringAlwaysplan_change.subscription_idstringThe subscription.customer_idstringIts customer.metadataobjectThe metadata you passed when you created the session.completed_attimestampWhen the session completed.plan_offer_idstringThe plan offer the session created.previous_price_idstringThe price before the change.price_idstringThe new price.directionstringupgradeordowngrade.effective_attimestampWhen the new price starts: when the upgrade applied, or the end of the paid period for a downgrade.
{
"session_id": "G2wP6hCs",
"type": "plan_change",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600900,
"plan_offer_id": "q2WkR5oF",
"previous_price_id": "Zt6YbN3q",
"price_id": "Hc8LmV2s",
"direction": "upgrade",
"effective_at": 1727600900,
"subscription": {
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Hc8LmV2s",
"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": 1727600900,
"current_period_end": 1730192900,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}
}cancel
During a trial, a customer's cancel is scheduled for trial_ends_at. Access stays until then and no invoice is payable. To end a trial immediately from your server, use the subscription cancel API.
Created by Create a cancel session. The url is a confirm page for canceling subscription_id. It shows what happens and the end date, with a Confirm button and a "Back to" link to cancel_url. The subscription must be trialing, active or past_due, and not already scheduled to cancel. You can't create one for a pending subscription: you get 409 with code subscription_not_active.
at_period_end is set when you create the session: the value you sent, or the app's customer_cancel setting. The cancel follows the usual cancel rules:
- At the end of the period, the subscription stays
activeand the customer keeps access until the paid period ends. - If the current period isn't paid, as while the subscription is
past_due, or is already over, the subscription ends right away instead. The page tells the customer before they confirm. - A cancel that takes effect right away voids the subscription's open invoices.
The session completes when the customer confirms, whether the cancel is scheduled or immediate. It expires 24 hours after creation if they don't. subscription.updated (scheduled) or subscription.canceled (immediate) still fire as for any cancel. For a scheduled cancel, subscription.canceled fires later, at cancel_at. Rely on those events to change access.
session.completed data
session_idstringThe session.typestringAlwayscancel.subscription_idstringThe subscription.customer_idstringIts customer.metadataobjectThe metadata you passed when you created the session.completed_attimestampWhen the customer confirmed.cancel_attimestampnullableWhen the subscription ends. Null when it ended right away.immediatebooleantruewhen the subscription ended right away.
{
"session_id": "n9RcL3Xu",
"type": "cancel",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600300,
"cancel_at": 1730192000,
"immediate": false,
"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": 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
}
}portal
Created by Create a portal session. The url is the customer portal for subscription_id, with a "Back to" link to return_url at the top. The subscription can have any status. The link stays as the customer changes plan, pays, turns on WhatsApp or Telegram messages, or updates their contact details. On the pay page, the back and done links go to return_url, and "Manage subscription" returns to the portal. Every one of these links is your return_url exactly as you sent it. Abuna adds no query parameters or IDs to it.
What the portal shows depends on the subscription's status:
trialing: the trial end date and a cancel that keeps access until that date, without an invoice to pay.pending: the first invoice with its pay-by date and a Pay button, and a Cancel button that ends the subscription right away. There is no plan change.activeorpast_due: the plan, invoices, contact details, a Cancel button, and the prices the customer can change to, if any. Apast_duesubscription also shows its unpaid invoice with a Pay button.canceled: the plan, the date it was canceled, the invoices, and the customer's contact details, which they can still update. There is nothing to pay, and no plan change or cancel.
The url must be opened within 1 hour of creation, or it shows an invalid link. Once opened, it keeps working like the customer portal. Create a new session each time the customer asks to manage billing.
The session completes when the customer first opens it. That doesn't mean they changed anything: what they do in the portal sends its own events, like subscription.updated, subscription.canceled, invoice.paid, and customer.updated. A session nobody opens expires after 1 hour. The subscription's subscription_page_url keeps working on its own, with no link back to your app.
session.completed data
session_idstringThe session.typestringAlwaysportal.subscription_idstringThe subscription.customer_idstringIts customer.metadataobjectThe metadata you passed when you created the session.completed_attimestampWhen the customer first opened the portal.
{
"session_id": "D1vT7rQf",
"type": "portal",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600020,
"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
}
}Redirect URLs
success_url and cancel_url default to your app's Success URL and Cancel URL. Abuna copies them onto the session when you create it, so changing the setting later doesn't change existing sessions. A portal session takes return_url instead, and has neither.
Every URL must be an absolute https URL with a host. In Test mode, http also works for localhost, 127.0.0.1, and [::1]. This includes the Test app's default Success URL and Cancel URL, for every session type. Any other URL returns 422 with code invalid and an errors item with code url_invalid.
Success URL placeholders
Cancel sessions and plan changes with no payment due send the customer straight to success_url. Checkout, payment, and paid upgrades show a "Back to" button instead. Both use success_url with these placeholders filled in:
{SESSION_ID}: every type.{SUBSCRIPTION_ID}: every type.{INVOICE_ID}:paymentonly.
If the URL has no placeholder, Abuna adds the same IDs as query parameters: session_id, subscription_id, and for payment, invoice_id. It keeps your own query parameters and the # fragment. cancel_url gets nothing added. A portal session has no success_url. Its "Back to" link goes to return_url.
Next steps
- SessionsSend a customer from your app to subscribe, pay, change plan or cancel, bring them back, and know for sure when they're done.
- SubscriptionsStart, list, read, update, cancel, keep and change the plan of a customer's subscription.
- EventsThe record of everything that happened in an app, and every event type.
- ErrorsStatus codes, error codes, field errors, rate limits, request IDs, and how to retry safely.