Guides/First Checkout

Your First Checkout

Create a plan, generate a checkout session, and subscribe your first customer.

Prerequisites

  • StackBE account with an app created
  • Stripe account connected in StackBE dashboard
  • API key from your app settings

Step 1: Create a Product & Plan

Products group your plans. Most apps have one product with multiple pricing tiers.

In the StackBE dashboard, go to Pricing and create a plan:

  • Name: Pro
  • Price: $29/month
  • Entitlements: { "plan": "pro", "apiCalls": 10000 }

Save the plan and note the planId (e.g., plan_abc123).

Tip: When you create an app, a free plan is created automatically. You can use it for freemium models.

Step 2: Install the SDK

bash
npm install @stackbe/sdk

Initialize the client:

typescript
import { StackBE } from '@stackbe/sdk';

const stackbe = new StackBE({
  apiKey: process.env.STACKBE_API_KEY!,
  appId: process.env.STACKBE_APP_ID!,
});

Step 3: Create a Checkout Session

When a user clicks "Upgrade" or "Subscribe", create a checkout session and redirect them:

typescript
// In your API route or server action
export async function createCheckout(customerId: string) {
  const { url } = await stackbe.checkout.createSession({
    customer: customerId,  // or email: 'user@example.com'
    planId: 'plan_abc123',
    successUrl: 'https://yourapp.com/dashboard?upgraded=true',
    cancelUrl: 'https://yourapp.com/pricing',
  });

  // Redirect the user to Stripe checkout
  return redirect(url);
}

The user completes payment on Stripe's hosted checkout page, then returns to your successUrl.

Step 4: Handle the Result

After successful checkout, the subscription is automatically created. You can verify it:

typescript
// Check the customer's subscription
const subscription = await stackbe.subscriptions.get(customerId);

console.log(subscription.status);  // 'active'
console.log(subscription.planId);  // 'plan_abc123'

// Or check specific entitlements
const { hasAccess } = await stackbe.entitlements.check(
  customerId,
  'apiCalls'
);

if (hasAccess) {
  // Unlock premium features
}

Step 5: Test It

In the StackBE dashboard, use the "Generate Test Checkout Link" button to create a test checkout without writing code. Use Stripe's test card:

text
Card: 4242 4242 4242 4242
Expiry: Any future date
CVC: Any 3 digits

Complete Example

Here's a complete Next.js example with a pricing page:

typescript
// app/api/checkout/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { StackBE } from '@stackbe/sdk';

const stackbe = new StackBE({
  apiKey: process.env.STACKBE_API_KEY!,
  appId: process.env.STACKBE_APP_ID!,
});

export async function POST(req: NextRequest) {
  const { planId, customerId } = await req.json();

  const { url } = await stackbe.checkout.createSession({
    customer: customerId,
    planId,
    successUrl: `${process.env.NEXT_PUBLIC_URL}/dashboard?upgraded=true`,
    cancelUrl: `${process.env.NEXT_PUBLIC_URL}/pricing`,
  });

  return NextResponse.json({ url });
}

// components/UpgradeButton.tsx
'use client';

export function UpgradeButton({ planId, customerId }) {
  const handleUpgrade = async () => {
    const res = await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ planId, customerId }),
    });
    const { url } = await res.json();
    window.location.href = url;
  };

  return (
    <button onClick={handleUpgrade}>
      Upgrade to Pro
    </button>
  );
}

Next Steps