How Migration Works

1. Automatic Detection: During login or registration, the system checks if the user has a local subscription record
2. Stripe Search: If no local subscription exists, the system searches Stripe for customers matching the user's email address
3. Background Processing: Migration runs asynchronously to avoid blocking the authentication response
4. Data Preservation: Successfully migrated subscriptions maintain their exact:
   • Billing cycle dates (current period start/end)
   • Trial period information (if applicable)
   • Pricing and plan details
   • Subscription status (active, trialing, past_due, etc.)
   • Cancellation settings (cancel_at_period_end flag)
5. Local Record Creation: The Stripe subscription is imported into the local database for faster access
6. Ongoing Sync: Future logins automatically sync subscription data with Stripe to ensure accuracy

When Migration Occurs

Automatic migration attempts happen during the following authentication flows:

• Email/Password Login: POST /api/auth/login
• Email/Password Registration: POST /api/auth/register
• Google OAuth Login: POST /api/auth/google/login
• Google OAuth Registration: POST /api/auth/google/register
• Google PKCE Login: POST /api/auth/google/callback-pkce (mode: login)
• Google PKCE Registration: POST /api/auth/google/callback-pkce (mode: register)
• Apple OAuth Login: POST /api/auth/apple/callback (mode: login)
• Apple OAuth Registration: POST /api/auth/apple/callback (mode: register)

Migration Behavior

Scenario	Behavior	User Experience
User has local subscription	No migration attempted; existing record used	Immediate access with existing subscription
User has Stripe subscription	Background migration imports subscription	Can log in immediately; subscription appears after migration
User has no subscription	Migration finds nothing; no error	Can log in and subscribe normally
Migration error occurs	Error logged; authentication succeeds	Can log in; migration retried on next login

Edge Cases Handled

• Multiple Subscriptions: If multiple active subscriptions exist in Stripe, the most recent one is migrated
• Cancelled Subscriptions: Subscriptions with cancel_at_period_end=true are migrated with their cancellation status preserved
• Trial Subscriptions: Trial periods are preserved exactly as configured in Stripe
• Past Due Subscriptions: Past due subscriptions are migrated but don't grant access until payment is resolved
• Legacy Pricing: Archived Stripe prices are synced as inactive plans but remain usable for existing subscriptions
• Email Mismatches: Only subscriptions matching the exact email address are migrated

Non-Blocking Design

Migration is designed to never block user authentication:

• ✅ Users can log in or register immediately
• ✅ Migration runs in the background asynchronously
• ✅ Authentication succeeds even if migration fails
• ✅ Failed migrations are automatically retried on next login
• ✅ All migration attempts are logged for troubleshooting

Technical Implementation

The migration process follows these steps:

1. Check if user has local subscription (migration_status field)
2. If not, search Stripe for customer by email
3. If customer found, retrieve all subscriptions
4. Filter for active subscriptions (active, trialing, past_due)
5. Select most recent subscription if multiple exist
6. Extract price ID and sync price/plan to database
7. Create local subscription record with all metadata
8. Mark migration as complete (migration_status='migrated')
9. Log success/failure to audit table
10. Continue with authentication flow

Migration Tracking

Subscription records include migration tracking fields:

• migration_status - null (not migrated), 'migrated', or 'migration_failed'
• migrated_at - Timestamp when migration completed
• legacy_subscription_id - Original Stripe subscription ID

For Developers

When implementing client applications:

• No special handling required for migration
• Subscription data may not be immediately available after registration
• Consider polling or refreshing user data to detect migrated subscriptions
• Optional: Display a message during first login that migration is in progress

GET /api/subscriptions

