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

# Subscription trials

> Offer free trials on recurring subscription tiers without requiring a payment method upfront.

crxbase supports Stripe-managed free trials for recurring subscriptions. When you configure a trial duration on a tier, eligible users can start a no-card trial directly from the pricing page.

## How it works

<Steps>
  <Step title="Configure trial duration">
    Choose a free trial duration (7, 14, or 30 days) on a tier in your dashboard. The trial applies to all recurring prices (monthly and yearly) in that
    tier. One-time (lifetime) prices are not affected.
  </Step>

  <Step title="User starts a trial">
    An eligible authenticated user sees a **Start X-day trial** button on qualifying recurring prices. Clicking it creates a Stripe Checkout session that
    starts a subscription trial without collecting a payment method.
  </Step>

  <Step title="Trial is active">
    During the trial, the user has full paid access. The library's `getUser()` returns `paid: true` with `status: 'trialing'` and `trial_end` on the plan
    entry while the trial period is current. `trial_available` is `false`.
  </Step>

  <Step title="Trial ends">
    When the trial expires, Stripe moves the subscription to `active` (if a payment method was added) or cancels it. The user's plan status updates
    automatically.
  </Step>
</Steps>

## Eligibility

Each end-user gets **one free trial per extension**. Once a trial has been started — even if canceled early — the user cannot start another trial for the same extension.

| Condition                                    | Trial offered? |
| -------------------------------------------- | -------------- |
| Tier has a trial duration configured         | Yes            |
| User has not used a trial for this extension | Yes            |
| User already used a trial for this extension | No             |
| User has an active or past\_due plan         | No (Switch UI) |
| Price is one-time (lifetime)                 | No             |

<Tip>
  If you need to test trial UI repeatedly during development, use [developer testing](/guides/platform/developer-testing/) on the pricing page. That override
  only affects your own test account and does not change the one-trial-per-extension rule for real end users.
</Tip>

## Switching during a trial

If a user with a trialing subscription switches to a different recurring plan:

1. They see a warning that switching **ends the current trial immediately**.
2. After confirming, the trial subscription is canceled and a fresh **paid checkout** is created for the target plan.
3. Remaining trial time does **not** carry over to the new plan.
4. If the user abandons the paid checkout, the trial remains canceled — there is no way to restore it.

<Warning>
  Switching during a trial is irreversible. The user is warned before confirming, but once the switch is initiated, the remaining trial time is consumed.
</Warning>

## Trial reminder emails

crxbase does **not** send trial reminder or expiry emails. These depend on the Stripe Billing settings of each developer's connected Stripe account.

To configure trial reminders, go to **Stripe Dashboard → Settings → Billing → Subscriptions and emails** on your Stripe account and enable the relevant customer email settings.

## API and library

### getUser()

For a trialing user, the response includes:

* `paid: true`
* `trial_available: false`
* A plan entry with `status: 'trialing'`, `trial_end`, and `period_end` (ISO timestamps)

### getTiers()

For a trial-enabled tier, the response includes `trial_days` on the tier object.

<Tip>You can use `trial_available` and `trial_end` in your extension to show trial-specific messaging, such as "X days left in your trial".</Tip>

## What you need to do

1. Choose a free trial duration (7, 14, or 30 days) on the tier(s) you want to offer trials for in your **Tiers** settings.
2. Optionally configure trial reminder emails in your Stripe dashboard.
3. The pricing page, checkout, and library automatically handle trial eligibility and lifecycle.