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 inWhat You Get
| Capability | Direct Stripe | With BillStack |
|---|---|---|
| Customer isolation | Manual (metadata) | Automatic per-project |
| Webhook routing | Build it yourself | Built-in per-team URLs |
| Customer portal | Stripe Customer Portal or DIY | Self-hosted at /portal/[token] |
| Subscription analytics | Third-party tools | Built-in dashboard |
| Multi-product billing | Manual management | Project-based isolation |
| API key auth for SaaS apps | N/A | bs_ prefixed keys with scopes |
| Referral tracking | Build it yourself | Built-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:
| Step | What | Time |
|---|---|---|
| 1. Connect Stripe | Link your Stripe account to BillStack | 5 min |
| 2. Create API Keys | Generate keys for your SaaS apps | 5 min |
| 3. Backfill Data | Sync existing products, customers, subscriptions | 10 min |
| 4. Replace Stripe Calls | Swap Stripe SDK calls with BillStack API | 30-60 min |
| 5. Update Webhooks | Point Stripe webhooks to BillStack | 10 min |
| 6. Customer Portal | Replace Stripe Customer Portal | 15 min |
| 7. Referrals | (Optional) Set up referral program | 10 min |
Rollback Strategy
BillStack doesn't modify your Stripe data in destructive ways. You can roll back at any time by:
- Pointing your webhook URL back to your original endpoint
- Reverting your code to use the Stripe SDK directly
- Your Stripe customers, products, and subscriptions remain unchanged