# Sessions > Send a customer from your app to subscribe, pay, change plan or cancel, bring them back, and know for sure when they're done. Source: https://abuna.app/docs/guides/sessions Sessions let your server send one customer to an Abuna page to subscribe, pay, change plan, cancel or manage their subscription. The customer comes back to your site, and Abuna sends your server a webhook. It carries your own `metadata`, so you know which customer it was. ## Actions and session types Every customer action uses one endpoint, `POST /v1/apps/{appID}/sessions`. The `type` you send picks the action. Every type returns the same session object and sends the same `session.completed` and `session.expired` events, with the session's `type` in them. | Action | Send with it | Type | Completes when | Expires | Events to rely on | | --- | --- | --- | --- | --- | --- | | [Sell one price to a new subscriber](https://abuna.app/docs/guides/sessions.md#create-a-session) | `price_id` | `checkout` | The first payment succeeds, a free trial starts, or a returning customer's plan switch is done. | 24 hours after creation, or when a switch offer ends. | `session.completed`, and `subscription.paid` for a late payment. | | [Have a customer pay one open invoice](https://abuna.app/docs/guides/sessions.md#payment) | `invoice_id` | `payment` | That invoice is paid through the session. | 24 hours, or sooner if the invoice can no longer be paid through it. | `invoice.paid` | | [Have a customer confirm a move to another price](https://abuna.app/docs/guides/sessions.md#plan-change) | `subscription_id`, `price_id` | `plan_change` | The change is confirmed, and paid if it costs anything. | 7 days, or the end of the current period if sooner. | `subscription.updated` | | [Have a customer confirm a cancel](https://abuna.app/docs/guides/sessions.md#cancel) | `subscription_id` | `cancel` | The customer confirms. | 24 hours after creation. | `subscription.updated` for a scheduled cancel, `subscription.canceled` when it ends. | | [Send a customer to manage their subscription, with a link back to your app](https://abuna.app/docs/guides/sessions.md#portal) | `subscription_id`, `return_url` | `portal` | The customer first opens it. | 1 hour after creation, if not opened. | The events for what the customer does in the portal. | Check `data.type` in your webhook handler, so each type reaches the right code. ## How it works 1. Your server creates a session of the action's type with your secret key and gets back a session with a `url`. 2. You redirect the customer to that `url`. 3. The customer acts on the page: they subscribe, pay an invoice, confirm a plan change or a cancel, or manage their subscription in the customer portal. 4. Abuna links the customer back to your success URL, or your return URL for a portal session. 5. Abuna sends `session.completed` to your webhook URL. You act on it when it arrives. The next sections walk through starting a subscription. The other actions follow the same steps. ## Start a subscription from your server Create the session from your server with your secret key, in the `Authorization` header. Never call this from a browser or a mobile app. A publishable key or a dashboard sign-in can't create a session: both get `403` with code `forbidden`. Call [Create a checkout session](https://abuna.app/docs/api/sessions.md#create-checkout) with `type` `checkout` and the `price_id` to sell. Put your own user ID in `metadata`, and Abuna copies it onto the subscription. Subscription events carry the subscription's metadata. Session events carry the metadata passed on that session, so pass it again each time you create a session. **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": "checkout", "price_id": "Zt6YbN3q", "customer": {"email": "ana@example.com"}, "success_url": "https://example.com/welcome", "cancel_url": "https://example.com/pricing", "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: "checkout", price_id: "Zt6YbN3q", customer: { email: "ana@example.com" }, success_url: "https://example.com/welcome", cancel_url: "https://example.com/pricing", 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": "checkout", "price_id": "Zt6YbN3q", "customer": {"email": "ana@example.com"}, "success_url": "https://example.com/welcome", "cancel_url": "https://example.com/pricing", "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" => "checkout", "price_id" => "Zt6YbN3q", "customer" => ["email" => "ana@example.com"], "success_url" => "https://example.com/welcome", "cancel_url" => "https://example.com/pricing", "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", "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": "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": "ask", "upgrade_timing": "now", "expires_at": 1727686400, "completed_at": null, "created_at": 1727600000 } ``` The response has status `201` and a `checkout` session. The session is `open` and expires 24 hours after it was created, at `expires_at`. [Create a checkout session](https://abuna.app/docs/api/sessions.md#create-checkout) lists every parameter and error. ### Prefill the customer If you already know who is paying, tell Abuna, and the customer doesn't type it again. Send one of these, not both: - `customer_id`: an existing customer in the app. The checkout uses their name and email, and the payment step uses their phone number if they have one. - `customer`: any of `email`, `name`, and `phone_number`. Write the phone number with its country code, like `+237671234567`. The payment step sends the payment request to it, and the customer can choose another number there. The checkout shows a prefilled email and name locked, so the customer can't change them. They fill in the rest. A customer needs only an email address to start. The payment step asks for the phone number, so a new customer's `phone_number` is `null` until they pay. Their first payment saves the number that paid and sends [`customer.updated`](https://abuna.app/docs/api/events.md#customer-updated). ## Send the customer to the session Redirect the customer's browser to the session's `url`. Create a new session each time a customer starts a checkout. The `url` belongs to one customer, so don't post it anywhere public. For a link anyone can use, use a [checkout link](https://abuna.app/docs/quickstart.md#use-a-checkout-link) instead. **Redirect from your server** ```javascript import http from "node:http"; http .createServer(async (req, res) => { if (req.method === "POST" && req.url === "/subscribe") { const user = await currentUser(req); const session = await createCheckoutSession(user); // the request above res.writeHead(303, { Location: session.url }).end(); return; } res.writeHead(404).end(); }) .listen(3000); ``` Without a trial, the customer enters their email. Abuna creates the customer and a `pending` subscription, sets the session's `customer_id` and `subscription_id`, and shows the pay step on the same page. There the customer enters the phone number they pay from. Once the first payment succeeds, the subscription becomes `active` and the session becomes `completed`, in the same step. With an eligible [free trial](https://abuna.app/docs/guides/trials.md), the customer confirms their details and consent without paying. No phone number is asked: the first renewal's pay link asks for it. The subscription starts `trialing` and the session completes. The customer can then choose reminders, and goes on to your success URL. Opening the `url` again shows where the customer left off. It never creates a second subscription. ### A customer who already subscribes A customer can come back with the email they already subscribe with. The checkout then works from their subscription to the same product instead of starting a second one. Only the email counts, never the phone number. - For an unpaid first payment of the same price, it takes them back to it. - For a price they already pay for, it refuses with `409` `already_subscribed`. - For another price of the same product, it emails them a link to switch their plan. Nothing changes until they confirm from that link. An unpaid subscription to another price stays as it is, beside the new one. [Returning customers](https://abuna.app/docs/api/sessions.md#returning-customers) lists every case. Send `upgrade_timing` to choose when a switch to a higher price takes effect. `now`, the default, charges the difference and switches once it is paid. `next_renewal` charges nothing now and switches at the next renewal. A switch to a lower price always waits for the end of the paid period. ## Handle the return Checkout, payment, and paid upgrades show a "Back to" button after payment. Cancel sessions and plan changes with no payment due return straight to your success URL. Portal sessions show a "Back to" link for your return URL. After the payment goes through, the customer sees a done screen that says where their [reminders](https://abuna.app/docs/guides/customer-notifications.md#reminder-channel) go, with a link back to your success URL. Abuna picks the URL in this order: 1. The `success_url` you passed when you created the session. 2. Your app's **Success URL**, under **Settings**, **General**, **Redirect URLs**. Abuna copies it onto the session when you create it, so changing the setting later doesn't change existing sessions. 3. With neither, the customer stays on Abuna's done screen. Abuna adds the session and subscription IDs to the success URL in one of two ways: - If the URL contains `{SESSION_ID}` or `{SUBSCRIPTION_ID}`, Abuna replaces each one with the ID. - Otherwise, Abuna adds `session_id` and `subscription_id` query parameters. It keeps your own query parameters and the `#` fragment. **Success URLs and where the customer lands** ```bash https://example.com/welcome/{SESSION_ID} https://example.com/welcome/A4kN1oSs https://example.com/welcome?plan=pro#start https://example.com/welcome?plan=pro&session_id=A4kN1oSs&subscription_id=x9QbL2sK#start ``` The cancel URL works the same way: the `cancel_url` you passed, or your app's **Cancel URL**. The checkout links to it for a customer who leaves before paying, and from the page of an expired session. Abuna adds nothing to it. On your success page, you can read the session with `GET /v1/apps/{appID}/sessions/{id}` to show the right message. **Your success page** ```javascript const url = new URL(req.url, "https://example.com"); const sessionId = url.searchParams.get("session_id"); const response = await fetch( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/" + encodeURIComponent(sessionId), { headers: { Authorization: "Bearer sk_test_..." } }, ); const session = await response.json(); // The ID came from the URL, so check the session is this user's. if (!response.ok || session.metadata.user_id !== String(user.id)) { return showPage("pricing"); } if (session.status === "completed") { return showPage("welcome"); } // Paid but not confirmed yet, or a mobile money approval still pending. return showPage("confirming-your-payment"); ``` ## Grant access on the webhook, not the redirect Anyone can type your success URL into a browser, and a customer can close the tab before they get there. Grant access when `session.completed` reaches your webhook URL. Abuna sends it once the first payment succeeds or the trial starts, whether or not the customer came back. **session.completed webhook body** ```json { "id": "01J9ZQ8E1F2G3H4J5K6M7N8P9Q", "type": "session.completed", "environment": "test", "created_at": 1727600600, "data": { "session_id": "A4kN1oSs", "type": "checkout", "subscription_id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "metadata": { "user_id": "42" }, "completed_at": 1727600600, "updates": { "channel": null, "email": { "status": "active" }, "telegram": { "status": "off", "connected_at": null, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } }, "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 } } } ``` `data.metadata` is what you passed when you created the session. `data.subscription_id` and `data.customer_id` are the subscription and customer Abuna created. Store them with your own user record. `data.subscription` is the whole [subscription](https://abuna.app/docs/api/subscriptions.md#object), now `active` after payment or `trialing` during a free trial. Check the `X-Abuna-Signature` header before you trust the payload. [Receiving webhooks](https://abuna.app/docs/guides/webhooks.md#verify-the-signature) explains the scheme, and the example below uses it. **Handle session.completed** ```javascript import crypto from "node:crypto"; import http from "node:http"; // header is "t=1727600000,v1=", with a second v1 while a secret rotation overlaps. function verifyAbunaSignature(rawBody, header, secret) { const pairs = (header ?? "").split(",").map((part) => part.split("=")); const timestamp = pairs.find(([key]) => key === "t")?.[1] ?? ""; if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const expected = crypto.createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest(); return pairs.some(([key, value]) => { const received = Buffer.from(key === "v1" ? value ?? "" : "", "hex"); return received.length === expected.length && crypto.timingSafeEqual(received, expected); }); } http .createServer((req, res) => { const chunks = []; req.on("data", (chunk) => chunks.push(chunk)); req.on("end", async () => { const rawBody = Buffer.concat(chunks); if (!verifyAbunaSignature(rawBody, req.headers["x-abuna-signature"], process.env.ABUNA_WEBHOOK_SECRET)) { res.writeHead(400).end(); return; } const event = JSON.parse(rawBody); // Grant access before you answer 200: Abuna doesn't send an event again once you have. // A late payment sends subscription.paid without session.completed, so handle both. // grantAccess is keyed on subscription_id, so getting both grants access once. try { const checkout = event.type === "session.completed" && event.data.type === "checkout"; if (!(await alreadyHandled(event.id)) && (checkout || event.type === "subscription.paid")) { const { metadata, subscription_id, customer_id } = event.data; await grantAccess(metadata.user_id, subscription_id, customer_id); } await markHandled(event.id); } catch { res.writeHead(500).end(); return; } res.writeHead(200).end(); }); }) .listen(3000); ``` When a checkout switched a [returning customer's](https://abuna.app/docs/guides/sessions.md#returning-customers) plan, `session.completed` has `data.subscription_id` set to their existing subscription, and adds `plan_offer_id`, `previous_price_id`, `price_id`, `direction`, and `effective_at`. Granting access keyed on `subscription_id` stays correct, since it is a subscription you already know. Change the plan on your side when `subscription.updated` reports `price_changed`, as for any plan change. **session.completed webhook body for a switch** ```json { "id": "01J9ZQ8K1M2N3P4Q5R6S7T8V9W", "type": "session.completed", "environment": "test", "created_at": 1727600900, "data": { "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": 1727600900, "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": 1727600900, "current_period_end": 1730192900, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } } } ``` > **Warning:** Verify the signature on the raw bytes before you parse them, and skip events you've already handled. The same event `id` can arrive more than once. ## Pay an unpaid invoice from your app A `payment` session sends a customer to pay one open invoice, for example from a "Pay now" button on your billing page while the subscription is `past_due`. Create one with `type` `payment` and the invoice's ID in `invoice_id`. See [Create a payment session](https://abuna.app/docs/api/sessions.md#create-payment). To find the invoice, [list invoices](https://abuna.app/docs/api/invoices-and-payments.md#list) with `status=open`, or keep the `invoice_id` from the `invoice.created` event when Abuna issues it. `success_url`, `cancel_url`, and `metadata` are optional, as for a checkout. ### Create the session **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, "expires_at": 1727686400, "completed_at": null, "created_at": 1727600000 } ``` The session's `url` is a pay page for that invoice, and `invoice_id` names it. The invoice must be open. Otherwise you get one of these errors: - `409` `already_paid`: the invoice is already paid. - `409` `invoice_not_open`: the invoice is void, for example because its subscription was canceled. - `422` `invalid` with an `errors` item for `invoice_id`: the app has no invoice with that ID. ### Redirect and handle the return Redirect the customer to the `url`. Once the invoice is paid through the session, the session completes and the customer sees a "Back to" button for your success URL. Abuna replaces `{SESSION_ID}`, `{SUBSCRIPTION_ID}`, and `{INVOICE_ID}` in it. Without placeholders, it adds `session_id`, `subscription_id`, and `invoice_id` query parameters. The cancel URL is the way back for a customer who leaves without paying. **Billing routes on your server** ```javascript http .createServer(async (req, res) => { const url = new URL(req.url, "https://example.com"); const user = await currentUser(req); // The "Pay now" button on your billing page posts here. if (req.method === "POST" && url.pathname === "/billing/pay") { const session = await createPaymentSession(user); // the request above res.writeHead(303, { Location: session.url }).end(); return; } // success_url: Abuna adds session_id, subscription_id, and invoice_id. if (req.method === "GET" && url.pathname === "/billing/paid") { const response = await fetch( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/" + encodeURIComponent(url.searchParams.get("session_id")), { headers: { Authorization: "Bearer sk_test_..." } }, ); const session = await response.json(); if (!response.ok || session.metadata.user_id !== String(user.id)) { return showPage(res, "billing"); } return showPage(res, session.status === "completed" ? "payment-received" : "confirming-your-payment"); } res.writeHead(404).end(); }) .listen(3000); ``` ### Confirm through the webhook **session.completed webhook body** ```json { "id": "01J9ZQ8F1G2H3J4K5M6N7P8Q9R", "type": "session.completed", "environment": "test", "created_at": 1727600600, "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 } } } ``` Use `invoice.paid` to know the invoice is settled. It fires however the customer paid. Use `session.completed` to know the customer finished the payment you sent them to. It carries your `metadata`. **Handle a paid invoice** ```javascript // Inside the verified webhook handler above. if (event.type === "invoice.paid") { // Fires however the invoice was paid: this session, a pay link, or a retry. await markInvoicePaid(event.data.subscription_id, event.data.invoice_id); } if (event.type === "session.completed" && event.data.type === "payment") { // The customer finished the payment you sent them to. await notifyUser(event.data.metadata.user_id, "Thanks, your payment went through."); } ``` ### When a payment session expires A payment session expires after 24 hours, or sooner once its invoice can no longer be paid through it: it was paid another way, it was voided, or the subscription ended. Abuna then sends `session.expired`. A session whose invoice was paid another way expires. It doesn't complete, so don't wait on `session.completed` to settle the invoice. The pay links in Abuna's emails and Telegram or WhatsApp messages keep working on their own. A payment session doesn't change them. ## Add an upgrade button to your app A `plan_change` session sends a customer to confirm a move to another price. Call [Create a plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change) with the subscription's ID in `subscription_id` and the new `price_id`. `success_url`, `cancel_url`, and `metadata` are optional. It follows the [plan change rules](https://abuna.app/docs/api/subscriptions.md#changing-plan). The price must be one of the subscription's [plan options](https://abuna.app/docs/api/subscriptions.md#list-plan-options), or you get `422` `price_not_eligible`. The subscription must be `active` or `past_due`, or you get `409` `plan_change_unavailable`. An unknown subscription gets `422` `invalid` with an `errors` item for `subscription_id`. The session replaces any pending offer or `plan_change` session, and the older session gets `session.expired`. Abuna sends `plan_offer.created`, but doesn't email or message the customer: you redirect them. ### Create the session **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, "expires_at": 1728204800, "completed_at": null, "created_at": 1727600000 } ``` The `url` is the confirm page. It shows the current plan, the new one, and what the change costs now. `price_id` is the new price, and `plan_offer_id` is the offer behind the session. ### Redirect and handle the return Redirect the customer to the `url`. The customer reaches your success URL only once the change is done: - **Upgrade**: after payment, the customer can choose "Back to" to return to your site. An upgrade that costs `0` returns them directly when they confirm. - **Downgrade**: when they confirm. It is scheduled for the end of the paid period, and the customer keeps the current plan until then. Your cancel URL is the "Back to" link on the confirm and pay steps. **Plan routes on your server** ```javascript http .createServer(async (req, res) => { const url = new URL(req.url, "https://example.com"); const user = await currentUser(req); // The "Upgrade" button posts here. if (req.method === "POST" && url.pathname === "/plan/upgrade") { const session = await createPlanChangeSession(user); // the request above res.writeHead(303, { Location: session.url }).end(); return; } // success_url: the customer confirmed, and paid if the upgrade cost anything. if (req.method === "GET" && url.pathname === "/plan/changed") { return showPage(res, "plan-changed"); } // cancel_url: the "Back to" link on the confirm and pay steps. if (req.method === "GET" && url.pathname === "/plan") { return showPage(res, "plans"); } res.writeHead(404).end(); }) .listen(3000); ``` ### Confirm through the webhook **session.completed webhook body** ```json { "id": "01J9ZQ8G1H2J3K4M5N6P7Q8R9S", "type": "session.completed", "environment": "test", "created_at": 1727600900, "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 } } } ``` `direction` is `upgrade` or `downgrade`. `effective_at` is when the new price starts: now for an upgrade, the end of the paid period for a downgrade. `plan_offer.*`, `subscription.updated`, and `invoice.*` events still fire as for any plan change. Rely on two of them: - `session.completed` to know the customer finished the flow you started. It carries your `metadata`. - `subscription.updated` to know the price changed. For a downgrade, that comes at the end of the period, after the session completes. **Handle a plan change** ```javascript // Inside the verified webhook handler above. if (event.type === "session.completed" && event.data.type === "plan_change") { // The customer finished the flow. A downgrade starts later, at effective_at. const { metadata, direction, effective_at } = event.data; await notifyUser(metadata.user_id, direction === "upgrade" ? "You're on the new plan." : "Your plan changes on " + new Date(effective_at * 1000).toDateString()); } if (event.type === "subscription.updated" && event.data.change?.type === "price_changed") { // The price actually changed: switch the features on your side now. await setPlan(event.data.subscription_id, event.data.change.new_price_id); } ``` ### When a plan change session expires A plan change session lasts 7 days, or until the end of the current period if that comes first. It also expires, with `session.expired`, when its offer is replaced, canceled, or expires, or when an upgrade it started goes unpaid and lapses. An upgrade the customer confirmed but hasn't paid yet keeps the session open until it is paid or lapses. ## Add a cancel button to your app A `cancel` session sends a customer to confirm a cancel. Call [Create a cancel session](https://abuna.app/docs/api/sessions.md#create-cancel) with the subscription's ID in `subscription_id`. `success_url`, `cancel_url`, and `metadata` are optional, as for a checkout. To cancel without asking the customer, use [Cancel a subscription](https://abuna.app/docs/api/subscriptions.md#cancel) instead. `at_period_end` is optional too. Send `true` to end the subscription at the end of the paid period, or `false` to end it right away. Leave it out and your app's **When customers cancel** setting, [`customer_cancel`](https://abuna.app/docs/api/apps.md#object), decides. The setting applies as it stands when you create the session, and the session's `at_period_end` always holds the result. ### Create the session **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", "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", 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", "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", "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", "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, "expires_at": 1727686400, "completed_at": null, "created_at": 1727600000 } ``` The subscription must be `active` or `past_due`, and not already scheduled to cancel. Otherwise you get one of these errors: - `409` `subscription_canceled`: the subscription has already ended. - `409` `subscription_not_active`: the subscription is `pending`: its first period isn't paid yet. To let the customer drop it, send them to the customer portal instead, where Cancel ends it right away. - `409` `cancel_already_scheduled`: a cancel is already scheduled for the end of the period. - `422` `invalid` with an `errors` item for `subscription_id`: the app has no subscription with that ID. ### Redirect and handle the return Redirect the customer to the `url`. The page shows what will happen and the end date, with a Confirm button and a "Back to" link to your cancel URL. What happens follows the [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. - **Unpaid period**: 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. - **Right away**: the subscription ends now, and its open invoices are voided. The session completes when the customer confirms, whether the cancel is scheduled or immediate. Abuna then sends them to your success URL, with `{SESSION_ID}` and `{SUBSCRIPTION_ID}` filled in, or `session_id` and `subscription_id` added, as for the other types. **Account routes on your server** ```javascript http .createServer(async (req, res) => { const url = new URL(req.url, "https://example.com"); const user = await currentUser(req); // The "Cancel subscription" button posts here. if (req.method === "POST" && url.pathname === "/account/cancel") { const session = await createCancelSession(user); // the request above res.writeHead(303, { Location: session.url }).end(); return; } // success_url: the customer confirmed. Abuna adds session_id and subscription_id. if (req.method === "GET" && url.pathname === "/account/canceled") { return showPage(res, "sorry-to-see-you-go"); } // cancel_url: the "Back to" link. The customer changed their mind. if (req.method === "GET" && url.pathname === "/account") { return showPage(res, "account"); } res.writeHead(404).end(); }) .listen(3000); ``` ### Confirm through the webhook **session.completed webhook body** ```json { "id": "01J9ZQ8H1J2K3M4N5P6Q7R8S9T", "type": "session.completed", "environment": "test", "created_at": 1727600300, "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 } } } ``` `immediate` is `true` when the subscription ended right away. `cancel_at` is when a scheduled cancel ends the subscription, and `null` when it ended right away. `subscription.updated` (a scheduled cancel) or `subscription.canceled` (an immediate one) still fire, as for any cancel. Rely on two events: - `session.completed` to know the customer confirmed the cancel you sent them to. It carries your `metadata`. - `subscription.canceled` to remove access. For a scheduled cancel, it comes later, at `cancel_at`. **Handle a cancel** ```javascript // Inside the verified webhook handler above. if (event.type === "session.completed" && event.data.type === "cancel") { // The customer confirmed. Access ends on subscription.canceled, not here. const { metadata, immediate, cancel_at } = event.data; await notifyUser(metadata.user_id, immediate ? "Your subscription has ended." : "Your subscription ends on " + new Date(cancel_at * 1000).toDateString()); } if (event.type === "subscription.canceled") { // Right away for an immediate cancel. At cancel_at for a scheduled one. await revokeAccess(event.data.subscription_id); } ``` ### When a cancel session expires A cancel session the customer doesn't confirm expires 24 hours after creation, and Abuna sends `session.expired`. The subscription doesn't change. ## Add a Manage billing link to your app A `portal` session sends a customer to the customer portal for one subscription, with a link back to your app. There they can change plan, pay, cancel, choose where reminders go, and update their contact details. Call [Create a portal session](https://abuna.app/docs/api/sessions.md#create-portal) with the subscription's ID in `subscription_id` and a `return_url`. `metadata` is optional. The subscription can have any status, including `pending` and `canceled`. `success_url` and `cancel_url` don't apply to a portal session. Sending either returns `400` with code `invalid_json`. `return_url` follows the same URL rules as the other two. ### Create the session **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, "expires_at": 1727603600, "completed_at": null, "created_at": 1727600000 } ``` The `url` is the customer portal, with a "Back to" link to your `return_url` at the top. An unknown subscription returns `422` with code `invalid` and an `errors` item for `subscription_id`. ### Redirect and let the customer come back Create a new session each time the customer clicks your "Manage billing" button, and redirect them to its `url` right away. The `url` must be opened within 1 hour of creation. After that, it shows an invalid link. Once opened, it keeps working like the customer portal does. The "Back to" link stays while the customer moves around the portal: changing plan, choosing where reminders go, updating contact details, and paying. On the pay page, the back and done links return to your `return_url`, and "Manage subscription" returns to the portal. Each of these links is your `return_url` exactly as you sent it: Abuna adds no query parameters or IDs. Put what your page needs in the URL when you create the session. What the customer sees depends on the subscription's status: - **`pending`**: the first invoice with its pay-by date and a Pay button, and a Cancel button that ends the subscription right away. No plan change. - **`active` or `past_due`**: the plan, invoices, contact details, a Cancel button, and the prices they 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 their contact details, which they can still update. Nothing to pay, and no plan change or cancel. **Billing routes on your server** ```javascript http .createServer(async (req, res) => { const url = new URL(req.url, "https://example.com"); const user = await currentUser(req); // The "Manage billing" button posts here. Make a new session every time. if (req.method === "POST" && url.pathname === "/account/billing") { const session = await createPortalSession(user); // the request above res.writeHead(303, { Location: session.url }).end(); return; } // return_url: the "Back to" link at the top of the portal. if (req.method === "GET" && url.pathname === "/account") { return showPage(res, "account"); } res.writeHead(404).end(); }) .listen(3000); ``` ### Act on what the customer does **session.completed webhook body** ```json { "id": "01J9ZQ8J1K2M3N4P5Q6R7S8T9V", "type": "session.completed", "environment": "test", "created_at": 1727600020, "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 } } } ``` A portal session completes when the customer first opens it, and `session.completed` fires then. It doesn't mean the customer changed anything. Each thing they do in the portal sends its own event, as it always has: - Change plan: `subscription.updated`, and `invoice.created` and `invoice.paid` for an upgrade with something to pay. - Cancel, or keep a scheduled cancel: `subscription.updated`, then `subscription.canceled` when the subscription ends. - Pay an invoice: `invoice.paid`, or `invoice.payment_failed`. - Update contact details: `customer.updated`. **Handle what happens in the portal** ```javascript // Inside the verified webhook handler above. // A portal session.completed only means the customer opened the portal. // Act on what they did there, from these events. if (event.type === "subscription.updated") { await syncSubscription(event.data.subscription_id, event.data.price_id, event.data.cancel_at); } if (event.type === "subscription.canceled") { await revokeAccess(event.data.subscription_id); } if (event.type === "invoice.paid") { await markInvoicePaid(event.data.subscription_id, event.data.invoice_id); } if (event.type === "customer.updated") { await syncContact(event.data.customer_id, event.data.email, event.data.phone_number); } ``` ### When a portal session expires A portal session nobody opens within 1 hour expires, and Abuna sends `session.expired`. An opened session has already completed, so it never expires. The subscription's [`subscription_page_url`](https://abuna.app/docs/api/subscriptions.md#retrieve) and the portal links in Abuna's emails keep working as before, with no link back to your app. ## Metadata `metadata` is an object of your own keys and values. It can have up to 20 keys. Each key is 1 to 40 characters and each value is a string of up to 500 characters. Metadata outside these limits returns `422` with code `invalid` and an `errors` item for `metadata`. Don't put secrets in it. The subscription a checkout session creates starts with the same `metadata`. Every webhook that carries a `subscription_id`, like `subscription.paid`, `invoice.paid`, or `subscription.canceled`, also carries that subscription's `metadata`. To change it later, [update the subscription](https://abuna.app/docs/api/subscriptions.md#update). ## Expiry A checkout session lasts 24 hours, unless it offered a returning customer a switch: then it lasts as long as the offer, up to 7 days and never past the end of the paid period. See [Switching plan at checkout](https://abuna.app/docs/api/sessions.md#checkout-switch). Within about a minute of `expires_at`, an open session becomes `expired` and Abuna sends `session.expired`. Its page then tells the customer the checkout has expired, with a link to your cancel URL. To start again, create a new session. The other types have their own rules: see [payment](https://abuna.app/docs/guides/sessions.md#payment-expiry), [plan change](https://abuna.app/docs/guides/sessions.md#plan-change-expiry), [cancel](https://abuna.app/docs/guides/sessions.md#cancel-expiry), and [portal](https://abuna.app/docs/guides/sessions.md#portal-expiry) expiry. To expire a session sooner, for example when the customer picks another plan on your site, call `POST /v1/apps/{appID}/sessions/{id}/expire`. **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) ``` A session that is already `completed` or `expired` returns `409` with code `session_not_open`. ### A session completes at most once A session ends in one of two states, `completed` or `expired`, and never changes after that. You get one `session.completed` or one `session.expired` for it, never both. An expired session never completes. ### A customer who leaves during a payment A mobile money payment waits for the customer to approve it on their phone. If they close the page while it waits, nothing is lost: when they approve, the subscription becomes `active` and `session.completed` still arrives. For this, set the webhook URL at your payment provider, as [Connecting a payment provider](https://abuna.app/docs/guides/payment-providers.md#set-the-provider-webhook) explains. A session doesn't expire while its payment is pending, even past `expires_at`. If that payment fails, the session expires afterwards. If you expire a session yourself while its payment is pending and the payment then succeeds, the subscription becomes `active` but the session stays `expired`. ### The subscription of an expired session If the customer filled in their details but didn't pay before the session expired, the `pending` subscription stays, and the customer gets its pay link by email. If they pay it before your app's days to pay run out, the subscription becomes `active`. You then get `subscription.paid` with your `metadata`, but no `session.completed`. If they don't pay, the subscription ends with `subscription.canceled` and reason `checkout_expired`. To catch these late payments, also grant access on `subscription.paid`. Key your grant on `subscription_id`, so getting both events grants access once. ## Retry safely with an idempotency key A network error can hide whether your request created a session. To retry without making a second one, send an `Idempotency-Key` header. Make a new random value once per session you want, and send that same value on every retry. A retry with the same key and body within 24 hours gets the first response again, and no second session is created. **POST /v1/apps/{appID}/sessions with Idempotency-Key** 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", "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", 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", "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", "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", "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) ``` **Retry with the same key** ```javascript import crypto from "node:crypto"; // Make the key once per session you want, and send the same key on every retry. const idempotencyKey = crypto.randomUUID(); async function createSession() { return fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ type: "checkout", price_id: "Zt6YbN3q", metadata: { user_id: "42" } }), }); } let response; for (let attempt = 1; attempt <= 3; attempt++) { try { response = await createSession(); if (response.status < 500 && response.status !== 409) break; } catch { // A network error: retry with the same key. } await new Promise((resolve) => setTimeout(resolve, attempt * 1000)); } ``` [Idempotent requests](https://abuna.app/docs/errors.md#idempotency) lists what each reuse of a key returns. ## Test it in Test mode Use your Test app ID and its `sk_test_` key. The flow is the same as in Live mode, but the pay step moves no money. With the Abuna simulator, the default, pick an outcome on the pay step: - **Successful payment**: the session completes right away. - **Needs approval, then succeeds**: the payment is `pending` first, like a mobile money prompt, and succeeds after about 10 seconds. The page waits for it. - **Declined payment** and **Insufficient balance**: the payment fails and the customer can try again. See [Simulated payments](https://abuna.app/docs/test-and-live-mode.md#simulated-payments) for how each one behaves. If your Test app connected a provider's sandbox, the pay step also offers it under **Test with**. Choose it, and its test numbers decide the outcome. See [Test numbers](https://abuna.app/docs/test-and-live-mode.md#test-numbers). Cancel and portal sessions work the same way in Test mode, on your Test subscriptions. In Test mode, `success_url`, `cancel_url`, and `return_url` can be `http` URLs on `localhost`, `127.0.0.1`, or `[::1]`, so you can come back to your own machine. This also applies to your Test app's default Success URL and Cancel URL, for every session type. Live mode takes only `https` URLs, and any other URL returns `422` with code `invalid` and an `errors` item with code `url_invalid`. Your webhook URL needs a public `https` address in both modes, so [expose your machine through a tunnel](https://abuna.app/docs/guides/webhooks.md#add-an-endpoint) to receive events.