BillStack Docs

Migration Overview

Why and how to migrate from a direct Stripe integration to BillStack

Why Migrate?

If your SaaS application currently integrates with Stripe directly, migrating to BillStack gives you:

Before (Direct Stripe)

// Every SaaS app has its own Stripe setup
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// Webhooks go everywhere — no project isolation
app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, sig, secret);
  // Is this for SaaS-1 or SaaS-2? Who knows...
});

// Customers are global — no project scoping
const customer = await stripe.customers.create({
  email: 'user@example.com',
});

// You build checkout, portal, subscription management from scratch
// For every. single. product.

After (BillStack)

// One API, project-scoped, API key authenticated
const res = await fetch(
  `${BILLSTACK_URL}/api/billstack/teams/${TEAM}/projects/${PROJECT}/customers`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email: 'user@example.com' }),
  }
);

// Webhooks are routed automatically per project
// Customer portal is self-hosted and ready to use
// Analytics dashboard is built in

What You Get

CapabilityDirect StripeWith BillStack
Customer isolationManual (metadata)Automatic per-project
Webhook routingBuild it yourselfBuilt-in per-team URLs
Customer portalStripe Customer Portal or DIYSelf-hosted at /portal/[token]
Subscription analyticsThird-party toolsBuilt-in dashboard
Multi-product billingManual managementProject-based isolation
API key auth for SaaS appsN/Abs_ prefixed keys with scopes
Referral trackingBuild it yourselfBuilt-in per-project

Prerequisites

Before starting the migration, ensure you have:

  • A running BillStack instance (self-hosted or managed)
  • A team created in BillStack (maps to your organization)
  • A project created for each SaaS product you want to manage
  • Your existing Stripe secret key, publishable key, and webhook secret
  • Access to your Stripe Dashboard to update webhook URLs

Migration Steps

The migration is a 7-step process. Each step is independent — you can migrate incrementally:

StepWhatTime
1. Connect StripeLink your Stripe account to BillStack5 min
2. Create API KeysGenerate keys for your SaaS apps5 min
3. Backfill DataSync existing products, customers, subscriptions10 min
4. Replace Stripe CallsSwap Stripe SDK calls with BillStack API30-60 min
5. Update WebhooksPoint Stripe webhooks to BillStack10 min
6. Customer PortalReplace Stripe Customer Portal15 min
7. Referrals(Optional) Set up referral program10 min

Rollback Strategy

BillStack doesn't modify your Stripe data in destructive ways. You can roll back at any time by:

  1. Pointing your webhook URL back to your original endpoint
  2. Reverting your code to use the Stripe SDK directly
  3. Your Stripe customers, products, and subscriptions remain unchanged

On this page