# 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. Source: https://abuna.app/docs/api/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](https://abuna.app/docs/guides/sessions.md) 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`](https://abuna.app/docs/api/sessions.md#create-checkout): a checkout page that sells one price. Send `price_id`. - [`payment`](https://abuna.app/docs/api/sessions.md#create-payment): a pay page for one open invoice. Send `invoice_id`. - [`plan_change`](https://abuna.app/docs/api/sessions.md#create-plan-change): the customer confirms a move to another price. Send `subscription_id` and `price_id`. - [`cancel`](https://abuna.app/docs/api/sessions.md#create-cancel): the customer confirms a cancel. Send `subscription_id`. - [`portal`](https://abuna.app/docs/api/sessions.md#create-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** - `id` (string): Unique identifier for the session. - `type` (string): What the session is for: `checkout`, `payment`, `plan_change`, `cancel`, or `portal`, as you sent it when you created the session. - `status` (string): `open` until it ends. `completed` once the customer finishes, as each [type](https://abuna.app/docs/api/sessions.md#types) defines it, or `expired` once it runs out or you expire it. A session that ends never changes again. - `url` (string): The page to send the customer to. It belongs to this customer, so don't share it. - `success_url` (string, nullable): 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](https://abuna.app/docs/api/sessions.md#placeholders). - `cancel_url` (string, nullable): 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_url` (string, nullable): For `portal`, where the portal's "Back to" link goes. Null for other types. - `metadata` (object): Your own keys and values, as you sent them. `{}` when you sent none. - `customer_id` (string, nullable): The customer you passed, or the one the customer's details created. For the other types, the subscription's customer. Null until known. - `price_id` (string, nullable): For `checkout`, the price the session sells. For `plan_change`, the new price. Null for the other types. - `subscription_id` (string, nullable): 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](https://abuna.app/docs/api/sessions.md#returning-customers)). For the other types, the subscription the session acts on. Null until known. - `invoice_id` (string, nullable): For `payment`, the invoice the customer pays. Null for other types. - `plan_offer_id` (string, nullable): For `plan_change`, the plan offer the session created. For `checkout`, the plan offer made once the checkout offers a returning customer a [switch](https://abuna.app/docs/api/sessions.md#checkout-switch), or null. Null for other types. - `at_period_end` (boolean, nullable): 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`](https://abuna.app/docs/api/apps.md#object). Null for other types. - `updates_channel` (string, nullable): 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](https://abuna.app/docs/api/sessions.md#create-checkout). Null for other types. - `upgrade_timing` (string, nullable): For `checkout`, when a returning customer's [switch](https://abuna.app/docs/api/sessions.md#checkout-switch) to a higher price takes effect: `now` or `next_renewal`, as you sent it or `now` by default. Null for other types. - `expires_at` (timestamp): 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](https://abuna.app/docs/api/sessions.md#checkout-switch) takes the switch offer's end instead. - `trial_days` (integer, nullable): 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_codes` (boolean, nullable): 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. - `discount` (object, nullable): For `checkout`, the discount on the session: `coupon`, the [coupon](https://abuna.app/docs/api/coupons.md#object), 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_subtotal` (integer, nullable): For `checkout`, the price's amount before any discount, in the smallest currency unit. Null for other types. - `amount_discount` (integer, nullable): 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_total` (integer, nullable): 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_at` (timestamp, nullable): When the session completed. - `created_at` (timestamp): When the session was created, in Unix seconds. **The session object** ```json { "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` Creates a [`checkout`](https://abuna.app/docs/api/sessions.md#type-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](https://abuna.app/docs/api/subscriptions.md#create). **Body parameters** - `type` (string, required): `checkout`. - `price_id` (string, required): The price to sell. It must not be archived. - `trial_days` (integer): 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](https://abuna.app/docs/guides/trials.md). - `allow_promotion_codes` (boolean): 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](https://abuna.app/docs/guides/promotion-codes.md#checkout). - `discounts` (array): 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_id` (string): An existing customer to bill. The checkout shows their details locked. Don't send it with `customer`. - `customer` (object): 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`. - `email` (string): Their email address. It must contain `@`. - `name` (string): Their name. - `phone_number` (string): 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_url` (string): Where to send the customer once the session completes. Abuna fills in its [placeholders](https://abuna.app/docs/api/sessions.md#placeholders), or adds the IDs as query parameters if it has none. Defaults to your app's Success URL. - `cancel_url` (string): Where to send the customer if they leave before paying. Defaults to your app's Cancel URL. - `updates_channel` (string): 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_timing` (string): When a returning customer's [switch](https://abuna.app/docs/api/sessions.md#checkout-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. - `metadata` (object): 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](https://abuna.app/docs/guides/customer-notifications.md#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](https://abuna.app/docs/guides/customer-notifications.md#grant-access) 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](https://abuna.app/docs/api/sessions.md#checkout-switch). - **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`](https://abuna.app/docs/api/events.md#notification-captured) event, under **Events** in the dashboard. The switch follows the [plan change rules](https://abuna.app/docs/api/subscriptions.md#changing-plan): - **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](https://abuna.app/docs/api/sessions.md#type-checkout). 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](https://abuna.app/docs/api/sessions.md#urls) (`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](https://abuna.app/docs/errors.md#idempotency). **POST /v1/apps/{appID}/sessions** cURL: ```bash 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"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43", }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"}, json={ "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"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "customer": map[string]any{"email": "ana@example.com"}, "success_url": "https://example.com/welcome", "cancel_url": "https://example.com/pricing", "updates_channel": "telegram", "upgrade_timing": "next_renewal", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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` Creates a [`payment`](https://abuna.app/docs/api/sessions.md#type-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](https://abuna.app/docs/api/invoices-and-payments.md#charge). Find open invoices with [List invoices](https://abuna.app/docs/api/invoices-and-payments.md#list) and `status=open`, or keep the `invoice_id` from the [`invoice.created`](https://abuna.app/docs/api/events.md#invoice-created) event. **Body parameters** - `type` (string, required): `payment`. - `invoice_id` (string, required): The open invoice the customer pays. - `success_url` (string): Where to send the customer once the session completes. Abuna fills in its [placeholders](https://abuna.app/docs/api/sessions.md#placeholders), or adds the IDs as query parameters if it has none. Defaults to your app's Success URL. - `cancel_url` (string): Where to send the customer if they leave without paying. Defaults to your app's Cancel URL. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md#urls) (`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](https://abuna.app/docs/errors.md#idempotency). **POST /v1/apps/{appID}/sessions** cURL: ```bash 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"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ type: "payment", invoice_id: "V2nC8xEi", success_url: "https://example.com/billing/paid", cancel_url: "https://example.com/billing", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "type": "payment", "invoice_id": "V2nC8xEi", "success_url": "https://example.com/billing/paid", "cancel_url": "https://example.com/billing", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "type" => "payment", "invoice_id" => "V2nC8xEi", "success_url" => "https://example.com/billing/paid", "cancel_url" => "https://example.com/billing", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "payment", "invoice_id": "V2nC8xEi", "success_url": "https://example.com/billing/paid", "cancel_url": "https://example.com/billing", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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` Creates a [`plan_change`](https://abuna.app/docs/api/sessions.md#type-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](https://abuna.app/docs/api/subscriptions.md#changing-plan) explains upgrades, downgrades, and what each costs. **Body parameters** - `type` (string, required): `plan_change`. - `subscription_id` (string, required): The subscription to move. It must be `active` or `past_due`. - `price_id` (string, required): The new price. It must be one of the subscription's [plan options](https://abuna.app/docs/api/subscriptions.md#list-plan-options). - `success_url` (string): Where to send the customer once the session completes. Abuna fills in its [placeholders](https://abuna.app/docs/api/sessions.md#placeholders), or adds the IDs as query parameters if it has none. Defaults to your app's Success URL. - `cancel_url` (string): The "Back to" link on the confirm and pay steps. Defaults to your app's Cancel URL. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md#urls) (`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](https://abuna.app/docs/errors.md#idempotency). **POST /v1/apps/{appID}/sessions** cURL: ```bash 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"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "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"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "plan_change", "subscription_id": "x9QbL2sK", "price_id": "Hc8LmV2s", "success_url": "https://example.com/plan/changed", "cancel_url": "https://example.com/plan", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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` Creates a [`cancel`](https://abuna.app/docs/api/sessions.md#type-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](https://abuna.app/docs/api/subscriptions.md#cancel). **Body parameters** - `type` (string, required): `cancel`. - `subscription_id` (string, required): The subscription to cancel. It must be `trialing`, `active` or `past_due`. - `at_period_end` (boolean): `true` ends the subscription at the end of the paid period, and `false` ends it right away. Defaults to your app's [`customer_cancel`](https://abuna.app/docs/api/apps.md#object), read when the session is created. - `success_url` (string): Where to send the customer once the session completes. Abuna fills in its [placeholders](https://abuna.app/docs/api/sessions.md#placeholders), or adds the IDs as query parameters if it has none. Defaults to your app's Success URL. - `cancel_url` (string): The "Back to" link on the confirm page. Defaults to your app's Cancel URL. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md#urls) (`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](https://abuna.app/docs/errors.md#idempotency). **POST /v1/apps/{appID}/sessions** cURL: ```bash 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"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "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"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "cancel", "subscription_id": "x9QbL2sK", "at_period_end": true, "success_url": "https://example.com/account/canceled", "cancel_url": "https://example.com/account", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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` Creates a [`portal`](https://abuna.app/docs/api/sessions.md#type-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** - `type` (string, required): `portal`. - `subscription_id` (string, required): The subscription to manage. - `return_url` (string, required): Where the portal's "Back to" link goes. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md#urls) (`url_invalid`), or `metadata` past its limits (`invalid`). - `422` with code `idempotency_key_reused` or `409` with code `idempotency_in_progress`. See [Idempotent requests](https://abuna.app/docs/errors.md#idempotency). **POST /v1/apps/{appID}/sessions** cURL: ```bash 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"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ type: "portal", subscription_id: "x9QbL2sK", return_url: "https://example.com/account", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "type": "portal", "subscription_id": "x9QbL2sK", "return_url": "https://example.com/account", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "type" => "portal", "subscription_id" => "x9QbL2sK", "return_url" => "https://example.com/account", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "portal", "subscription_id": "x9QbL2sK", "return_url": "https://example.com/account", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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** - `type` (string): Only sessions of this type: `checkout`, `payment`, `plan_change`, `cancel`, or `portal`. - `status` (string): `open`, `completed`, or `expired`. - `subscription_id` (string): Only sessions for this subscription. - `limit` (integer): How many sessions to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. **Response attributes** - `items` (array): The page's [sessions](https://abuna.app/docs/api/sessions.md#object). Empty when nothing matches. - `next_cursor` (string, nullable): 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: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Response** ```json { "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: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", { headers: { Authorization: "Bearer sk_test_..." }, }); const session = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", headers={"Authorization": "Bearer sk_test_..."}, ) session = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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` 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](https://abuna.app/docs/guides/sessions.md#expired-session-subscription). 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: ```bash curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", headers={"Authorization": "Bearer sk_test_..."}, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Response** ```json { "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](https://abuna.app/docs/api/events.md#session-expired). ### 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](https://abuna.app/docs/api/sessions.md#create-checkout). 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`](https://abuna.app/docs/api/customers.md#object). A [returning customer](https://abuna.app/docs/api/sessions.md#returning-customers) can complete the session on their existing subscription instead. When the session offered a [switch](https://abuna.app/docs/api/sessions.md#checkout-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`](https://abuna.app/docs/api/sessions.md#type-plan-change) session's: **session.completed data for a switch** - `session_id` (string): The session. - `type` (string): Always `checkout`. - `subscription_id` (string): The customer's existing subscription. - `customer_id` (string): Its customer. - `metadata` (object): The metadata you passed when you created the session. - `completed_at` (timestamp): When the session completed. - `plan_offer_id` (string): The plan offer the checkout made. - `previous_price_id` (string): The price before the switch. - `price_id` (string): The new price, the one the session sells. - `direction` (string): `upgrade` or `downgrade`. - `effective_at` (timestamp): 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** ```json { "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](https://abuna.app/docs/api/sessions.md#create-payment). 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_id` (string): The session. - `type` (string): Always `payment`. - `invoice_id` (string): The invoice the customer paid. - `subscription_id` (string): Its subscription. - `customer_id` (string): Its customer. - `metadata` (object): The metadata you passed when you created the session. - `completed_at` (timestamp): When the session completed. **session.completed data** ```json { "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](https://abuna.app/docs/api/sessions.md#create-plan-change). 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](https://abuna.app/docs/api/subscriptions.md#changing-plan). 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_id` (string): The session. - `type` (string): Always `plan_change`. - `subscription_id` (string): The subscription. - `customer_id` (string): Its customer. - `metadata` (object): The metadata you passed when you created the session. - `completed_at` (timestamp): When the session completed. - `plan_offer_id` (string): The plan offer the session created. - `previous_price_id` (string): The price before the change. - `price_id` (string): The new price. - `direction` (string): `upgrade` or `downgrade`. - `effective_at` (timestamp): When the new price starts: when the upgrade applied, or the end of the paid period for a downgrade. **session.completed data** ```json { "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](https://abuna.app/docs/api/subscriptions.md#cancel). Created by [Create a cancel session](https://abuna.app/docs/api/sessions.md#create-cancel). 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](https://abuna.app/docs/api/subscriptions.md#canceling): - 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_id` (string): The session. - `type` (string): Always `cancel`. - `subscription_id` (string): The subscription. - `customer_id` (string): Its customer. - `metadata` (object): The metadata you passed when you created the session. - `completed_at` (timestamp): When the customer confirmed. - `cancel_at` (timestamp, nullable): When the subscription ends. Null when it ended right away. - `immediate` (boolean): `true` when the subscription ended right away. **session.completed data** ```json { "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](https://abuna.app/docs/api/sessions.md#create-portal). 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_id` (string): The session. - `type` (string): Always `portal`. - `subscription_id` (string): The subscription. - `customer_id` (string): Its customer. - `metadata` (object): The metadata you passed when you created the session. - `completed_at` (timestamp): When the customer first opened the portal. **session.completed data** ```json { "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`.