List all subscriptions with filtering and pagination (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Query Parameters:

• sort - JSON array with field name and direction ["fieldName","ASC|DESC"]
  Available sort fields: id, userId, username, email, subscriptionPlanId, status, currentPeriodStart, currentPeriodEnd, trialStart, trialEnd, cancelAtPeriodEnd, canceledAt, createdAt, updatedAt, planName, interval, amount, currency, trialPeriodDays, isActive
  Example: sort=["createdAt","DESC"] - Sort by creation date in descending order
• page - Page number (1-based)
  Example: page=1 - Get the first page
• perPage - Number of items per page
  Example: perPage=10 - Show 10 items per page
• filter - JSON object with field name/value pairs for filtering {"fieldName1":"value1","fieldName2":value2}
  Example: filter={"status":"active","planName":"Pro"} - Filter active subscriptions with plan name containing "Pro"
  
  Available filters:
  • q - Global search across username, email, subscription status, plan name, plan interval, and currency
  • username - Filter by username (partial match, case-insensitive)
  • email - Filter by email address (partial match, case-insensitive)
  • status - Filter by subscription status (active, trialing, past_due, canceled, incomplete, etc.)
  • planName - Filter by subscription plan name (partial match, case-insensitive)
  • interval - Filter by billing interval (month, year)
  • amount - Filter by plan amount in cents (exact match)
  • currency - Filter by currency code (usd, eur, etc.)
  • trialPeriodDays - Filter by trial period days (exact match)
  • isActive - Filter by plan active status (true/false)
  • createdAt - Filter by subscription creation date (exact date or date range)
  • updatedAt - Filter by last update date (exact date or date range)
  • currentPeriodStart - Filter by current period start date (exact date or date range)
  • currentPeriodEnd - Filter by current period end date (exact date or date range)
  • trialStart - Filter by trial start date (exact date or date range)
  • trialEnd - Filter by trial end date (exact date or date range)
  • canceledAt - Filter by cancellation date (exact date or date range)
  
  
  Special filter: Global Search
  Using the key q in the filter will search across all text columns:
  Example: filter={"q":"pro","status":"active"} - Find active subscriptions with "pro" in any text field
• syncWithStripe - Whether to sync with Stripe before fetching data (default: true)

Example Requests:

GET /api/subscriptions?page=1&perPage=10&sort=["createdAt","DESC"]&filter={"status":"active"}

GET /api/subscriptions?page=2&perPage=20&filter={"q":"pro","status":"active"}

GET /api/subscriptions?filter={"planName":"Premium","interval":"month"}

GET /api/subscriptions?filter={"currency":"usd","amount":999}

GET /api/subscriptions?filter={"email":"gmail.com","isActive":true}

Response (200 OK):

{
    "data": [
        {
            "id": 1,
            "userId": 1,
            "email": "user@example.com",
            "username": "user123",
            "plan": {
                "id": 1,
                "stripePriceId": "price_...",
                "name": "Pro Plan",
                "interval": "month",
                "amount": 999,
                "currency": "usd",
                "trialPeriodDays": 14,
                "isActive": true,
                "createdAt": "2023-01-15T08:30:00Z",
                "updatedAt": null
            },
            "status": "active",
            "currentPeriodStart": "2023-06-01T00:00:00Z",
            "currentPeriodEnd": "2023-07-01T00:00:00Z",
            "trialStart": "2023-06-01T00:00:00Z",
            "trialEnd": "2023-06-15T00:00:00Z",
            "cancelAtPeriodEnd": false,
            "canceledAt": null,
            "createdAt": "2023-06-01T00:00:00Z",
            "updatedAt": null,
            "promotion": {
                "id": 5,
                "name": "Summer Sale 2023",
                "coupon": {
                    "id": 3,
                    "type": "DISC",
                    "name": "Discount Percentage",
                    "percentOff": 20,
                    "trialDays": null
                }
            },
            "discount": {
                "percentOff": 20,
                "amountOff": 200,
                "discountedAmount": 799
            }
        }
        // Additional subscription objects...
    ],
    "total": 42
}

Notes:

• The response includes pagination metadata in headers: Content-Range, Accept-Range, X-Total-Count
• Each subscription includes the full plan details
• Subscription responses include any applied promotional code and coupon information
• You can sort by plan fields using planName, interval, amount, etc.
• The syncWithStripe parameter allows you to ensure that all subscription data is fresh from Stripe before applying filters and pagination
• Requires admin privileges or appropriate authorization to view other users' subscriptions

GET /api/subscriptions/me

Get the current user's subscription (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 1,
        "stripePriceId": "price_...",
        "name": "Pro Plan",
        "interval": "month",
        "amount": 999,
        "currency": "usd",
        "trialPeriodDays": 14,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": "2023-06-01T00:00:00Z",
    "trialEnd": "2023-06-15T00:00:00Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": null,
    "promotion": {
        "id": 5,
        "name": "Summer Sale 2023",
        "coupon": {
            "id": 3,
            "type": "DISC",
            "name": "Discount Percentage",
            "percentOff": 20,
            "trialDays": null
        }
    },
    "discount": {
        "percentOff": 20,
        "amountOff": 200,
        "discountedAmount": 799
    }
}

