Skip to main content

​
Create subscription

POST /api/subscriptions
Auth: web.api Creates a Stripe subscription for the tutor. Supports trial periods. Handler: SubscriptionService::subscribe()

​
Get billing portal

GET /api/subscriptions/portal
Auth: auth:api Returns Stripe Customer Portal URLs for self-service management: 
{
  "actions": [
    {
      "type": "update_payment_method",
      "url": "https://billing.stripe.com/..."
    },
    {
      "type": "cancel",
      "url": "https://billing.stripe.com/..."
    }
  ]
}

​
Subscription webhook

POST /api/subscriptions/webhooks
Auth: None (public — secured via Stripe signature verification) Handler: StripeService::handleSubscriptionWebhook() Validates webhook signature using STRIPE_SUBSCRIPTION_SIGNING_SECRET. Updates subscription status in the database.

​
Subscription statuses

StatusMeaning
trialingIn free trial period
activeActive and paying
canceledCancelled (soft-deleted)
incompletePayment failed, awaiting retry
incomplete_expiredPayment failed, subscription ended
Checked via Subscription::isValid() — returns true for trialing or active.

​
Subscription products

Defined in subscription_products table:
FieldPurpose
product_idStripe product ID
price_idStripe price ID
trial_periodTrial duration