> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Architecture for the Subscription Status endpoint

## 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

```mermaid theme={null}
flowchart TD
    Request["GET /api/subscription-status"]
    
    subgraph auth [Authentication]
        GetOrg["Get org_id from JWT"]
    end
    
    subgraph db [Database]
        GetSubId["Get stripe_subscription_id"]
    end
    
    subgraph stripe [Stripe API]
        RetrieveSub["Retrieve subscription"]
        CheckStatus["Check status == trialing"]
        CalcDays["Calculate days_remaining"]
    end
    
    Request --> GetOrg
    GetOrg --> GetSubId
    GetSubId --> RetrieveSub
    RetrieveSub --> CheckStatus
    CheckStatus --> CalcDays
    CalcDays --> Response["Response"]
```

## 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**:

```python theme={null}
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

```json theme={null}
{
  "status": "trialing",
  "trial_end": 1736899200,
  "days_remaining": 7
}
```

| Field            | Type        | Description                            |
| ---------------- | ----------- | -------------------------------------- |
| `status`         | string      | Stripe subscription status             |
| `trial_end`      | int \| null | Unix timestamp when trial ends         |
| `days_remaining` | int \| null | Days 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
```