Notes:

• The plan.amount field shows the base plan price in cents (e.g., 999 = $9.99)
• When a promotion is applied, the discount field shows:
  • percentOff - The discount percentage applied
  • amountOff - The discount amount in cents
  • discountedAmount - The final price after discount in cents (e.g., 799 = $7.99)
• If no promotion is applied, the promotion field will be null and discount will be null

GET /api/subscriptions/plans

List all available subscription plans (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Query Parameters:

• sort - JSON array with field name and direction ["fieldName","ASC|DESC"]
  Available sort fields: id, stripePriceId, name, interval, amount, currency, trialPeriodDays, isActive, createdAt, updatedAt
  Example: sort=["amount","ASC"] - Sort by price amount in ascending order
  Example: sort=["name","ASC"] - Sort by plan name in ascending order
• page - Page number (1-based)
  Example: page=1 - Get the first page
• perPage - Number of items per page
  Example: perPage=10 - Show 10 items per page
• filter - JSON object with field name/value pairs for filtering {"fieldName1":"value1","fieldName2":value2}
  Example: filter={"isActive":true} - Show only active subscription plans
  Example: filter={"interval":"month"} - Filter by billing interval
  Example: filter={"currency":"usd"} - Filter by currency
  
  Available filters:
  • q - Global search across plan name, interval, and currency
  • name - Filter by plan name (partial match, case-insensitive)
  • interval - Filter by billing interval (month, year, etc.)
  • amount - Filter by plan amount in cents (exact match)
  • currency - Filter by currency code (usd, eur, etc.)
  • trialPeriodDays - Filter by trial period days (exact match)
  • isActive - Filter by plan active status (true/false)
  
  
  Special filter: Global Search
  Using the key q in the filter will search across all text columns:
  Example: filter={"q":"pro"} - Find plans with "pro" in their name
• syncWithStripe - Whether to sync with Stripe before fetching data (default: true)

Example Requests:

GET /api/subscriptions/plans?page=1&perPage=10&sort=["amount","ASC"]&filter={"isActive":true}&syncWithStripe=true

GET /api/subscriptions/plans?page=2&perPage=20&filter={"q":"pro","interval":"month"}

GET /api/subscriptions/plans?filter={"currency":"usd","amount":999}

GET /api/subscriptions/plans?filter={"trialPeriodDays":14,"isActive":true}

Response (200 OK):

{
    "data": [
        {
            "id": 1,
            "stripePriceId": "price_...",
            "name": "Basic Plan",
            "interval": "month",
            "amount": 499,
            "currency": "usd",
            "trialPeriodDays": 14,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        },
        {
            "id": 2,
            "stripePriceId": "price_...",
            "name": "Pro Plan",
            "interval": "month",
            "amount": 999,
            "currency": "usd",
            "trialPeriodDays": 14,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        }
        // Additional plan objects...
    ],
    "total": 5
}

Notes:

• The syncWithStripe parameter allows you to ensure that all subscription data is fresh from Stripe before applying filters and pagination

GET /api/subscriptions/verify-payment

Verify payment status for a subscription using payment intent ID (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Query Parameters:

• paymentIntentId - The Stripe payment intent ID to verify

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 1,
        "stripePriceId": "price_...",
        "name": "Pro Plan",
        "interval": "month",
        "amount": 999,
        "currency": "usd",
        "trialPeriodDays": 14,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": null,
    "trialEnd": null,
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": "2023-06-15T00:00:00Z",
    "promotion": null
}

Error Responses:

{
    "message": "Payment intent ID is required"
}

{
    "message": "Subscription not found or could not be updated"
}

GET /api/subscriptions/verify-setup

Verify setup intent status for a subscription (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Query Parameters:

• setupIntentId - The Stripe setup intent ID to verify

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 1,
        "stripePriceId": "price_...",
        "name": "Pro Plan",
        "interval": "month",
        "amount": 999,
        "currency": "usd",
        "trialPeriodDays": 14,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": null,
    "trialEnd": null,
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": "2023-06-15T00:00:00Z",
    "promotion": null
}

Error Responses:

{
    "message": "Setup intent ID is required"
}

{
    "message": "Subscription not found or could not be updated"
}

POST /api/subscriptions/change-plan

Change the user's subscription to a different plan (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "planId": 2,
    "prorationBehavior": "create_prorations"  // Optional: "create_prorations", "none", or "always_invoice"
}

