# Add a subscription checkout to a SaaS

> Add recurring subscription checkout to your SaaS using @vibiz/app or direct API calls with hosted checkout links, webhooks, and billing portals.

**To add subscription payments to a SaaS, create a recurring product in your catalog, generate a hosted checkout URL tied to your customer's user id, and verify the subscription using webhooks or `@vibiz/app`.** thelastapi serves as the merchant of record, so you can bill recurring plans immediately without registering an external merchant account or managing processor secrets. Your application receives events when payments clear, and you can check user access status with a single server-side method.

This guide walks through creating recurring plans, redirecting users to checkout, listening for billing webhooks, and letting subscribers manage their billing.

## How subscriptions work without setting up a processor

When you run a SaaS, setting up recurring billing often involves separate merchant applications, complex key rotation, and weeks of compliance verification. With thelastapi, your project can take card payments—both one-time and recurring—the moment the project is created. thelastapi acts as the merchant, appearing on buyer statements as `VIBIZ, INC* <APP>`. 

Because you do not need your own payment processing account before selling, you can build and launch immediately. If you want to review the full settlement flow, read our guide on how to [take payments online without opening a merchant account](https://thelastapi.dev/blog/take-payments-without-merchant-account) and the reference on [Payments: how money moves](https://thelastapi.dev/docs/guides/payments).

The payment lifecycle runs in three simple steps:
1. You define recurring products (such as a monthly or yearly tier) with a unique `lookup_key`.
2. When a logged-in user clicks "Upgrade," your backend generates a secure, hosted checkout URL for that user and redirects them.
3. Once the buyer completes checkout, thelastapi manages recurring renewals, notifies your application via webhooks, and updates subscription state.

## Step 1: Define your recurring subscription product

Product catalogs are separated by environment: `development` for local testing and `production` for real card charges. You can define products using the `vibiz` CLI or via HTTP.

To add a $15 per month "Pro" plan in development with the CLI:

```bash
vibiz payments products add Pro --amount 1500 --interval month --lookup-key pro-monthly --dev
```

You can do the exact same thing using the HTTP API:

```bash
curl https://thelastapi.dev/v1/projects/$PROJECT/payments/products?env=development \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "price": {
      "unit_amount_cents": 1500,
      "type": "recurring",
      "interval": "month",
      "lookup_key": "pro-monthly"
    }
  }'
```

When you are ready to launch, run the same command without `--dev` (or pass `env=production` in the HTTP query) to add the product to your live catalog.

If you charge international customers, recurring prices can be created in 35 supported currencies (including `eur`, `gbp`, `cad`, `aud`, and `jpy`). Subscriptions always bill in the price's currency, amounts are supplied in the currency's smallest unit (such as cents or whole yen), and an individual buyer cannot hold subscriptions in two different currencies simultaneously.

## Step 2: Create a checkout session on upgrade

Never send card details directly to your server. When a customer chooses a plan, create a checkout session on the server and redirect the user to the hosted checkout page. The checkout URL is meant for a single buyer and expires after 1 hour.

Install the helper library:

```bash
npm install @vibiz/app
```

In a Next.js server action or server-side API handler, call `vibiz.payments.checkout`. The library automatically reads `VIBIZ_APP_KEY` from your environment.

```ts
'use server';

import { redirect } from 'next/navigation';
import { vibiz } from '@vibiz/app';

export async function upgradeToPro(userId: string) {
  const { url } = await vibiz.payments.checkout({
    lookup_key: 'pro-monthly',
    user: userId, // Your internal user ID
    success_url: 'https://app.example.com/billing/success',
    cancel_url: 'https://app.example.com/pricing',
    metadata: {
      account_tier: 'pro',
    },
  });

  redirect(url);
}
```

If you prefer using direct HTTP requests instead of installing `@vibiz/app`, send a POST request from your server:

```bash
curl https://thelastapi.dev/v1/app/payments/checkout \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lookup_key": "pro-monthly",
    "user": "u_123",
    "success_url": "https://app.example.com/billing/success",
    "cancel_url": "https://app.example.com/pricing"
  }'
```

For more details on server parameters and checkout customization, see the documentation on [Payments in the app (@vibiz/app)](https://thelastapi.dev/docs/guides/app-payments). If your app sells single items instead of subscriptions, see how to [sell a one-time product with a hosted checkout link](https://thelastapi.dev/blog/sell-one-time-product-checkout-link).

## Step 3: Handle webhooks and provision access

Once your customer submits their payment details on the hosted page, thelastapi updates the ledger and emits webhook events.

By default on thelastapi hosting, live webhooks point directly to `https://<the app's site>/api/vibiz/webhook`. In development, you can point webhooks to your local machine:

```bash
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev
```

Webhook payloads are cryptographically signed. In your route handler, verify the raw incoming request using `vibiz.webhooks.receive(req)`. Because retries can happen if your endpoint does not respond with a 2xx status code within 10 seconds, make sure to deduplicate incoming events using `event.id`.

```ts
// app/api/vibiz/webhook/route.ts
import { vibiz } from '@vibiz/app';

export async function POST(req: Request) {
  let event;
  try {
    // Verifies signature using VIBIZ_APP_KEY automatically
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  switch (event.type) {
    case 'subscription.created':
    case 'subscription.updated': {
      const subscription = event.data.object;
      // Grant or update user access based on subscription.user and subscription.status
      break;
    }
    case 'subscription.canceled': {
      const subscription = event.data.object;
      // Revoke access or downgrade account
      break;
    }
    case 'invoice.payment_failed': {
      // Handle failed recurring renewal attempt
      break;
    }
  }

  return new Response('ok');
}
```

Check the guide to [Webhooks: thelastapi tells the app when someone pays](https://thelastapi.dev/docs/guides/webhooks) for signature validation details and failure retry schedules.

## Step 4: Verify subscription access in real time

In addition to handling asynchronous webhooks, you can check whether a user holds an active subscription directly inside your server-rendered pages, API routes, or middleware:

```ts
import { vibiz } from '@vibiz/app';

// Returns true if the user has an active or trialing subscription for this plan
const isPro = await vibiz.payments.hasActive(user.id, 'pro-monthly');

// Or inspect the full subscription details:
const sub = await vibiz.payments.subscription(user.id);
// sub: { id, status, price_id, current_period_end, cancel_at_period_end } | null
```

If you do not specify a lookup key in `hasActive(user.id)`, it returns true if the user has an active subscription to *any* plan in your catalog.

## Step 5: Let subscribers manage or cancel plans

SaaS applications must give users a way to update their card details, view billing periods, or cancel. You do not need to build custom billing forms for this. Generate a customer portal link with `@vibiz/app`:

```ts
import { vibiz } from '@vibiz/app';

export async function getBillingPortalUrl(userId: string) {
  const { url } = await vibiz.payments.portal(userId, {
    return_url: 'https://app.example.com/settings/billing',
  });
  return url;
}
```

When users visit this URL, they can update their payment method or cancel their recurring plan. When a cancellation occurs, thelastapi updates the subscription record and emits a `subscription.canceled` webhook event to your endpoint.

## Processing fees, hold periods, and payouts

Before launching live subscriptions, review how pricing, holds, and withdrawals function on the platform:

| Item | Details |
| --- | --- |
| Card processing fee | 2.9% + 30¢ per payment for most US cards |
| Platform fee | 2% (200 bps) |
| Dispute fee | $15 fee (taken on dispute opening; returned if won) |
| Available hold | Live payments remain pending for 7 days, then move to available balance |
| Development hold | No hold period in development |
| Withdrawals | No fee from thelastapi to transfer available balance to your bank |

On a $100 payment under standard defaults, processing fees take $3.20 and the platform fee takes $2.00, leaving a net of $94.80 added to your project's balance.

When you are ready to withdraw funds to your bank account:
1. Complete the one-time **Get paid** verification in the console under project ▸ Payments ▸ Get paid to add your identity and bank details. Payouts are supported in the US, Canada, UK, EEA, and Switzerland.
2. Run `vibiz payments withdraw` or click Withdraw in the dashboard to transfer your available balance.

To see how subscriptions fit alongside the rest of your architecture—such as auth, hosting, and databases—read our full breakdown on how to [build a SaaS in a weekend: database, sign-in, payments, email, deploy](https://thelastapi.dev/blog/build-saas-weekend). For complete API route lists, consult the main [Payments](https://thelastapi.dev/docs/payments) documentation.

To add recurring billing to your project today, run `vibiz payments products add` in your terminal and generate your first checkout session in development mode.

## Frequently asked questions

### How long are subscription checkout links valid?

Hosted checkout links expire after 1 hour and are designed for a single customer to complete checkout. Generate a fresh link on each upgrade click rather than storing static URLs.

### How do I test subscription checkouts without using real money?

Create your products and run checkouts in development mode by passing `--dev` in the CLI or `env=development` via API. You can use standard test card numbers such as 4242 4242 4242 4242 with any future expiration date and CVC, and test payments carry no 7-day hold.

### Can an AI agent or Limited API key issue refunds or withdraw money?

No. In production, sensitive money-moving operations such as live refunds, subscription cancellations, and bank withdrawals are restricted to full-access keys or the project owner in the console (`403 owner_only`). Limited keys may only execute these actions in development mode.

---

Published 2026-11-15 · https://thelastapi.dev/blog/subscription-checkout-saas
