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

# Organizations

> Enable organization-level subscriptions and customer management with the Better Auth organization plugin.

The Razorpay plugin supports organization-level subscriptions when you enable the Better Auth `organization()` plugin. This lets you bill teams instead of individual users, sync seat quantities as members join or leave, and manage a dedicated Razorpay customer per organization.

**1. Enable the organization plugin on the server**

Import `organization` from `better-auth/plugins` and add it to your `betterAuth` plugins array before `razorpay`.

```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!,
      subscription: {
        enabled: true,
        plans: [
          { planId: "plan_XXXX", name: "team", quantity: 5 },
        ],
      },
      organization: { enabled: true },
    }),
  ],
});
```

**2. Enable the organization client plugin**

Import `organizationClient` from `better-auth/client/plugins` and add it to your client plugins.

```ts client.ts theme={null}
import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";
import { razorpayClient } from "@amank-root/better-auth-razorpay/client";

export const authClient = createAuthClient({
  plugins: [organizationClient(), razorpayClient({ subscription: true })],
});
```

**3. Define authorizeReference**

Organization subscriptions require `subscription.authorizeReference`. This callback receives the user, session, reference id, and action. Return `true` to allow the action, or `false` to deny it.

The example below uses a helper you define against your own database. Replace `getMemberRole` with your actual membership lookup.

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

// Your own helper — implement this against your database or ORM.
async function getMemberRole(userId: string, orgId: string) {
  // Example: return "owner" | "admin" | "member" | null
}

export const auth = betterAuth({
  plugins: [
    organization(),
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      subscription: {
        enabled: true,
        plans: [{ planId: "plan_XXXX", name: "team", quantity: 5 }],
        authorizeReference: async ({ user, session, referenceId, action }) => {
          const role = await getMemberRole(user.id, referenceId);
          if (!role) return false;
          // Only owners and admins can upgrade, cancel, pause, resume, or update.
          if (
            [
              "upgrade-subscription",
              "cancel-subscription",
              "pause-subscription",
              "resume-subscription",
              "update-subscription",
              "restore-subscription",
            ].includes(action)
          ) {
            return role === "owner" || role === "admin";
          }
          // Anyone in the org can list or get.
          return true;
        },
      },
      organization: { enabled: true },
    }),
  ],
});
```

## Organization plugin options

**enabled** `boolean` *required*

Must be `true` to enable organization support.

**getCustomerCreateParams** `function`

Async function that receives `(organization, ctx)` and returns partial Razorpay customer create params. Use this to attach custom notes or set a display name.

**onCustomerCreate** `function`

Callback invoked after a Razorpay customer is created for an organization. Receives `({ razorpayCustomer, organization }, ctx)`.

## Upgrading and managing organization subscriptions

From the client, pass `customerType: "organization"` and optionally `referenceId` (the organization id). If you omit `referenceId`, the plugin uses the active organization from the session.

```ts client.ts theme={null}
// Upgrade an organization to a team plan
const { data, error } = await authClient.subscription.upgrade({
  plan: "team",
  customerType: "organization",
  referenceId: "org_XXXX",
});

// List organization subscriptions
const { data: list } = await authClient.subscription.list({
  query: {
    customerType: "organization",
    referenceId: "org_XXXX",
  },
});

// Cancel at the end of the current billing cycle
const { data: cancelled } = await authClient.subscription.cancel({
  customerType: "organization",
  referenceId: "org_XXXX",
  cancelAtCycleEnd: true,
});
```

```ts server.ts theme={null}
// Server-side upgrade
const result = await auth.api.upgradeSubscription({
  body: {
    plan: "team",
    customerType: "organization",
    referenceId: "org_XXXX",
  },
  headers: await headers(),
});
```

## Built-in sync hooks

When organization support is enabled, the plugin automatically keeps Razorpay customer data in sync and protects against invalid operations:

* **Organization name update**: changing the organization name updates the linked Razorpay customer name.
* **Member add / remove / invitation accept**: on quantity-based plans, the plugin recalculates seat quantity and updates the Razorpay subscription to match the current member count.
* **Organization deletion guard**: deleting an organization that has an active subscription is blocked.

## Error codes

| Code | Meaning |
| - | - |
| `ORGANIZATION_NOT_FOUND` | The requested organization does not exist. |
| `ORGANIZATION_SUBSCRIPTION_NOT_ENABLED` | Organization support is not enabled in the plugin options. |
| `AUTHORIZE_REFERENCE_REQUIRED` | `authorizeReference` is required for organization subscriptions but was not provided. |
| `ORGANIZATION_REFERENCE_ID_REQUIRED` | An organization subscription action was attempted without a `referenceId` and no active organization is present in the session. |
| `UNAUTHORIZED` | `authorizeReference` returned `false` for the requested action. |
| `REFERENCE_ID_NOT_ALLOWED` | The provided `referenceId` is not permitted for the current user. |
| `ORGANIZATION_HAS_ACTIVE_SUBSCRIPTION` | The organization cannot be deleted because it still has an active subscription. |

> [!WARNING]
>
> Always define `authorizeReference` when using organization subscriptions. Without it, the plugin returns `AUTHORIZE_REFERENCE_REQUIRED` and blocks subscription operations.


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