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.
On this page 8 sections
- How subscriptions work without setting up a processor
- Step 1: Define your recurring subscription product
- Step 2: Create a checkout session on upgrade
- Step 3: Handle webhooks and provision access
- Step 4: Verify subscription access in real time
- Step 5: Let subscribers manage or cancel plans
- Processing fees, hold periods, and payouts
- FAQ
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 and the reference on Payments: how money moves.
The payment lifecycle runs in three simple steps:
- You define recurring products (such as a monthly or yearly tier) with a unique
lookup_key. - When a logged-in user clicks "Upgrade," your backend generates a secure, hosted checkout URL for that user and redirects them.
- 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:
vibiz payments products add Pro --amount 1500 --interval month --lookup-key pro-monthly --devYou can do the exact same thing using the HTTP API:
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:
npm install @vibiz/appIn a Next.js server action or server-side API handler, call vibiz.payments.checkout. The library automatically reads VIBIZ_APP_KEY from your environment.
'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:
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). If your app sells single items instead of subscriptions, see how to sell a one-time product with a hosted 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:
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --devWebhook 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.
// 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 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:
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 } | nullIf 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:
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:
- 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.
- Run
vibiz payments withdrawor 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. For complete API route lists, consult the main 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.