Skip to content
ABUNA
DocsSessions

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.

View as Markdown

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. Send price_id.
  • payment: a pay page for one open invoice. Send invoice_id.
  • plan_change: the customer confirms a move to another price. Send subscription_id and price_id.
  • cancel: the customer confirms a cancel. Send subscription_id.
  • portal: the customer portal with a link back to your app. Send subscription_id and return_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

  • idstring

    Unique identifier for the session.
  • typestring

    What the session is for: checkout, payment, plan_change, cancel, or portal, as you sent it when you created the session.
  • statusstring

    open until it ends. completed once the customer finishes, as each type defines it, or expired once it runs out or you expire it. A session that ends never changes again.
  • urlstring

    The page to send the customer to. It belongs to this customer, so don't share it.
  • success_urlstringnullable

    Where 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 for portal. See Success URL placeholders.
  • cancel_urlstringnullable

    Where 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_urlstringnullable

    For portal, where the portal's "Back to" link goes. Null for other types.
  • metadataobject

    Your own keys and values, as you sent them. {} when you sent none.
  • customer_idstringnullable

    The customer you passed, or the one the customer's details created. For the other types, the subscription's customer. Null until known.
  • price_idstringnullable

    For checkout, the price the session sells. For plan_change, the new price. Null for the other types.
  • subscription_idstringnullable

    For checkout, 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_idstringnullable

    For payment, the invoice the customer pays. Null for other types.
  • plan_offer_idstringnullable

    For plan_change, the plan offer the session created. For checkout, the plan offer made once the checkout offers a returning customer a switch, or null. Null for other types.
  • at_period_endbooleannullable

    For cancel, 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's customer_cancel. Null for other types.
  • updates_channelstringnullable

    For checkout, which chat app the checkout offers first for payment reminders once the customer pays, as it applies now: ask, telegram, whatsapp, or email. A channel your app can't offer shows as ask. See Create a checkout session. Null for other types.
  • upgrade_timingstringnullable

    For checkout, when a returning customer's switch to a higher price takes effect: now or next_renewal, as you sent it or now by default. Null for other types.
  • expires_attimestamp

    When the session runs out, in Unix seconds. 24 hours after creation for checkout, payment, and cancel. 7 days, or the end of the current period if sooner, for plan_change. 1 hour for portal, which must be opened by then. A checkout session that offered a switch takes the switch offer's end instead.
  • trial_daysintegernullable

    For checkout, your requested trial override: 1 to 365 days, or 0 to disable it. Null uses the price's default. Null for other session types. Eligibility is checked when the subscription starts.
  • allow_promotion_codesbooleannullable

    For checkout, the value you sent: true always shows the promotion code field, false hides it, and null shows it while a code can be used on the price. false too when you sent discounts. Null for other types.
  • discountobjectnullable

    For checkout, the discount on the session: coupon, the coupon, and promotion_code, the ID of the code that brought it, or null. It is the one you sent in discounts, or the code the customer applied. Null without one, and for other types.
  • amount_subtotalintegernullable

    For checkout, the price's amount before any discount, in the smallest currency unit. Null for other types.
  • amount_discountintegernullable

    For checkout, what the discount takes off the first payment. 0 without a discount, or when the discount can no longer be used; the checkout then refuses it. Null for other types.
  • amount_totalintegernullable

    For checkout, what the first payment costs: amount_subtotal minus amount_discount. With a trial, the customer pays it when the trial ends. Null for other types.
  • completed_attimestampnullable

    When the session completed.
  • created_attimestamp

    When the session was created, in Unix seconds.