Response (200 OK):

{
    "message": "Subscription plan changed successfully",
    "subscription": {
        "id": 1,
        "userId": 1,
        "email": "user@example.com",
        "username": "user123",
        "plan": {
            "id": 2,
            "stripePriceId": "price_...",
            "name": "Premium Plan",
            "interval": "month",
            "amount": 1999,
            "currency": "usd",
            "trialPeriodDays": 0,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        },
        "status": "active",
        "currentPeriodStart": "2023-06-01T00:00:00Z",
        "currentPeriodEnd": "2023-07-01T00:00:00Z",
        "trialStart": null,
        "trialEnd": null,
        "cancelAtPeriodEnd": false,
        "canceledAt": null,
        "createdAt": "2023-06-01T00:00:00Z",
        "updatedAt": "2023-06-15T00:00:00Z",
        "promotion": null
    }
}

Error Responses:

{
    "message": "Plan ID is required"
}

{
    "message": "You don't have an active subscription"
}

{
    "message": "You are already subscribed to this plan"
}

{
    "message": "The selected plan is not available"
}

POST /api/subscriptions/change-plan-with-payment-method

Change the user's subscription to a different plan while updating payment method (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "planId": 2,
    "paymentMethodId": "pm_1234567890",
    "prorationBehavior": "create_prorations"  // Optional: "create_prorations", "none", or "always_invoice"
}

Response (200 OK):

{
    "requiresAction": true,
    "setupIntentClientSecret": "seti_1RJYc0PFpKHu6YD8quMd7VH8_secret_...",
    "setupIntentId": "seti_1RJYc0PFpKHu6YD8quMd7VH8",
    "planId": 2,
    "prorationBehavior": "create_prorations"
}

Error Responses:

{
    "message": "Plan ID is required"
}

{
    "message": "Payment method ID is required"
}

{
    "message": "You don't have an active subscription"
}

{
    "message": "There was a problem setting up the payment method"
}

POST /api/subscriptions/confirm-change-plan

Confirm plan change after setup intent is completed (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "setupIntentId": "seti_1RJYc0PFpKHu6YD8quMd7VH8",
    "planId": 2,
    "prorationBehavior": "create_prorations"  // Optional: "create_prorations", "none", or "always_invoice"
}

Response (200 OK):

{
    "message": "Subscription plan and payment method updated successfully",
    "subscription": {
        "id": 1,
        "userId": 1,
        "email": "user@example.com",
        "username": "user123",
        "plan": {
            "id": 2,
            "stripePriceId": "price_...",
            "name": "Premium Plan",
            "interval": "month",
            "amount": 1999,
            "currency": "usd",
            "trialPeriodDays": 0,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        },
        "status": "active",
        "currentPeriodStart": "2023-06-01T00:00:00Z",
        "currentPeriodEnd": "2023-07-01T00:00:00Z",
        "trialStart": null,
        "trialEnd": null,
        "cancelAtPeriodEnd": false,
        "canceledAt": null,
        "createdAt": "2023-06-01T00:00:00Z",
        "updatedAt": "2023-06-15T00:00:00Z",
        "promotion": null
    }
}

Error Responses:

{
    "message": "Setup intent ID is required"
}

{
    "message": "Plan ID is required"
}

{
    "message": "Setup intent is not complete. Current status: requires_payment_method"
}

{
    "message": "Failed to attach payment method"
}

POST /api/subscriptions/create-free-trial

Create a free trial subscription without requiring payment method (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "priceId": "price_H5ggYwtDq4fbrJ",
    "trialPeriodDays": 14  // Optional: Defaults to 14 days if not specified
}

Response (200 OK):

{
    "message": "Free trial subscription created successfully",
    "subscription": {
        "id": 1,
        "userId": 1,
        "email": "user@example.com",
        "username": "user123",
        "plan": {
            "id": 1,
            "stripePriceId": "price_H5ggYwtDq4fbrJ",
            "name": "Pro Plan",
            "interval": "month",
            "amount": 999,
            "currency": "usd",
            "trialPeriodDays": 14,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        },
        "status": "trialing",
        "currentPeriodStart": "2023-06-01T00:00:00Z",
        "currentPeriodEnd": "2023-07-01T00:00:00Z",
        "trialStart": "2023-06-01T00:00:00Z",
        "trialEnd": "2023-06-15T00:00:00Z",
        "cancelAtPeriodEnd": false,
        "canceledAt": null,
        "createdAt": "2023-06-01T00:00:00Z",
        "updatedAt": null,
        "promotion": null
    },
    "trialEnd": "2023-06-15T00:00:00Z"
}

