> ## Documentation Index
> Fetch the complete documentation index at: https://better-auth-razorpay.amankushwaha.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Database schema

> Tables and fields added by the Razorpay plugin, migration commands, and how to customize them.

The Razorpay plugin extends your existing Better Auth schema with Razorpay customer ids and, when subscriptions are enabled, a dedicated `subscription` table. This page describes every field, the subscription status lifecycle, how to run migrations, and how to rename or remap fields using the `schema` option.

## User fields

| Field | Type | Description |
| - | - | - |
| `razorpayCustomerId` | `string` (optional) | Razorpay customer id created when `createCustomerOnSignUp` is `true` or when a subscription is upgraded for the user. |

## Organization fields

When `organization: { enabled: true }` is set, the `organization` table also receives:

| Field | Type | Description |
| - | - | - |
| `razorpayCustomerId` | `string` (optional) | Razorpay customer id for the organization. |

## Subscription table

The `subscription` table is created only when `subscription.enabled` is `true`.

| Field | Type | Default | Description |
| - | - | - | - |
| `id` | `string` | None | Local primary key. |
| `plan` | `string` | None | Internal plan name matched case-insensitively (stored in lowercase). |
| `referenceId` | `string` | None | User id or organization id the subscription belongs to. |
| `razorpayCustomerId` | `string` | None | Linked Razorpay customer id. |
| `razorpaySubscriptionId` | `string` | None | Razorpay subscription id (`sub_XXXX`). |
| `razorpayPlanId` | `string` | None | Razorpay plan id (`plan_XXXX`). |
| `status` | `string` | `"created"` | Current lifecycle status. |
| `currentStart` | `date` | None | Start of the current billing cycle. |
| `currentEnd` | `date` | None | End of the current billing cycle. |
| `endedAt` | `date` | None | Timestamp when the subscription ended. |
| `quantity` | `number` | `1` | Seat or item quantity. |
| `totalCount` | `number` | `0` | Total billing cycles configured (0 means no limit). |
| `paidCount` | `number` | `0` | Number of successfully paid billing cycles. |
| `remainingCount` | `number` | None | Billing cycles remaining. |
| `cancelledAt` | `date` | None | Timestamp when the subscription was cancelled. |
| `pausedAt` | `date` | None | Timestamp when the subscription was paused. |
| `shortUrl` | `string` | None | Razorpay hosted authorization link. |
| `cancelAtCycleEnd` | `boolean` | `false` | Whether cancellation is scheduled at the end of the current cycle. |
| `groupId` | `string` | None | Razorpay subscription group id, if any. |
| `billingPeriod` | `string` | None | `"monthly"` or `"yearly"`. |
| `trialStart` | `date` | None | Start of the trial period. |
| `trialEnd` | `date` | None | End of the trial period. |
| `metadata` | `JSON string` | None | Additional metadata stored as a JSON string. |
| `renewedAt` | `date` | None | Timestamp of the most recent renewal. |

## Subscription statuses

| Status | Meaning |
| - | - |
| `created` | The subscription was created locally but has not been authenticated by the customer yet. |
| `authenticated` | The customer has authorized the payment method on Razorpay. |
| `active` | The subscription is live and billing cycles are running. |
| `pending` | The subscription is awaiting an action, such as authentication or a pending update. |
| `halted` | Razorpay has halted the subscription because of repeated payment failures. |
| `cancelled` | The subscription was cancelled either immediately or after the current cycle ended. |
| `completed` | All configured billing cycles have been paid and the subscription is finished. |
| `expired` | The subscription expired, for example because the authorization link was not used in time. |
| `paused` | The subscription was paused and billing is temporarily stopped. |

## Migrations

After installing the plugin and configuring your schema, run the Better Auth CLI to generate and apply migrations.

```bash theme={null}
# Generate migration files from the plugin schema
npx @better-auth/cli generate

# Or apply directly if your setup supports it
npx @better-auth/cli migrate
```

> [!NOTE]
>
> The exact migration output depends on your database adapter (Prisma, Drizzle, or others). Always review the generated migration before applying it in production.

## Customizing the schema

You can rename the subscription table or remap individual fields using the `schema` plugin option. This follows Better Auth's plugin schema customization convention.

```ts auth.ts theme={null}
import { betterAuth } from "better-auth";
import { razorpay } from "@amank-root/better-auth-razorpay";

export const auth = betterAuth({
  plugins: [
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      subscription: {
        enabled: true,
        plans: [{ planId: "plan_XXXX", name: "pro" }],
      },
      schema: {
        subscription: {
          modelName: "billing_subscription",
          fields: {
            referenceId: "reference_id",
            razorpayCustomerId: "razorpay_customer_id",
            razorpaySubscriptionId: "razorpay_subscription_id",
            razorpayPlanId: "razorpay_plan_id",
            currentStart: "current_start",
            currentEnd: "current_end",
            endedAt: "ended_at",
            paidCount: "paid_count",
            remainingCount: "remaining_count",
            cancelledAt: "cancelled_at",
            pausedAt: "paused_at",
            shortUrl: "short_url",
            cancelAtCycleEnd: "cancel_at_cycle_end",
            groupId: "group_id",
            billingPeriod: "billing_period",
            trialStart: "trial_start",
            trialEnd: "trial_end",
            renewedAt: "renewed_at",
          },
        },
      },
    }),
  ],
});
```

In the example above:

* `modelName` renames the table from `subscription` to `billing_subscription`.
* Each key inside `fields` maps the internal field name to your preferred column name.

> [!TIP]
>
> If you only need to rename a few fields, include only those keys in `fields`. Unmapped fields keep their default names.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.