The session object
{
  "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

  • typestringrequired

    checkout.
  • price_idstringrequired

    The price to sell. It must not be archived.
  • trial_daysinteger

    Override the price's trial with 1 to 365 days. Send 0 for 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_codesboolean

    Whether 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. Send false to hide it, or true to always show it. Don't send true with discounts. See Run a sale with promotion codes.
  • discountsarray

    A discount to apply before the customer arrives: one entry with coupon or promotion_code, by ID, not both. The page then has no code field. Don't send it with allow_promotion_codes: true. A discount that can't be used returns 422 with code coupon_invalid for discounts.
  • customer_idstring

    An existing customer to bill. The checkout shows their details locked. Don't send it with customer.
  • customerobject

    Details 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 with customer_id.
    Show child parametersHide child parameters
    • emailstring

      Their email address. It must contain @.
    • namestring

      Their name.
    • phone_numberstring

      Their 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_urlstring

    Where 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_urlstring

    Where to send the customer if they leave before paying. Defaults to your app's Cancel URL.
  • updates_channelstring

    Which chat app the checkout offers first for payment reminders, once the customer pays. Email always goes out. One of the four values below. Defaults to ask.
  • upgrade_timingstring

    When 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.
  • metadataobject

    Your 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_id is 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, active or past_due: the checkout is refused with 409 already_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, active or past_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.canceled and reason checkout_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_timing now, 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_timing next_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:

  • 422 with code invalid when a field fails. Each errors item names the field: no price_id (required), a price_id or customer_id the app doesn't have (not_found), customer sent with customer_id (invalid), an updates_channel that isn't one of the four values (invalid), a bad customer.email (invalid) or customer.phone_number (phone_invalid), a customer.phone_number from a country your payment provider can't charge (phone_country_unsupported), a URL that breaks the URL rules (url_invalid), an upgrade_timing that isn't now or next_renewal (invalid), or metadata past its limits (invalid).
  • 410 with code price_archived when the price is archived.
  • 422 with code not_accepting_payments when a Live app can't take payments yet.
  • 422 with code coupon_invalid when a discount in discounts can't be used, or 422 with an errors item for discounts when you send it with allow_promotion_codes: true.
  • 422 with code idempotency_key_reused or 409 with code idempotency_in_progress. See Idempotent requests.
POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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

  • typestringrequired

    payment.
  • invoice_idstringrequired

    The open invoice the customer pays.
  • success_urlstring

    Where 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_urlstring

    Where to send the customer if they leave without paying. Defaults to your app's Cancel URL.
  • metadataobject

    Your 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:

  • 422 with code invalid when a field fails: no invoice_id (required), an invoice_id the app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), or metadata past its limits (invalid).
  • 409 with code already_paid when the invoice is already paid, or 409 with code invoice_not_open when it is void, including the invoice of a canceled subscription.
  • 422 with code not_accepting_payments when a Live app can't take payments yet.
  • 422 with code idempotency_key_reused or 409 with code idempotency_in_progress. See Idempotent requests.
POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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

  • typestringrequired

    plan_change.
  • subscription_idstringrequired

    The subscription to move. It must be active or past_due.
  • price_idstringrequired

    The new price. It must be one of the subscription's plan options.
  • success_urlstring

    Where 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_urlstring

    The "Back to" link on the confirm and pay steps. Defaults to your app's Cancel URL.
  • metadataobject

    Your 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:

  • 422 with code invalid when a field fails: no subscription_id or price_id (required), a subscription_id the app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), or metadata past its limits (invalid).
  • 422 with code price_not_eligible when the price isn't one of the plan options.
  • 409 with code plan_change_unavailable when the subscription isn't active or past_due.
  • 422 with code idempotency_key_reused or 409 with code idempotency_in_progress. See Idempotent requests.
POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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

  • typestringrequired

    cancel.
  • subscription_idstringrequired

    The subscription to cancel. It must be trialing, active or past_due.
  • at_period_endboolean

    true ends the subscription at the end of the paid period, and false ends it right away. Defaults to your app's customer_cancel, read when the session is created.
  • success_urlstring

    Where 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_urlstring

    The "Back to" link on the confirm page. Defaults to your app's Cancel URL.
  • metadataobject

    Your 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:

  • 422 with code invalid when a field fails: no subscription_id (required), a subscription_id the app doesn't have (not_found), a URL that breaks the URL rules (url_invalid), or metadata past its limits (invalid).
  • 409 with code subscription_canceled when the subscription has ended, 409 with code subscription_not_active when it is pending, with its first period not paid yet, or 409 with code cancel_already_scheduled when a cancel is already scheduled.
  • 422 with code idempotency_key_reused or 409 with code idempotency_in_progress. See Idempotent requests.
POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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

  • typestringrequired

    portal.
  • subscription_idstringrequired

    The subscription to manage.
  • return_urlstringrequired

    Where the portal's "Back to" link goes.
  • metadataobject

    Your 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:

  • 422 with code invalid when a field fails: no subscription_id or return_url (required), a subscription_id the app doesn't have (not_found), a return_url that breaks the URL rules (url_invalid), or metadata past its limits (invalid).
  • 422 with code idempotency_key_reused or 409 with code idempotency_in_progress. See Idempotent requests.
POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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

  • typestring

    Only sessions of this type: checkout, payment, plan_change, cancel, or portal.
  • statusstring

    open, completed, or expired.
  • subscription_idstring

    Only sessions for this subscription.
  • limitinteger

    How many sessions to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from the previous page. Send the same filters with it.

Response attributes

  • itemsarray

    The page's sessions. Empty when nothing matches.
  • next_cursorstringnullable

    Pass 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.

GET /v1/apps/{appID}/sessions
curl "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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.

GET /v1/apps/{appID}/sessions/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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.

POST /v1/apps/{appID}/sessions/{id}/expire
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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_idstring

    The session.
  • typestring

    Always checkout.
  • subscription_idstring

    The customer's existing subscription.
  • customer_idstring

    Its customer.
  • metadataobject

    The metadata you passed when you created the session.
  • completed_attimestamp

    When the session completed.
  • plan_offer_idstring

    The plan offer the checkout made.
  • previous_price_idstring

    The price before the switch.
  • price_idstring

    The new price, the one the session sells.
  • directionstring

    upgrade or downgrade.
  • effective_attimestamp

    When 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.completed data for a switch
{
  "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_idstring

    The session.
  • typestring

    Always payment.
  • invoice_idstring

    The invoice the customer paid.
  • subscription_idstring

    Its subscription.
  • customer_idstring

    Its customer.
  • metadataobject

    The metadata you passed when you created the session.
  • completed_attimestamp

    When the session completed.
session.completed data
{
  "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 0 applies, 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_idstring

    The session.
  • typestring

    Always plan_change.
  • subscription_idstring

    The subscription.
  • customer_idstring

    Its customer.
  • metadataobject

    The metadata you passed when you created the session.
  • completed_attimestamp

    When the session completed.
  • plan_offer_idstring

    The plan offer the session created.
  • previous_price_idstring

    The price before the change.
  • price_idstring

    The new price.
  • directionstring

    upgrade or downgrade.
  • effective_attimestamp

    When the new price starts: when the upgrade applied, or the end of the paid period for a downgrade.
session.completed data
{
  "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 active and 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_idstring

    The session.
  • typestring

    Always cancel.
  • subscription_idstring

    The subscription.
  • customer_idstring

    Its customer.
  • metadataobject

    The metadata you passed when you created the session.
  • completed_attimestamp

    When the customer confirmed.
  • cancel_attimestampnullable

    When the subscription ends. Null when it ended right away.
  • immediateboolean

    true when the subscription ended right away.
session.completed data
{
  "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.
  • active or past_due: the plan, invoices, contact details, a Cancel button, and the prices the customer can change to, if any. A past_due subscription 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_idstring

    The session.
  • typestring

    Always portal.
  • subscription_idstring

    The subscription.
  • customer_idstring

    Its customer.
  • metadataobject

    The metadata you passed when you created the session.
  • completed_attimestamp

    When the customer first opened the portal.
session.completed data
{
  "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}: payment only.

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