Documentation
Back to App

Managing Subscriptions

Managing Subscriptions

✅ Implemented - Customer portal access and subscription management via Stripe Customer Portal are fully implemented in AllureLMS.

Learn how to manage your AllureLMS subscription, including plan changes, cancellations, and the customer portal.

Overview

This guide covers:

  • Accessing the customer portal
  • Changing plans
  • Canceling subscriptions
  • Updating payment methods
  • Viewing billing history

Prerequisites

  • Active subscription
  • Admin or super_admin role
  • Access to billing dashboard

Customer Portal

Accessing the Portal

The Stripe Customer Portal provides self-service subscription management.

Via Web UI:

  1. Navigate to Admin → Billing
  2. Click Manage Billing
  3. Redirected to Stripe Customer Portal

Via API:

✅ Implemented - The /api/billing/portal endpoint creates Stripe Customer Portal sessions for subscription management.

curl -X POST https://your-domain.com/api/billing/portal \
  -H "Authorization: Bearer <your-jwt-token>"

Requirements:

  • Admin or super_admin role required
  • Active subscription with Stripe customer ID
  • Valid authentication token

Response:

{
  "url": "https://billing.stripe.com/session/..."
}

Redirect user to url for Stripe Customer Portal.

Error Response (No Subscription):

{
  "error": "No active subscription found. Please subscribe to a plan first."
}

Portal Features

The customer portal allows you to:

  • Update payment method
  • Change subscription plan
  • View billing history
  • Download invoices
  • Cancel subscription

Changing Plans

Upgrade/Downgrade

Via Customer Portal:

  1. Access customer portal
  2. Click Change Plan
  3. Select new plan
  4. Confirm change
  5. Plan change takes effect immediately or at next billing cycle

Via API (Direct):

# Note: Direct plan changes may require Stripe API integration
# Check API reference for current implementation

Plan Change Effects

Upgrade:

  • Immediate access to new features
  • Prorated billing for remainder of period
  • Higher included units available immediately

Downgrade:

  • Takes effect at next billing cycle
  • Current period continues with current plan
  • Usage limits apply after downgrade

Canceling Subscriptions

Via Customer Portal

  1. Access customer portal
  2. Navigate to Subscription
  3. Click Cancel Subscription
  4. Confirm cancellation
  5. Subscription remains active until period end

Cancellation Effects

  • Immediate: Subscription marked as "canceled"
  • Access: Features remain until period end
  • Billing: No further charges after period end
  • Data: All data retained
  • Reactivation: Can reactivate before period end

Reactivating Subscription

  1. Access customer portal
  2. Click Reactivate Subscription
  3. Subscription reactivated immediately
  4. Billing resumes

Updating Payment Methods

Via Customer Portal

  1. Access customer portal
  2. Navigate to Payment Methods
  3. Click Add Payment Method or Update
  4. Enter new payment information
  5. Save changes

Payment Method Requirements

  • Valid credit/debit card
  • Billing address
  • Card expiration date
  • CVV code

Viewing Billing History

Via Customer Portal

  1. Access customer portal
  2. Navigate to Billing History
  3. View past invoices
  4. Download PDF invoices

Via API

# Note: Billing history may be available via Stripe API
# Check API reference for current implementation

Subscription Status

Status Types

  • trial: Free trial period
  • active: Active paid subscription
  • canceled: Canceled but active until period end
  • past_due: Payment failed, retrying
  • unpaid: Payment failed, access may be restricted

Checking Status

curl -X GET https://your-domain.com/api/billing/summary \
  -H "Authorization: Bearer <your-jwt-token>"

Response includes:

{
  "status": "active",
  "trial_ends_at": null,
  "activated_at": "2025-01-15T10:00:00Z"
}

Best Practices

Subscription Management

  1. Monitor Usage: Track usage to avoid overage
  2. Review Regularly: Review subscription quarterly
  3. Plan Ahead: Upgrade before hitting limits
  4. Keep Updated: Keep payment method current

Plan Changes

  1. Assess First: Evaluate if plan change is needed
  2. Check Timing: Consider billing cycle timing
  3. Understand Effects: Know what changes with plan
  4. Test Features: Test new features after upgrade

Troubleshooting

Can't Access Portal

Problem: "Failed to create portal session"

  • Solution: Check Stripe configuration
  • Check: Verify STRIPE_SECRET_KEY is set
  • Try: Ensure Stripe customer ID exists

Plan Change Fails

Problem: "Plan change failed" error

  • Solution: Check Stripe subscription status
  • Check: Verify payment method is valid
  • Try: Contact support

Payment Method Update Fails

Problem: "Payment method update failed"

  • Solution: Verify card information is correct
  • Check: Ensure card is not expired
  • Try: Use different payment method

Related Documentation

Next Steps

Next: Usage Tracking → Learn how to track usage and overage