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:

```env
# 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`:

```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:
```bash
# Mac/Linux:
brew install stripe/stripe-cli/stripe

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

Forward webhooks to your local server:
```bash
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`:
```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`:
   ```env
   STRIPE_WEBHOOK_SECRET=whsec_YOUR_PRODUCTION_WEBHOOK_SECRET
   ```

---

### 9. Restart Your Server

After updating `.env`:

```bash
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

```bash
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

```bash
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

```bash
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