Server : Apache/2 System : Linux server-15-235-50-60 5.15.0-164-generic #174-Ubuntu SMP Fri Nov 14 20:25:16 UTC 2025 x86_64 User : gositeme ( 1004) PHP Version : 8.2.29 Disable Function : exec,system,passthru,shell_exec,proc_close,proc_open,dl,popen,show_source,posix_kill,posix_mkfifo,posix_getpwuid,posix_setpgid,posix_setsid,posix_setuid,posix_setgid,posix_seteuid,posix_setegid,posix_uname Directory :  /home/gositeme/domains/soundstudiopro.com/private_html/

Upload File : current_dir [ Writeable ] document_root [ Writeable ]

# Subscription Sync Guide

## Problem: Stripe Transaction Completed But Database Not Updated

### What Happened
- User initiated upgrade on `subscribe.php?plan=starter`
- Stripe processed the subscription update successfully
- User stopped/closed the page mid-process
- Webhook didn't fire or failed to update database
- Transaction was refunded in Stripe
- Database still shows old subscription state (0/5 tracks)

### Solution: Sync Subscription from Stripe

#### Option 1: Use Sync Script (Recommended)
1. Go to: `/sync_subscription_from_stripe.php?user_id=USER_ID`
   - Replace `USER_ID` with the actual user ID
   - Or use: `/sync_subscription_from_stripe.php?email=user@email.com`

2. The script will:
   - Fetch current subscription state from Stripe
   - Compare with database
   - Update database to match Stripe
   - Update user plan
   - Update track limits
   - Handle refunded/canceled subscriptions

#### Option 2: Use Sync Button on Manage Subscription Page
1. User goes to `/manage_subscription.php`
2. Scroll to bottom
3. Click "Sync Subscription from Stripe" button
4. Opens sync page in new tab
5. Shows detailed sync results

### What the Sync Script Does

1. **Fetches from Stripe:**
   - Gets all subscriptions for the customer
   - Reads current plan (from price ID)
   - Gets subscription status (active, canceled, past_due, etc.)
   - Gets billing period dates

2. **Updates Database:**
   - Updates `user_subscriptions` table with current Stripe state
   - Updates `users.plan` field
   - Updates `monthly_track_usage.track_limit` if plan changed
   - Handles canceled subscriptions (sets user to 'free' plan)

3. **Handles Edge Cases:**
   - If subscription was refunded → status becomes 'canceled' or 'past_due'
   - If plan changed but webhook failed → updates plan and track limit
   - If subscription doesn't exist in DB → creates new record
   - If multiple subscriptions → uses most recent active one

### After Refund Scenario

If the transaction was refunded:
1. Stripe subscription status may be:
   - `canceled` - Subscription was canceled
   - `past_due` - Payment failed
   - `active` - If refund was partial or subscription still active

2. Sync script will:
   - Detect the status from Stripe
   - Update database accordingly
   - If canceled/past_due → set user plan to 'free'
   - If still active → keep subscription active with correct plan

### Prevention: Webhook Improvements

The webhook handler (`webhooks/stripe.php`) has been improved to:
- Store old values BEFORE updating (prevents data loss)
- Handle subscription not found gracefully
- Update track limits when plan changes
- Better error logging

### Manual Steps for This User

1. **Identify the user:**
   - Get user ID or email
   - Check current subscription in database
   - Check Stripe dashboard for actual subscription state

2. **Run sync:**
   ```
   /sync_subscription_from_stripe.php?user_id=USER_ID
   ```

3. **Verify:**
   - Check that database matches Stripe
   - Verify track limits are correct
   - Check user can access correct features

4. **If refunded:**
   - Stripe should show subscription as canceled or past_due
   - Sync will set user back to 'free' plan
   - Track limit should reset to 0 or free tier limit

### Testing Sync

To test the sync functionality:
1. Visit `/sync_subscription_from_stripe.php?user_id=USER_ID`
2. Review the output:
   - Shows Stripe subscription details
   - Shows database subscription details
   - Shows what will be updated
   - Confirms successful sync

### Future Improvements

1. **Automatic Retry:**
   - Add retry mechanism for failed webhooks
   - Queue failed webhook events for retry

2. **Background Sync:**
   - Periodic sync job to catch discrepancies
   - Daily sync for all active subscriptions

3. **User Notification:**
   - Notify user if sync detects issues
   - Email when subscription state changes