Skip to content
ABUNA
DocsSessions

Guides

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.

View as Markdown

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.

ActionSend with itTypeCompletes whenExpiresEvents to rely on
Sell one price to a new subscriberprice_idcheckoutThe 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 invoiceinvoice_idpaymentThat 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 pricesubscription_id, price_idplan_changeThe 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 cancelsubscription_idcancelThe 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 appsubscription_id, return_urlportalThe 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 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 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"}
  }'
Response
{
  "id": "A4kN1oSs",
  "type": "checkout",
  "status": "open",
  "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": null,
  "price_id": "Zt6YbN3q",
  "subscription_id": null,
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": "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 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.

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

Redirect from your server
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, 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 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 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
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
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
{
  "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, now active after payment or trialing during a free trial.

Check the X-Abuna-Signature header before you trust the payload. Receiving webhooks explains the scheme, and the example below uses it.

Handle session.completed
import crypto from "node:crypto";
import http from "node:http";

// header is "t=1727600000,v1=<hex>", 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 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
{
  "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
    }
  }
}

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.

To find the invoice, list invoices 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 https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "invoice_id": "V2nC8xEi",
    "success_url": "https://example.com/billing/paid",
    "cancel_url": "https://example.com/billing",
    "metadata": {"user_id": "42"}
  }'
Response
{
  "id": "z8TmY5Pq",
  "type": "payment",
  "status": "open",
  "url": "https://app.abuna.app/pay/3a8d1f6c9e2b5a7d0f4c8e1b6a9d3f7c2e5b",
  "success_url": "https://example.com/billing/paid",
  "cancel_url": "https://example.com/billing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": "V2nC8xEi",
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "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
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
{
  "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
// 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 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. The price must be one of the subscription's 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 https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "plan_change",
    "subscription_id": "x9QbL2sK",
    "price_id": "Hc8LmV2s",
    "success_url": "https://example.com/plan/changed",
    "cancel_url": "https://example.com/plan",
    "metadata": {"user_id": "42"}
  }'
Response
{
  "id": "G2wP6hCs",
  "type": "plan_change",
  "status": "open",
  "url": "https://app.abuna.app/plan-change/5d2b8e1f4a7c0d3e6b9f2a5c8e1d4b7a0f3c",
  "success_url": "https://example.com/plan/changed",
  "cancel_url": "https://example.com/plan",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": "Hc8LmV2s",
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": "q2WkR5oF",
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "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
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
{
  "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
// 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 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 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, 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 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"}
  }'
Response
{
  "id": "n9RcL3Xu",
  "type": "cancel",
  "status": "open",
  "url": "https://app.abuna.app/cancel/9e4b7a1d3f6c0e8b2d5a9f1c4e7b0d3a6f2c",
  "success_url": "https://example.com/account/canceled",
  "cancel_url": "https://example.com/account",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": true,
  "updates_channel": null,
  "upgrade_timing": null,
  "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:

  • 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
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
{
  "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
// 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 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 https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "portal",
    "subscription_id": "x9QbL2sK",
    "return_url": "https://example.com/account",
    "metadata": {"user_id": "42"}
  }'
Response
{
  "id": "D1vT7rQf",
  "type": "portal",
  "status": "open",
  "url": "https://app.abuna.app/portal/2c7f0a3d6b9e1c4f8a2d5b7e0c3f6a9d1b4e",
  "success_url": null,
  "cancel_url": null,
  "return_url": "https://example.com/account",
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "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
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
{
  "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
// 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 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.

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.

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, plan change, cancel, and portal 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 -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \
  -H "Authorization: Bearer sk_test_..."

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 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 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"}
  }'
Retry with the same key
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 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 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.

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 to receive events.

Next steps