Stripe

The Stripe plugin integrates Stripe's payment and subscription functionality with Better Auth. Since payment and authentication are often tightly coupled, this plugin simplifies the integration of Stripe into your application, handling customer creation, subscription management, and webhook processing.

Features

• Create Stripe Customers automatically when users sign up
• Manage subscription plans and pricing
• Process subscription lifecycle events (creation, updates, cancellations)
• Handle Stripe webhooks securely with signature verification
• Expose subscription data to your application
• Support for trial periods and subscription upgrades
• Automatic trial abuse prevention - Users can only get one trial per account across all plans
• Flexible reference system to associate subscriptions with users or organizations
• Team subscription support with seats management

Installation

First, install the plugin:

```package-install
@better-auth/stripe
```

<Callout>
  If you're using a separate client and server setup, make sure to install the plugin in both parts of your project.
</Callout>

Next, install the Stripe SDK on your server:

```package-install
stripe@^22.0.0
```

```ts title="auth.ts"
import { betterAuth } from "better-auth"
import { stripe } from "@better-auth/stripe"
import Stripe from "stripe"

const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    apiVersion: "2026-03-25.dahlia", // Latest API version as of Stripe SDK v22.0.0
})

export const auth = betterAuth({
    // ... your existing config
    plugins: [
        stripe({
            stripeClient,
            stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
            createCustomerOnSignUp: true,
        })
    ]
})
```

<Callout type="info">
  **Upgrading from Stripe v18?** Version 19 uses async webhook signature verification (`constructEventAsync`) which is handled internally by the plugin. No code changes required on your end!
</Callout>

```ts title="auth-client.ts"
import { createAuthClient } from "better-auth/client"
import { stripeClient } from "@better-auth/stripe/client"

export const authClient = createAuthClient({
    // ... your existing config
    plugins: [
        stripeClient({
            subscription: true //if you want to enable subscription management
        })
    ]
})
```

Run the migration or generate the schema to add the necessary tables to the database.

<Tabs items={["migrate", "generate"]}>
  <Tab value="migrate">
    ```package-install
    npx auth migrate
    ```
  </Tab>

  <Tab value="generate">
    ```package-install
    npx auth generate
    ```
  </Tab>
</Tabs>