Error Responses:

{
    "message": "User already has an active subscription"
}

{
    "message": "Price ID is required"
}

{
    "message": "User not found"
}

{
    "message": "Subscription plan not found"
}

POST /api/subscriptions/create-with-payment-method

Create a subscription with payment method ID (deferred payment flow) (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "priceId": "price_H5ggYwtDq4fbrJ",
    "paymentMethodId": "pm_1234567890",
    "trialPeriodDays": 14,  // Optional: Number of trial days
    "promoCode": "SUMMER20",  // Optional: Promotion code to apply (provide either promoCode or promotionId, not both)
    "promotionId": 5  // Optional: Promotion ID (database ID) to apply (provide either promoCode or promotionId, not both)
}

Response (200 OK):

{
    "subscriptionId": "sub_1RJYc0PFpKHu6YD8quMd7VH8",
    "type": "payment",
    "clientSecret": "cs_test_...",
    "promotionApplied": true
}

Alternative Response (Setup Flow):

{
    "subscriptionId": "sub_1RJYc0PFpKHu6YD8quMd7VH8",
    "type": "setup",
    "clientSecret": "seti_1RJYc0PFpKHu6YD8quMd7VH8_secret_...",
    "promotionApplied": true
}

Error Responses:

{
    "message": "Price ID is required"
}

{
    "message": "Payment method ID is required"
}

{
    "message": "Please provide either promoCode or promotionId, not both"
}

{
    "message": "Invalid promotion code"
}

{
    "message": "Promotion with ID 5 not found"
}

{
    "message": "Promotion code \"SUMMER20\" not found in Stripe"
}

{
    "message": "This promotion cannot be applied to subscriptions"
}

{
    "message": "User already has an active subscription"
}

{
    "message": "Subscription plan not found"
}

Notes:

• This endpoint follows Stripe's deferred payment pattern
• Response type indicates whether payment confirmation or setup intent completion is required
• Use the clientSecret on the frontend to complete the payment or setup process
• Promotion Handling:
  • You can provide either promoCode (string) or promotionId (number), but not both
  • The promoCode is the promotion code string (e.g., "SUMMER20")
  • The promotionId is the database ID from the promotions table
  • The promotion is validated before creating the subscription
  • Only SUBS promotions (with associated coupons) can be applied to subscriptions
  • NONS promotions (subscription exemptions) cannot be applied during subscription creation
  • If the promotion doesn't exist in Stripe, it will be created on-demand (for legacy promotions)
  • The promotion is applied immediately in Stripe when creating the subscription
  • Promotion redemption is recorded in the database after successful subscription creation
  • The promotionApplied field in the response indicates whether a promotion was successfully applied
• If promotion code validation or application fails, the entire subscription creation fails

POST /api/subscriptions/migrate-and-sync

Trigger bulk migration and synchronization of Stripe subscriptions for SUBS users (requires authentication and admin privileges). This endpoint searches Stripe for subscriptions associated with user email addresses and imports them into the local database, preserving all billing cycles, pricing, and trial information. It can also re-sync existing subscriptions to ensure data consistency between Stripe and the local database. This is particularly useful for:

• Initial Migration: Importing subscriptions from a legacy Stripe account when transitioning to a new application
• New User Onboarding: Automatically discovering and importing subscriptions for users who register with existing Stripe subscriptions
• Data Reconciliation: Ensuring local subscription records match the current state in Stripe after manual changes or webhook failures
• Batch Processing: Processing multiple users at once rather than waiting for individual logins to trigger automatic migration
• Promotion Reconciliation: Syncing promotion redemptions with subscription IDs and Stripe discount IDs

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...
x-csrf-token: a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3

Request Body:

{
    "batchSize": 50,         // Optional: Number of users to process (default: 50)
    "dryRun": false,         // Optional: If true, returns users to migrate without processing (default: false)
    "resync": false,         // Optional: If true, re-syncs ALL SUBS users including those with subscriptions (default: false)
    "forceResync": false,    // Optional: If true, includes users synced within the last hour (default: false)
    "activeUsersOnly": true  // Optional: If true, only migrates users who have logged in at least once (default: true)
}

