Skip to main content

​
Purpose

Retrieves subscription status directly from Stripe, including trial period information. This enables the frontend to display how many days remain in a user’s free trial.

​
Architecture

​
How Trial Days Are Calculated

  1. Retrieve Subscription: Fetch the subscription object from Stripe using stripe.Subscription.retrieve(subscription_id)
  2. Check Status: Verify subscription.status === "trialing"
  3. Get Trial End: Extract subscription.trial_end (Unix timestamp in seconds)
  4. Calculate Remaining Days: 
from datetime import datetime, timezone

now = datetime.now(timezone.utc)
trial_end_dt = datetime.fromtimestamp(trial_end, tz=timezone.utc)
delta = trial_end_dt - now
days_remaining = max(0, delta.days)

​
Response Format

{
  "status": "trialing",
  "trial_end": 1736899200,
  "days_remaining": 7
}
FieldTypeDescription
statusstringStripe subscription status
trial_endint | nullUnix timestamp when trial ends
days_remainingint | nullDays left in trial (0 if ending today)

​
Fallback Behavior

If Stripe API fails, the endpoint falls back to returning the subscription_status stored in clerk_organization_details table, with trial_end and days_remaining as null.

​
Code Location

src/app/apis/settings_billing/subscription_status/routes.py