See the [Schema](#schema) section to add the tables manually.

Create a webhook endpoint in your Stripe dashboard pointing to:

```
https://your-domain.com/api/auth/stripe/webhook
```

`/api/auth` is the default path for the auth server.

Make sure to select at least these events:

* `checkout.session.completed`
* `customer.subscription.created`
* `customer.subscription.updated`
* `customer.subscription.deleted`

Save the webhook signing secret provided by Stripe and add it to your environment variables as `STRIPE_WEBHOOK_SECRET`.

Usage

Customer Management

You can use this plugin solely for customer management without enabling subscriptions. This is useful if you just want to link Stripe customers to your users.

When you set createCustomerOnSignUp: true, a Stripe customer is automatically created on signup and linked to the user in your database. You can customize the customer creation process:

stripe({
    // ... other options
    createCustomerOnSignUp: true,
    onCustomerCreate: async ({ stripeCustomer, user }, ctx) => {
        // Do something with the newly created customer
        console.log(`Customer ${stripeCustomer.id} created for user ${user.id}`);
    },
    getCustomerCreateParams: async (user, ctx) => {
        // Customize the Stripe customer creation parameters
        return {
            metadata: {
                referralSource: user.metadata?.referralSource
            }
        };
    }
})

Subscription Management

Defining Plans

You can define your subscription plans either statically or dynamically:

// Static plans
subscription: {
    enabled: true,
    plans: [
        {
            name: "basic", // the name of the plan, it'll be automatically lower cased when stored in the database
            priceId: "price_1234567890", // the price ID from stripe
            annualDiscountPriceId: "price_1234567890", // (optional) the price ID for annual billing with a discount
            limits: {
                projects: 5,
                storage: 10
            }
        },
        {
            name: "pro",
            priceId: "price_0987654321",
            limits: {
                projects: 20,
                storage: 50
            },
            freeTrial: {
                days: 14,
            }
        }
    ]
}

// Dynamic plans (fetched from database or API)
subscription: {
    enabled: true,
    plans: async () => {
        const plans = await db.query("SELECT * FROM plans");
        return plans.map(plan => ({
            name: plan.name,
            priceId: plan.stripe_price_id,
            limits: JSON.parse(plan.limits)
        }));
    }
}

see plan configuration for more.

Creating a Subscription

To create a subscription, use the subscription.upgrade method:

Simple Example:

await authClient.subscription.upgrade({
    plan: "pro",
    successUrl: "/dashboard",
    cancelUrl: "/pricing",
    annual: true, // Optional: upgrade to an annual plan
    referenceId: "org_123", // Optional: defaults based on customerType
    seats: 5, // Optional: for team plans
    locale: "en" // Optional: display checkout in English
});

This will create a Checkout Session and redirect the user to the Stripe Checkout page.

If the user already has an active subscription, you must provide the subscriptionId parameter when upgrading. Otherwise, a new subscription may be created alongside the existing one, resulting in duplicate billing. </Callout>

Important: The successUrl parameter will be internally modified to handle race conditions between checkout completion and webhook processing. The plugin creates an intermediate redirect that ensures subscription status is properly updated before redirecting to your success page.

const { error } = await authClient.subscription.upgrade({
    plan: "pro",
    successUrl: "/dashboard",
    cancelUrl: "/pricing",
});
if(error) {
    alert(error.message);
}

Switching Plans

To switch a subscription to a different plan, use the subscription.upgrade method:

await authClient.subscription.upgrade({
    plan: "pro",
    successUrl: "/dashboard",
    cancelUrl: "/pricing",
    subscriptionId: "sub_123", // the Stripe subscription ID of the user's current plan
});

This ensures that the user only pays for the new plan, and not both.

Scheduling Plan Changes at Period End

By default, plan changes take effect immediately with prorated billing. You may want to defer the change to the end of the current billing period so the user can continue using their current plan until it expires:

await authClient.subscription.upgrade({
    plan: "pro",
    successUrl: "/dashboard",
    cancelUrl: "/pricing",
    returnUrl: "/billing",
    scheduleAtPeriodEnd: true, // [!code highlight] Default: false
});

This uses the Stripe Subscription Schedules API to create a two-phase schedule: the current plan continues until the billing period ends, then the new plan starts automatically with no proration.

• The subscription plan is not changed until the billing period ends — only stripeScheduleId is stored so clients can detect the pending change
• No redirect to Stripe Checkout or Billing Portal occurs, the change is applied server-side
• At the end of the billing period, Stripe fires a customer.subscription.updated webhook which updates the subscription record automatically
• If a new upgrade or schedule is requested before the period ends, the existing pending schedule is released first </Callout>

Listing Active Subscriptions

To get the user's active subscriptions:

// get the active subscription const activeSubscription = subscriptions.find( sub => sub.status === "active" || sub.status === "trialing" );

// Check subscription limits const projectLimit = subscriptions?.limits?.projects || 0;

</APIMethod>

Make sure to provide `authorizeReference` in your plugin config to authorize the reference ID

```ts title="auth.ts"
stripe({
  // ... other options
  subscription: {
      // ... other subscription options
      authorizeReference: async ({ user, session, referenceId, action }) => {
          if(action === "list-subscription") {
              const org = await db.member.findFirst({
                  where: {
                      organizationId: referenceId,
                      userId: user.id
                  }   
              });
              return org?.role === "owner"
          }
          // Check if the user has permission to list subscriptions for this reference
          return true;
      }
  }
})

Canceling a Subscription

To cancel a subscription:

This will redirect the user to the Stripe Billing Portal where they can cancel their subscription.

Stripe supports different types of cancellation, and the plugin tracks all of them:

Restoring a Subscription

<small className="font-normal">Note: This only works for subscriptions that are still active but have a pending cancellation or a scheduled plan change. It cannot restore subscriptions that have already ended (status: "canceled" with endedAt set).</small>

If a user changes their mind after canceling a subscription or scheduling a plan change, you can restore the subscription:

• Pending cancellation: Sets cancelAtPeriodEnd to false and clears cancelAt / canceledAt, so the subscription continues to renew.
• Pending plan change (via scheduleAtPeriodEnd): Releases the Stripe subscription schedule and clears stripeScheduleId, so the current plan remains unchanged. </Callout>

Creating Billing Portal Sessions

To create a Stripe billing portal session where customers can manage their subscriptions, update payment methods, and view billing history:

This endpoint creates a Stripe billing portal session and returns a URL in the response as data.url. You can redirect users to this URL to allow them to manage their subscription, payment methods, and billing history.

Reference System

By default, subscriptions are associated with the user ID. However, you can use a custom reference ID to associate subscriptions with other entities, such as organizations:

// Create a subscription for an organization
await authClient.subscription.upgrade({
    plan: "pro",
    referenceId: "org_123456",
    successUrl: "/dashboard",
    cancelUrl: "/pricing",
    seats: 5 // Number of seats for team plans
});

// List subscriptions for an organization
const { data: subscriptions } = await authClient.subscription.list({
    query: {
        referenceId: "org_123456"
    }
});

Team Subscriptions with Seats

For team or organization plans, you can specify the number of seats:

await authClient.subscription.upgrade({
    plan: "team",
    referenceId: "org_123456",
    seats: 10, // 10 team members
    successUrl: "/org/billing/success",
    cancelUrl: "/org/billing"
});

The seats parameter is passed to Stripe as the quantity for the subscription item. You can use this value in your application logic to limit the number of members in a team or organization.

To authorize reference IDs, implement the authorizeReference function:

subscription: {
    // ... other options
    authorizeReference: async ({ user, session, referenceId, action }) => {
        // Check if the user has permission to manage subscriptions for this reference
        if (action === "upgrade-subscription" || action === "cancel-subscription" || action === "restore-subscription") {
            const org = await db.member.findFirst({
                where: {
                    organizationId: referenceId,
                    userId: user.id
                }   
            });
            return org?.role === "owner"
        }
        return true;
    }
}

Webhook Handling

The plugin automatically handles common webhook events:

• checkout.session.completed: Updates subscription status after checkout
• customer.subscription.created: Creates a subscription when created outside the checkout flow
• customer.subscription.updated: Updates subscription details when changed
• customer.subscription.deleted: Marks subscription as canceled

You can also handle custom events:

stripe({
    // ... other options
    onEvent: async (event) => {
        // Handle any Stripe event
        switch (event.type) {
            case "invoice.paid":
                // Handle paid invoice
                break;
            case "payment_intent.succeeded":
                // Handle successful payment
                break;
        }
    }
})

Subscription Lifecycle Hooks

You can hook into various subscription lifecycle events:

subscription: {
    // ... other options
    onSubscriptionComplete: async ({ event, subscription, stripeSubscription, plan }) => {
        // Called when a subscription is successfully created via checkout
        await sendWelcomeEmail(subscription.referenceId, plan.name);
    },
    onSubscriptionCreated: async ({ event, subscription, stripeSubscription, plan }) => {
        // Called when a subscription is created outside the checkout flow (e.g. Stripe dashboard)
        await sendSubscriptionCreatedEmail(subscription.referenceId, plan.name);
    },
    onSubscriptionUpdate: async ({ event, subscription, stripeSubscription }) => {
        // Called when a subscription is updated. Use `stripeSubscription` for raw Stripe fields like `cancellation_details`.
        console.log(`Subscription ${subscription.id} updated`);
    },
    onSubscriptionCancel: async ({ event, subscription, stripeSubscription, cancellationDetails }) => {
        // Called when a subscription is canceled
        await sendCancellationEmail(subscription.referenceId);
    },
    onSubscriptionDeleted: async ({ event, subscription, stripeSubscription }) => {
        // Called when a subscription is deleted
        console.log(`Subscription ${subscription.id} deleted`);
    }
}

Trial Periods

You can configure trial periods for your plans:

{
    name: "pro",
    priceId: "price_0987654321",
    freeTrial: {
        days: 14,
        onTrialStart: async (subscription) => {
            // Called when a trial starts
            await sendTrialStartEmail(subscription.referenceId);
        },
        onTrialEnd: async ({ subscription }, ctx) => {
            // Called when a trial ends
            await sendTrialEndEmail(subscription.referenceId);
        },
        onTrialExpired: async (subscription, ctx) => {
            // Called when a trial expires without conversion
            await sendTrialExpiredEmail(subscription.referenceId);
        }
    }
}

Schema

The Stripe plugin adds the following tables to your database:

User

Table Name: user

export const stripeUserTableFields = [ { name: "stripeCustomerId", type: "string", description: "The Stripe customer ID", isOptional: true, }, ];

Organization

Table Name: organization <small className="text-xs">(only when organization.enabled is true)</small>

export const stripeOrganizationTableFields = [ { name: "stripeCustomerId", type: "string", description: "The Stripe customer ID for the organization", isOptional: true, }, ];

Subscription

Table Name: subscription

export const stripeSubscriptionTableFields = [ { name: "id", type: "string", description: "Unique identifier for each subscription", isPrimaryKey: true, }, { name: "plan", type: "string", description: "The name of the subscription plan", }, { name: "referenceId", type: "string", description: "The ID this subscription is associated with (user ID by default). This should NOT be a unique field in your database, as it must allow users to resubscribe after a cancellation.", isUnique: false, }, { name: "stripeCustomerId", type: "string", description: "The Stripe customer ID", isOptional: true, }, { name: "stripeSubscriptionId", type: "string", description: "The Stripe subscription ID", isOptional: true, }, { name: "status", type: "string", description: "The status of the subscription (active, canceled, etc.)", defaultValue: "incomplete", }, { name: "periodStart", type: "Date", description: "Start date of the current billing period", isOptional: true, }, { name: "periodEnd", type: "Date", description: "End date of the current billing period", isOptional: true, }, { name: "cancelAtPeriodEnd", type: "boolean", description: "Whether the subscription will be canceled at the end of the period", defaultValue: false, isOptional: true, }, { name: "cancelAt", type: "Date", description: "If the subscription is scheduled to be canceled, this is the time at which the cancellation will take effect", isOptional: true, }, { name: "canceledAt", type: "Date", description: "If the subscription has been canceled, this is the time when the cancellation was requested. Note: If the subscription was canceled with cancelAtPeriodEnd, this reflects the cancellation request time, not when the subscription actually ends", isOptional: true, }, { name: "endedAt", type: "Date", description: "If the subscription has ended, this is the date the subscription ended", isOptional: true, }, { name: "seats", type: "number", description: "Number of seats for team plans", isOptional: true, }, { name: "trialStart", type: "Date", description: "Start date of the trial period", isOptional: true, }, { name: "trialEnd", type: "Date", description: "End date of the trial period", isOptional: true, }, { name: "billingInterval", type: "string", description: "The billing interval of the subscription (e.g. 'month', 'year')", isOptional: true, }, { name: "stripeScheduleId", type: "string", description: "Stripe Subscription Schedule ID, present when a scheduled plan change is pending", isOptional: true, }, ];

Customizing the Schema

To change the schema table names or fields, you can pass a schema option to the Stripe plugin:

stripe({
    // ... other options
    schema: {
        subscription: {
            modelName: "stripeSubscriptions", // map the subscription table to stripeSubscriptions
            fields: {
                plan: "planName" // map the plan field to planName
            }
        }
    }
})

Options

Subscription Options

Plan Configuration

Free Trial Configuration

Organization Options

Advanced Usage

Using with Organizations

The Stripe plugin integrates with the organization plugin to enable organizations as Stripe Customers. Instead of individual users, organizations become the billing entity for subscriptions. This is useful for B2B services where billing is tied to the organization rather than individual user.

• A Stripe Customer is automatically created when an organization first subscribes
• Organization name changes are synced to the Stripe Customer
• Organizations with active subscriptions cannot be deleted </Callout>

Enabling Organization Customer

To enable Organization Customer, set organization.enabled to true and ensure the organization plugin is installed:

plugins: [
    organization(),
    stripe({
        // ... other options
        subscription: {
            enabled: true,
            plans: [...],
        },
        organization: { // [!code highlight]
            enabled: true // [!code highlight]
        } // [!code highlight]
    })
]

Creating Organization Subscriptions

Even with Organization Customer enabled, user subscriptions remain available and are the default. To use the organization as the billing entity, pass customerType: "organization":

await authClient.subscription.upgrade({
    plan: "team",
    referenceId: activeOrg.id,
    customerType: "organization", // [!code highlight]
    seats: 10,
    successUrl: "/org/billing/success",
    cancelUrl: "/org/billing"
});

Authorization

Make sure to implement the authorizeReference function to verify that the user has permission to manage subscriptions for the organization:

subscription: {
    // ... other subscription options
    authorizeReference: async ({ user, referenceId, action }) => {
        const member = await db.members.findFirst({
            where: {
                userId: user.id,
                organizationId: referenceId
            }
        });

        return member?.role === "owner" || member?.role === "admin";
    }
}

Organization Billing Email

Unlike users, organization billing email is not automatically synced because organization itself doesn't have a unique email. Organizations often use a dedicated billing email separate from user accounts. To change the billing email after checkout, update it through the Stripe Dashboard or implement custom logic using stripeClient:

await stripeClient.customers.update(organization.stripeCustomerId, {
    email: "[email protected]"
});

Handling user deletion

Organizations with active subscriptions are blocked from deletion automatically, but users are not. To mirror the same behavior on user deletion, throw from the beforeDelete callback when a subscription is active:

import { betterAuth } from "better-auth";
import { APIError } from "better-auth/api";

export const auth = betterAuth({
    user: {
        deleteUser: {
            enabled: true,
            beforeDelete: async (user) => {
                if (!user.stripeCustomerId) return;

                for await (const sub of stripeClient.subscriptions.list({
                    customer: user.stripeCustomerId,
                    status: "all",
                })) {
                    if (["canceled", "incomplete", "incomplete_expired"].includes(sub.status)) continue;

                    throw new APIError("BAD_REQUEST", {
                        message: "Cancel your active subscription before deleting your account",
                    });
                    // Or cancel immediately: await stripeClient.subscriptions.cancel(sub.id);
                    // Or at period end:      await stripeClient.subscriptions.update(sub.id, { cancel_at_period_end: true });
                }
            },
        },
    },
});

Custom Checkout Session Parameters

You can customize the Stripe Checkout session with additional parameters:

getCheckoutSessionParams: async ({ user, session, plan, subscription }, ctx) => {
    return {
        params: {
            allow_promotion_codes: true,
            tax_id_collection: {
                enabled: true
            },
            billing_address_collection: "required",
            custom_text: {
                submit: {
                    message: "We'll start your subscription right away"
                }
            },
            metadata: {
                planType: "business",
                referralCode: user.metadata?.referralCode
            }
        },
        options: {
            idempotencyKey: `sub_${user.id}_${plan.name}_${Date.now()}`
        }
    };
}

Tax Collection

To collect tax IDs from the customer, set tax_id_collection to true:

subscription: {
    // ... other options
    getCheckoutSessionParams: async ({ user, session, plan, subscription }, ctx) => {
        return {
            params: {
                tax_id_collection: {
                    enabled: true
                }
            }
        };
    }
}

Automatic Tax Calculation

To enable automatic tax calculation using the customer's location, set automatic_tax to true. Enabling this parameter causes Checkout to collect any billing address information necessary for tax calculation. You need to have tax registration setup and configured in the Stripe dashboard first for this to work.

subscription: {
    // ... other options
    getCheckoutSessionParams: async ({ user, session, plan, subscription }, ctx) => {
        return {
            params: {
                automatic_tax: {
                    enabled: true
                }
            }
        };
    }
}

Trial Period Management

The Stripe plugin automatically prevents users from getting multiple free trials. Once a user has used a trial period (regardless of which plan), they will not be eligible for additional trials on any plan.

How it works:

• The system tracks trial usage across all plans for each user
• When a user subscribes to a plan with a trial, the system checks their subscription history
• If the user has ever had a trial (indicated by trialStart/trialEnd fields or trialing status), no new trial will be offered
• This prevents abuse where users cancel subscriptions and resubscribe to get multiple free trials

Example scenario:

1. User subscribes to "Starter" plan with 7-day trial
2. User cancels the subscription after the trial
3. User tries to subscribe to "Premium" plan - no trial will be offered
4. User will be charged immediately for the Premium plan

This behavior is automatic and requires no additional configuration. The trial eligibility is determined at the time of subscription creation and cannot be overridden through configuration.

Troubleshooting

Webhook Issues

If webhooks aren't being processed correctly:

1. Check that your webhook URL is correctly configured in the Stripe dashboard
2. Verify that the webhook signing secret is correct
3. Ensure you've selected all the necessary events in the Stripe dashboard
4. Check your server logs for any errors during webhook processing

Subscription Status Issues

If subscription statuses aren't updating correctly:

1. Make sure the webhook events are being received and processed
2. Check that the stripeCustomerId and stripeSubscriptionId fields are correctly populated
3. Verify that the reference IDs match between your application and Stripe

Testing Webhooks Locally

For local development, you can use the Stripe CLI to forward webhooks to your local environment:

stripe listen --forward-to localhost:3000/api/auth/stripe/webhook

This will provide you with a webhook signing secret that you can use in your local environment.