Superkabe LogoSuperkabe

Deployment Checklist

Production deployment steps for Superkabe billing integration and infrastructure

✅ Implementation Status

All code has been written, committed, and pushed to repositories. Ready for deployment.

Backend Complete

  • ✅ Prisma schema with subscription fields
  • ✅ Polar API client service
  • ✅ Billing service & webhook processing
  • ✅ Trial expiration worker (hourly cron)
  • ✅ Feature gate middleware
  • ✅ Capacity checks & usage tracking

Frontend Complete

  • ✅ BillingSection component
  • ✅ Trial countdown banner
  • ✅ Dynamic pricing page CTAs
  • ✅ Authentication-aware routing
  • ✅ Checkout & cancellation flows

🚀 Deployment Steps

STEP 1

Configure Railway Environment Variables

Add these variables to your Railway backend project:

POLAR_ACCESS_TOKEN=polar_oat_...
POLAR_WEBHOOK_SECRET=polar_whs_...
POLAR_STARTER_PRODUCT_ID=f82a3f93-14d5-49c6-b6cf-6bc0d8e6ca6c
POLAR_GROWTH_PRODUCT_ID=0690578b-2fe7-4e05-a2e2-a258a90599e9
POLAR_SCALE_PRODUCT_ID=edae6a6e-bfd2-4f24-9092-197021cf984d
FRONTEND_URL=https://your-frontend-domain.vercel.app

How to add in Railway:

  1. 1. Go to Railway project → Backend service
  2. 2. Click "Variables" tab
  3. 3. Add each variable with its value
  4. 4. Railway will automatically redeploy
STEP 2

Configure Polar Webhook

Webhook endpoint: https://your-backend-domain.railway.app/api/billing/polar-webhook

Setup in Polar Dashboard:

  1. 1. Go to Polar Dashboard → Settings → Webhooks
  2. 2. Click "Add Webhook"
  3. 3. Enter webhook URL above
  4. 4. Select events:
    • • subscription.created
    • • subscription.updated
    • • subscription.canceled
    • • invoice.paid
    • • invoice.payment_failed
  5. 5. Save webhook
STEP 3

Run Database Migration

cd backend
npx prisma migrate deploy
npx prisma generate

This adds subscription fields to Organization table, creates SubscriptionEvent table, and updates usage tracking columns.

STEP 4

Backfill Existing Organizations

Initialize trial status for existing organizations:

cd backend
npx ts-node scripts/backfillSubscriptions.ts

Expected: ✅ Backfilled 5 organizations with trial status

STEP 5

Verify Deployment

1. Check Backend Health:

curl https://your-backend-domain.railway.app/api/health

2. Verify Trial Worker Started:

Check Railway logs for: "Trial expiration worker started (runs hourly)"

3. Test Billing Endpoint:

curl -X GET https://your-backend.railway.app/api/billing/subscription \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

4. Check Frontend:

  • • Visit /dashboard/settings
  • • Verify BillingSection appears with trial status
  • • Check trial countdown banner (if < 7 days)

📋 Feature Verification

Environment variables added to Railway
Polar webhook configured & receiving events
Database migration applied
Backfill script executed successfully
Trial countdown banner appears (< 7 days)
BillingSection displays plan & usage
Pricing page CTAs redirect correctly
Checkout flow completes & webhook processes
Feature gates block at capacity
Trial worker logs appear hourly
Usage counts increment correctly
Subscription upgrades work end-to-end

🐛 Troubleshooting

Webhook Not Receiving Events

  • • Verify webhook URL matches in Polar dashboard
  • • Check webhook secret matches POLAR_WEBHOOK_SECRET
  • • Verify backend deployed & accessible
  • • Check Railway logs for incoming requests

Feature Gates Not Blocking

  • • Verify migration applied (check database schema)
  • • Check current usage counts are accurate
  • • Run refreshUsageCounts endpoint manually
  • • Verify TIER_LIMITS in polarClient.ts

Checkout Not Completing

  • • Verify FRONTEND_URL is set correctly
  • • Check Polar product IDs match dashboard
  • • Ensure Polar access token has permissions
  • • Test with Polar test mode first

🎉 Post-Deployment

Once all checks pass:

  • • Test with a real user signup
  • • Monitor first week for trial expirations
  • • Track conversion rates from trial to paid
  • • Set up alerts for webhook failures
  • • Monitor usage count accuracy

Your billing system is now live! 🚀

📞 Support Resources