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

# Get Subscription Status

> Get subscription status including trial days remaining from Stripe

Retrieves the current subscription status directly from Stripe, including trial information if the subscription is in a trial period.

<Note>
  **Authentication Required**: This endpoint requires a Clerk JWT token with
  organization context. The organization is determined from the `org_id` claim
  in the token.
</Note>

## Request Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with organization context: `Bearer {clerk_jwt_token}`
</ParamField>

## Response

<ResponseField name="status" type="string">
  Subscription status from Stripe: `trialing`, `active`, `canceled`, `past_due`, `unpaid`, `incomplete`, `incomplete_expired`, or `none` if no subscription exists.
</ResponseField>

<ResponseField name="trial_end" type="integer | null">
  Unix timestamp (seconds) when the trial ends. Only present if `status` is `trialing`.
</ResponseField>

<ResponseField name="days_remaining" type="integer | null">
  Number of days remaining in the trial period. Only present if `status` is `trialing`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://searchcompany-main.up.railway.app/api/subscription-status \
    -H "Authorization: Bearer YOUR_CLERK_JWT_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json Trialing Response theme={null}
  {
    "status": "trialing",
    "trial_end": 1736899200,
    "days_remaining": 7
  }
  ```

  ```json Active Response theme={null}
  {
    "status": "active",
    "trial_end": null,
    "days_remaining": null
  }
  ```

  ```json No Subscription theme={null}
  {
    "status": "none",
    "trial_end": null,
    "days_remaining": null
  }
  ```
</ResponseExample>

## Errors

| Status | Description                             |
| ------ | --------------------------------------- |
| 401    | Missing or invalid authentication token |
| 401    | No organization context in token        |
| 404    | Organization not found                  |
| 500    | Database not configured                 |

## Usage

```javascript theme={null}
// Get token with organization context
const token = await getToken({ organizationId: organization.id });

const response = await fetch("/api/subscription-status", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const { status, days_remaining } = await response.json();

if (status === "trialing" && days_remaining !== null) {
  console.log(`Trial ends in ${days_remaining} days`);
}
```