Response (200 OK) - Dry Run:

{
    "message": "Dry run completed - no migrations performed",
    "usersToMigrate": 42,
    "users": [
        {
            "id": 123,
            "email": "user@example.com",
            "hasSubscription": false
        },
        {
            "id": 456,
            "email": "existing@example.com",
            "hasSubscription": true
        }
        // Additional users...
    ],
    "note": "Excluding users synced within the last hour",
    "activeUsersOnly": true
}

Response (200 OK) - Actual Migration:

{
    "message": "Bulk migration completed",
    "results": {
        "total": 50,
        "successful": 30,    // New migrations
        "failed": 5,
        "skipped": 10,
        "resynced": 5        // Existing subscriptions that were re-synced
    },
    "errors": [
        {
            "userId": 456,
            "email": "failed@example.com",
            "error": "Failed to sync price: Price not found in Stripe"
        }
        // Additional errors if any...
    ]
}

Response (200 OK) - Re-sync Mode:

{
    "message": "Bulk re-sync completed",
    "results": {
        "total": 50,
        "successful": 15,    // New migrations found
        "failed": 2,
        "skipped": 8,        // No Stripe subscriptions found
        "resynced": 25       // Existing subscriptions updated with latest Stripe data
    }
}

Error Responses:

{
    "message": "Access denied. Admin privileges required."
}

Notes:

• Default Mode (resync=false): Only processes SUBS users WITHOUT local subscriptions
• Re-sync Mode (resync=true): Processes ALL SUBS users to ensure subscriptions are up-to-date
• Active Users Only (activeUsersOnly=true, default): Only processes users who have logged in at least once to the new application
  • Filters for users where last_login_at IS NOT NULL
  • Prevents migrating subscriptions for users who haven't actually used the new app
  • Set to false to include all SUBS users regardless of login status
• Smart Batching: By default, excludes users synced within the last hour to prevent re-processing the same batch
  • Each successful sync updates the synced_at timestamp on the subscription
  • Subsequent batch runs automatically skip recently synced users
  • This ensures progress through all users when running multiple batches
  • Use forceResync=true to override this behavior and re-process all users
• Ordering: Users are processed in order of least recently synced first, ensuring older data gets updated first
• Works for All SUBS Users: Migration searches Stripe by email, working for both legacy imports and new registrations
• Migration happens automatically on login, this endpoint is for bulk processing
• Use dryRun=true to preview which users will be processed without performing the operation
• Batch processing prevents overwhelming the Stripe API
• Failed migrations are logged and can be retried individually
• Skipped users are those without any Stripe subscriptions to migrate
• Re-synced users are those with existing subscriptions that were updated from Stripe
• Use Cases:
  • Initial migration (active users only): resync=false, activeUsersOnly=true
  • Initial migration (all users): resync=false, activeUsersOnly=false
  • Regular batch sync (active users): Run with resync=true, activeUsersOnly=true, batchSize=50 multiple times
  • Data reconciliation (all users): resync=true, activeUsersOnly=false
  • Force complete re-sync: resync=true, forceResync=true
  • Troubleshooting: dryRun=true to see what would be processed
  • New user subscriptions: Automatically finds Stripe subscriptions for newly registered SUBS users who have logged in

POST /api/subscriptions/resume

Resume a subscription that was previously scheduled for cancellation (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 1,
        "stripePriceId": "price_...",
        "name": "Pro Plan",
        "interval": "month",
        "amount": 999,
        "currency": "usd",
        "trialPeriodDays": 14,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": null,
    "trialEnd": null,
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": "2023-06-15T00:00:00Z",
    "promotion": null
}

Error Responses:

{
    "message": "Subscription not found or could not be resumed"
}

{
    "message": "Failed to resume subscription",
    "error": "Cannot resume subscription because it is already fully canceled"
}

POST /api/subscriptions/sync-plans

Sync subscription plans with Stripe (requires authentication and admin privileges). This endpoint synchronizes subscription plans from Stripe into the local database, ensuring pricing and plan information is up-to-date.

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...
x-csrf-token: a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3

Request Body:

{
    "dryRun": false  // Optional: If true, returns plans to sync without processing (default: false)
}

Response (200 OK) - Dry Run:

{
    "message": "Dry run completed - no plans were synced",
    "plansToSync": 8,
    "details": {
        "existingPlans": [
            {
                "id": 1,
                "stripePriceId": "price_...",
                "name": "Basic Plan",
                "amount": 499,
                "currency": "usd",
                "interval": "month",
                "isActive": true
            }
            // Additional existing plans...
        ],
        "stripePrices": [
            {
                "id": "price_...",
                "nickname": "Basic Monthly",
                "amount": 499,
                "currency": "usd",
                "interval": "month",
                "active": true
            }
            // Additional Stripe prices...
        ],
        "analysis": {
            "totalExistingPlans": 5,
            "totalStripePrices": 8,
            "plansToUpdate": 2,
            "plansToAdd": 3,
            "plansToDeactivate": 0
        }
    }
}

Response (200 OK) - Actual Sync:

{
    "message": "Successfully synchronized 8 subscription plans with Stripe",
    "syncedPlans": 8,
    "results": {
        "synced": 5,
        "added": 3,
        "deactivated": 0
    }
}

Error Responses:

{
    "message": "Access denied. Admin privileges required."
}

Notes:

• Use dryRun=true to preview which plans will be synced without making any changes
• The dry run response includes detailed analysis of existing plans vs Stripe prices
• Synced plans are those that were updated with new data from Stripe
• Added plans are new prices from Stripe that didn't exist in the local database
• Deactivated plans are local plans that are no longer active in Stripe

POST /api/subscriptions/update-payment-method

Update the payment method for a user's subscription (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Request Body:

{
    "paymentMethodId": "pm_1234567890"
}

Response (200 OK):

{
    "success": true,
    "message": "Payment method updated successfully",
    "subscription": {
        "id": 1,
        "userId": 1,
        "email": "user@example.com",
        "username": "user123",
        "plan": {
            "id": 1,
            "stripePriceId": "price_...",
            "name": "Pro Plan",
            "interval": "month",
            "amount": 999,
            "currency": "usd",
            "trialPeriodDays": 14,
            "isActive": true,
            "createdAt": "2023-01-15T08:30:00Z",
            "updatedAt": null
        },
        "status": "active",
        "currentPeriodStart": "2023-06-01T00:00:00Z",
        "currentPeriodEnd": "2023-07-01T00:00:00Z",
        "trialStart": null,
        "trialEnd": null,
        "cancelAtPeriodEnd": false,
        "canceledAt": null,
        "createdAt": "2023-06-01T00:00:00Z",
        "updatedAt": "2023-06-15T00:00:00Z",
        "promotion": null
    }
}

Error Responses:

{
    "success": false,
    "message": "Payment method ID is required"
}

{
    "success": false,
    "message": "Failed to update payment method",
    "error": {
        "type": "card_error",
        "message": "Your card was declined.",
        "code": "card_declined",
        "decline_code": "generic_decline"
    }
}

Notes:

• This endpoint updates both the customer's default payment method and applies it to active subscriptions
• Error responses include detailed Stripe error information when payment method attachment fails

PUT /api/subscriptions/me

Update the current user's subscription (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...
x-csrf-token: a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3

Request Body:

{
    "planId": 2,
    "paymentMethodId": "pm_1234567890"  // Optional: New payment method
}

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 2,
        "stripePriceId": "price_...",
        "name": "Premium Plan",
        "interval": "month",
        "amount": 1999,
        "currency": "usd",
        "trialPeriodDays": 0,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": null,
    "trialEnd": null,
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": "2023-06-15T00:00:00Z",
    "promotion": null
}

DELETE /api/subscriptions/me

Cancel the current user's subscription (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Query Parameters:

• cancelAtPeriodEnd - Whether to cancel at period end (default: true). Set to false for immediate cancellation.

Response (200 OK):

{
    "id": 1,
    "userId": 1,
    "email": "user@example.com",
    "username": "user123",
    "plan": {
        "id": 1,
        "stripePriceId": "price_...",
        "name": "Pro Plan",
        "interval": "month",
        "amount": 999,
        "currency": "usd",
        "trialPeriodDays": 14,
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "updatedAt": null
    },
    "status": "active",
    "currentPeriodStart": "2023-06-01T00:00:00Z",
    "currentPeriodEnd": "2023-07-01T00:00:00Z",
    "trialStart": null,
    "trialEnd": null,
    "cancelAtPeriodEnd": true,
    "canceledAt": "2023-06-15T00:00:00Z",
    "createdAt": "2023-06-01T00:00:00Z",
    "updatedAt": "2023-06-15T00:00:00Z",
    "promotion": null
}