tenderpilot/STRIPE_PRICE_SETUP_GUIDE.md

Stripe Price Setup Guide

This guide walks you through creating the three Stripe Price objects for TenderRadar's subscription plans.

Overview

You need to create 3 recurring prices in your Stripe Dashboard:

• Starter: £39/month
• Growth: £99/month
• Pro: £249/month

Each price will generate a unique Price ID that must be added to your .env file.

---

Step-by-Step Instructions

1. Log in to Stripe Dashboard

Visit https://dashboard.stripe.com and sign in with your Stripe account.

Note: Use Test Mode during development (toggle in top-right corner).
Switch to Live Mode when ready for production.

---

2. Navigate to Products

In the left sidebar, click:

• More+ → Product Catalogue → Products
  OR
• Directly visit: https://dashboard.stripe.com/products

---

3. Create Starter Plan (£39/month)

1. Click + Add product (blue button, top-right)
2. Fill in the form:
   • Name: TenderRadar Starter
   • Description (optional): Starter tier with basic features
   • Pricing model: Standard pricing
   • Price: 39.00
   • Currency: GBP (£)
   • Billing period: Monthly
   • Usage is metered: Leave unchecked
3. Click Save product
4. On the product page, you'll see a Pricing section with your new price
5. Click on the price row to expand details
6. Copy the Price ID (starts with price_...) — Example: price_1AbCdEfGhIjKlMnO
7. Save this Price ID for the next step

---

4. Create Growth Plan (£99/month)

Repeat the process:

1. Click + Add product
2. Fill in:
   • Name: TenderRadar Growth
   • Description (optional): Growth tier with advanced features
   • Price: 99.00
   • Currency: GBP (£)
   • Billing period: Monthly
3. Click Save product
4. Copy the Price ID from the new price

---

5. Create Pro Plan (£249/month)

Repeat again:

1. Click + Add product
2. Fill in:
   • Name: TenderRadar Pro
   • Description (optional): Pro tier with unlimited features
   • Price: 249.00
   • Currency: GBP (£)
   • Billing period: Monthly
3. Click Save product
4. Copy the Price ID

---

6. Update Your .env File

Open /home/peter/tenderpilot/.env and replace the placeholder Price IDs:

# Before:
STRIPE_PRICE_STARTER=price_starter_placeholder
STRIPE_PRICE_GROWTH=price_growth_placeholder
STRIPE_PRICE_PRO=price_pro_placeholder

# After (example):
STRIPE_PRICE_STARTER=price_1AbCdEfGhIjKlMnO
STRIPE_PRICE_GROWTH=price_1PqRsTuVwXyZaBcD
STRIPE_PRICE_PRO=price_1EfGhIjKlMnOpQrS

Important: Use the actual Price IDs from your Stripe Dashboard.

---

7. Get Your API Keys

Still in Stripe Dashboard:

1. Click Developers (left sidebar)
2. Click API keys (under Developers)
3. You'll see two keys:
   • Publishable key (starts with pk_test_... in test mode)
   • Secret key (starts with sk_test_... in test mode, click Reveal test key)

Copy both keys and update your .env:

STRIPE_SECRET_KEY=sk_test_YOUR_ACTUAL_SECRET_KEY
STRIPE_PUBLISHABLE_KEY=pk_test_YOUR_ACTUAL_PUBLISHABLE_KEY

Security Warning: Never commit the .env file to version control!
Keep your Secret Key private — it has full access to your Stripe account.

---

8. Set Up Webhook Endpoint

Webhooks allow Stripe to notify your server about subscription events (payments, cancellations, etc.).

Development (Localhost Testing)

Install Stripe CLI:

# Mac/Linux:
brew install stripe/stripe-cli/stripe

# Windows:
# Download from https://github.com/stripe/stripe-cli/releases

Forward webhooks to your local server:

stripe login
stripe listen --forward-to localhost:3456/api/billing/webhook

