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

# Seat-based billing

> Charge per seat by using plan quantity, updating subscription seats, and syncing organization member counts automatically with better-auth-razorpay.

The better-auth-razorpay plugin supports seat-based billing by using the `quantity` field on subscriptions. You can set a default quantity in the plan config, update it manually through the API, or let the plugin sync it automatically when organization members are added or removed.

## Plan quantity

Set `quantity` on a plan to define the default number of seats included in the subscription. The value is stored on the local subscription row and passed to Razorpay when the subscription is created.

```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!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
      createCustomerOnSignUp: true,
      subscription: {
        enabled: true,
        plans: [
          {
            planId: "plan_monthly_team",
            annualPlanId: "plan_annual_team",
            name: "team",
            totalCount: 12,
            quantity: 5, // default 5 seats
            limits: { projects: 50, storage: 500 },
          },
        ],
      },
    }),
  ],
});
```

> [!NOTE]
>
> `quantity: false` disables quantity tracking for that plan. `quantity: 1` or higher enables seat-based billing.

## Updating quantity manually

Call `subscription.update` to change the seat count at any time. You can apply the change immediately or schedule it for the end of the current billing cycle.

```ts theme={null}
// Increase seats immediately
const { data, error } = await authClient.subscription.update({
  quantity: 10,
  scheduleChangeAt: "now",
});

// Decrease seats at cycle end (prorated until then)
const { data, error } = await authClient.subscription.update({
  quantity: 3,
  scheduleChangeAt: "cycle_end",
});
```

**quantity** `number` *required*

New seat count. Must be a positive integer.

**scheduleChangeAt** `string`

`"now"` applies immediately. `"cycle_end"` applies after the current period ends.

Razorpay prorates seat changes based on your plan settings. The plugin returns the updated local subscription and the Razorpay subscription object.

## Automatic seat sync for organizations

When you enable the Better Auth `organization` plugin and set `organization: { enabled: true }` in the Razorpay plugin, seat counts sync automatically:

* **Member added**: the plugin increments the subscription quantity by 1.
* **Member removed**: the plugin decrements the subscription quantity by 1.
* **Invitation accepted**: the plugin increments the subscription quantity by 1 when the invitee joins.

This only applies to subscriptions on plans that have `quantity` configured. The plugin uses the active organization's subscription and updates the quantity through Razorpay's subscription update API.

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

export const auth = betterAuth({
  plugins: [
    organization(),
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
      createCustomerOnSignUp: true,
      subscription: {
        enabled: true,
        plans: [
          {
            planId: "plan_monthly_team",
            annualPlanId: "plan_annual_team",
            name: "team",
            totalCount: 12,
            quantity: 5,
            limits: { projects: 50, storage: 500 },
          },
        ],
        authorizeReference: async ({ user, session, referenceId, action }) => {
          // Only organization admins can manage subscriptions
          const member = await getOrganizationMember(referenceId, user.id);
          return member?.role === "admin";
        },
      },
      organization: {
        enabled: true,
      },
    }),
  ],
});
```

> [!WARNING]
>
> Automatic seat sync requires the organization plugin and `organization.enabled: true`. Deleting an organization with an active subscription is blocked with `ORGANIZATION_HAS_ACTIVE_SUBSCRIPTION`.

## React example: seat management UI

Build a team settings page where admins can view and adjust seat counts.

```tsx app/team/billing/page.tsx theme={null}
"use client";

import { useState } from "react";
import { authClient } from "@/lib/auth-client";
import {
  useSubscriptionList,
  useUpdateSubscription,
  useSubscriptionStatus,
} from "@amank-root/better-auth-razorpay/react";

export default function TeamBillingPage() {
  const { data: subscriptions, isLoading } = useSubscriptionList(authClient, {
    customerType: "organization",
  });
  const updateSub = useUpdateSubscription(authClient);
  const [newQuantity, setNewQuantity] = useState(5);

  if (isLoading) return <p>Loading...</p>;

  const sub = subscriptions?.[0];
  const status = useSubscriptionStatus(sub);

  if (!sub) return <p>No active subscription.</p>;

  const handleUpdate = async () => {
    const { error } = await updateSub.mutateAsync({
      quantity: newQuantity,
      scheduleChangeAt: "now",
      customerType: "organization",
    });

    if (error) {
      alert("Failed to update seats: " + error.message);
    }
  };

  return (
    <div>
      <h1>Team billing</h1>
      <p>Plan: {sub.plan}</p>
      <p>Status: {status.isActive ? "Active" : status.isPaused ? "Paused" : "Inactive"}</p>
      <p>Current seats: {sub.quantity}</p>

      <label>
        New seat count:
        <input
          type="number"
          min={1}
          value={newQuantity}
          onChange={(e) => setNewQuantity(Number(e.target.value))}
        />
      </label>

      <button onClick={handleUpdate} disabled={updateSub.isPending}>
        {updateSub.isPending ? "Updating..." : "Update seats"}
      </button>
    </div>
  );
}
```

## Common errors

| Error code | When it occurs |
| - | - |
| `SUBSCRIPTION_UPDATE_FAILED` | Razorpay rejected the quantity update. |
| `SUBSCRIPTION_NOT_FOUND` | No subscription exists for the reference. |
| `ORGANIZATION_HAS_ACTIVE_SUBSCRIPTION` | Attempting to delete an organization that still has an active subscription. |
| `ORGANIZATION_SUBSCRIPTION_NOT_ENABLED` | Organization subscriptions are not enabled in the plugin config. |
| `AUTHORIZE_REFERENCE_REQUIRED` | `authorizeReference` is not configured for organization subscriptions. |


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