# Stripe Customer Portal Configuration - Detailed Steps

## Test Mode Configuration

### Step 1: Navigate to Customer Portal Settings

1. Open your web browser
2. Go to: **https://dashboard.stripe.com/test/settings/billing/portal**
3. You should see the "Customer portal" page with a toggle for "Test mode" in the top-right corner
4. Ensure **"Test mode"** toggle is ON (blue)

---

### Step 2: Activate the Customer Portal

You'll see one of two states:

**If you see "Activate customer portal":**
- Click the blue **"Activate customer portal"** button

**If you see "Configure" or settings are already visible:**
- Proceed to Step 3

---

### Step 3: Configure Customer Information Section

Look for the **"Customer information"** section (usually at the top):

1. Find the checkbox labeled **"Email address"**
   - ✅ **Check this box**
   - This allows customers to update their email

2. Find the checkbox labeled **"Payment methods"**
   - ✅ **Check this box**
   - This allows customers to add/update payment methods

---

### Step 4: Configure Subscription Settings

Scroll down to the **"Subscriptions"** section:

1. Find **"Allow customers to cancel subscriptions"**
   - Click the toggle or checkbox to **enable it** (should turn blue/green)

2. Under **"Cancellation behavior"**, select:
   - Option: **"Cancel at period end"** (recommended)
   - This means subscriptions stay active until the end of the billing period

3. Find **"Cancellation survey"**
   - Click the toggle to **enable it** (should turn blue/green)

4. Click **"Add question"** or **"Configure survey"** button

---

### Step 5: Configure Exit Survey Questions

#### Question 1 (Required):
1. Click **"Add question"**
2. **Question type**: Select "Multiple choice"
3. **Question text**: Type exactly:
   ```
   Why are you cancelling?
   ```
4. **Required**: Toggle ON (should be blue)
5. **Answer options** (click "Add option" for each):
   - Too expensive
   - No longer need it
   - Found an alternative
   - Not what I expected
   - Other

6. For the "Other" option:
   - ✅ Check **"Allow text input"** (this lets users explain further)

7. Click **"Save"** or **"Add"**

#### Question 2 (Optional):
1. Click **"Add question"** again
2. **Question type**: Select "Text"
3. **Question text**: Type exactly:
   ```
   How can we improve?
   ```
4. **Required**: Toggle OFF (leave unchecked)
5. Click **"Save"** or **"Add"**

---

### Step 6: Configure Invoice History

Scroll to the **"Invoice history"** section:

1. Find **"Show invoice history"**
   - ✅ **Check this box** or toggle ON
   - This lets customers see past invoices and receipts

---

### Step 7: Configure Business Information

Scroll to the **"Business information"** section:

1. **Business name**:
   - Type: `Tractatus AI Safety Framework`

2. **Support email**:
   - Type: `support@agenticgovernance.digital`

3. **Privacy policy URL**:
   - Type: `https://agenticgovernance.digital/about/values.html`

4. **Terms of service URL**:
   - Type: `https://agenticgovernance.digital/about/values.html`

---

### Step 8: Review and Save

1. Scroll to the **bottom** of the page
2. Click the blue **"Save changes"** button
3. You should see a green success message: "Customer portal settings updated"

---

## Live Mode Configuration

Once Test Mode is working, repeat the EXACT same steps for Live Mode:

### Step 1: Switch to Live Mode
1. In the top-right corner of Stripe Dashboard, find the **"Test mode"** toggle
2. Click it to switch to **Live mode** (toggle should turn OFF/gray)
3. You may see a banner saying "You're now in live mode"

### Step 2: Navigate to Live Customer Portal Settings
1. Go to: **https://dashboard.stripe.com/settings/billing/portal**
   - Note: This URL is slightly different (no `/test/`)

### Step 3-8: Repeat Configuration
- Follow Steps 2-8 exactly as above
- Use the same settings, same text, same options
- **CRITICAL**: Don't skip any settings - Live and Test must match

---

## Verification

### Test Mode Verification:
1. Go to http://localhost:9000/koha.html
2. Scroll to "Manage Your Subscription" section
3. Enter an email with a test subscription
4. Click "Manage"
5. You should be redirected to Stripe Customer Portal
6. Verify you can see:
   - ✅ Subscription details
   - ✅ "Update payment method" option
   - ✅ "Cancel subscription" option
7. Click "Cancel subscription"
8. Verify the exit survey appears with your two questions

### Live Mode Verification:
1. After deployment, go to https://agenticgovernance.digital/koha.html
2. Repeat the same test with your live subscription email
3. Test the full cancellation flow (you can cancel your $5 test subscription)

---

## Troubleshooting

### "No configuration provided" error:
- You haven't saved the portal configuration yet
- Go back to Step 8 and click "Save changes"
- Wait 30 seconds, then try again

### Can't find "Customer portal" in settings:
- Make sure you're logged into the correct Stripe account
- Check that you have admin permissions
- Try this direct link: https://dashboard.stripe.com/test/settings/billing/portal

### Changes not appearing:
- Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
- Check you're in the correct mode (Test vs Live)
- Stripe portal settings can take 1-2 minutes to propagate

### Exit survey not showing:
- Verify "Cancellation survey" toggle is ON
- Check that at least one question is added
- Try creating a new test portal session

---

## Screenshots Reference (What You Should See)

**Customer Portal Settings Page:**
- Top section: "Customer portal" heading with Test mode toggle
- Left sidebar: Settings, Billing, Customer portal
- Main area: Multiple configuration sections with toggles and inputs

**After Activation:**
- Customer information section (2 checkboxes)
- Subscriptions section (cancellation toggle + survey)
- Invoice history section (1 checkbox)
- Business information section (4 text inputs)
- Blue "Save changes" button at bottom

**Exit Survey Configuration:**
- Question list with drag handles
- Each question shows type (Multiple choice / Text)
- Edit/Delete buttons on each question
- "Add question" button at bottom

---

**Time Required**: 10-15 minutes total
**Last Updated**: 2025-10-18