This outputs a webhook signing secret (starts with whsec_...). Copy it and update .env:

STRIPE_WEBHOOK_SECRET=whsec_YOUR_LOCAL_WEBHOOK_SECRET

Leave the CLI running while testing.

Production (Live Server)

1. In Stripe Dashboard, go to Developers → Webhooks
2. Click + Add endpoint
3. Fill in:
   • Endpoint URL: https://your-domain.com/api/billing/webhook
   • Description (optional): TenderRadar production webhook
   • Events to send: Select these 4 events:
     • checkout.session.completed
     • customer.subscription.updated
     • customer.subscription.deleted
     • invoice.payment_failed
   • OR select Receive all events (simpler but more traffic)
4. Click Add endpoint
5. On the webhook details page, click Signing secret → Reveal
6. Copy the signing secret (starts with whsec_...)
7. Update production .env:

   STRIPE_WEBHOOK_SECRET=whsec_YOUR_PRODUCTION_WEBHOOK_SECRET
   

---

9. Restart Your Server

After updating .env:

cd /home/peter/tenderpilot
pm2 restart all   # If using PM2
# OR
pkill -f 'node.*server.js'
npm start &

---

10. Test the Integration

Register a Test User

curl -X POST http://localhost:3456/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpass123",
    "company_name": "Test Company"
  }'

Save the returned token.

Create a Checkout Session

curl -X POST http://localhost:3456/api/billing/checkout \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "starter",
    "successUrl": "http://localhost:3000/success",
    "cancelUrl": "http://localhost:3000/cancel"
  }'

This returns a url — open it in your browser to test the payment flow.

Use Stripe Test Cards

In Test Mode, use these card numbers:

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Requires 3D Secure: 4000 0025 0000 3155

Any future expiry date and any CVC will work.

Check Subscription Status

curl -X GET http://localhost:3456/api/billing/subscription \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Should return subscription details after successful checkout.

---

Common Issues

"Invalid plan: starter"

• Cause: Price ID not set in .env or typo in plan name
• Fix: Verify STRIPE_PRICE_STARTER is set correctly and plan parameter is lowercase

"Webhook signature verification failed"

• Cause: Wrong STRIPE_WEBHOOK_SECRET
• Fix:
  • For localhost: Ensure Stripe CLI is running (stripe listen ...)
  • For production: Copy signing secret from webhook endpoint in Dashboard

"No such customer"

• Cause: Customer ID doesn't exist in Stripe
• Fix: This is usually a database sync issue — check subscriptions table

Payment succeeds but no subscription in database

• Cause: Webhook not firing or webhook handler error
• Fix: Check Stripe Dashboard → Developers → Events for webhook delivery status

---

Pricing Summary

Plan	Monthly Price	Annual Equivalent	Price ID Env Var
Starter	£39	£468	STRIPE_PRICE_STARTER
Growth	£99	£1,188	STRIPE_PRICE_GROWTH
Pro	£249	£2,988	STRIPE_PRICE_PRO

All plans include a 14-day free trial (configured in code, not Stripe).

---

Next Steps

1. ✅ Create the 3 Price objects in Stripe Dashboard
2. ✅ Copy Price IDs to .env
3. ✅ Get API keys and add to .env
4. ✅ Set up webhook endpoint
5. ✅ Restart server
6. ✅ Test with Stripe test cards
7. 🚀 Deploy to production with live keys

---

Resources

• Stripe Dashboard: https://dashboard.stripe.com
• Stripe API Docs: https://stripe.com/docs/api
• Test Cards: https://stripe.com/docs/testing
• Stripe CLI: https://stripe.com/docs/stripe-cli
• Webhooks Guide: https://stripe.com/docs/webhooks

---

Questions? Check the other documentation files:

• STRIPE_SETUP.md — Complete integration overview
• BILLING_API_EXAMPLES.md — API testing examples
• STRIPE_INTEGRATION_SUMMARY.md — High-level summary