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

# Subscriptions

> Manage subscription lifecycles through the plugin endpoints.

> [!NOTE]
>
> These endpoints exist only when `subscription.enabled` is `true` in your plugin configuration. All subscription endpoints require an active session.

The subscriptions endpoints let you upgrade, cancel, pause, resume, update, restore, list, and inspect subscriptions. They are backed by a local `subscription` table that is kept in sync with Razorpay via webhooks.

## Upgrade subscription

`POST /api/auth/subscription/upgrade`

Creates or upgrades a subscription for the authenticated user (or an organization). If a subscription already exists for the same plan, the endpoint returns `ALREADY_SUBSCRIBED_PLAN`. When a free trial is configured on the plan and the reference has never had a trial, the subscription starts after the trial period.

**Server API name:** `upgradeSubscription`\
**Client method:** `authClient.subscription.upgrade(...)`

**plan** `string` *required*

Plan name to upgrade to. Matched case-insensitively against the configured plans.

**referenceId** `string`

The reference id to attach the subscription to. Defaults to the active organization id when `customerType` is `organization`, or the user id otherwise.

**customerType** `string` (default: user)

Either `user` or `organization`.

**annual** `boolean` (default: false)

Use the plan's `annualPlanId` instead of the regular `planId`.

**metadata** `object`

Arbitrary metadata stored on the local subscription row.

**lineItems** `array`

Add-on line items to include at creation. Each item: `{ item_id: string, quantity?: number }`.

**scheduleAtPeriodEnd** `boolean` (default: false)

When `true`, schedules the upgrade to take effect at the current cycle end (`schedule_change_at: "cycle_end"`).

**subscription** `object`

The local subscription row.

**razorpaySubscription** `object`

The Razorpay subscription object.

**shortUrl** `string`

Hosted authorization link for the customer to complete payment.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_PLAN_NOT_FOUND`, `CUSTOMER_NOT_FOUND`, `ALREADY_SUBSCRIBED_PLAN`, `SUBSCRIPTION_UPDATE_FAILED`, `EMAIL_VERIFICATION_REQUIRED`, `FORBIDDEN`, `UNAUTHORIZED`, `REFERENCE_ID_NOT_ALLOWED`, `ORGANIZATION_REFERENCE_ID_REQUIRED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.upgrade({
  plan: "pro",
  annual: true,
  metadata: { source: "checkout" },
});
```

```ts server.ts theme={null}
const result = await auth.api.upgradeSubscription({
  body: {
    plan: "pro",
    annual: true,
    metadata: { source: "checkout" },
  },
  headers: await headers(),
});
```

## Cancel subscription

`POST /api/auth/subscription/cancel`

Cancels the active subscription for the authenticated reference. By default the cancellation is immediate. Pass `cancelAtCycleEnd: true` to let the subscription run until the end of the current billing cycle.

**Server API name:** `cancelSubscription`\
**Client method:** `authClient.subscription.cancel(...)`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**cancelAtCycleEnd** `boolean` (default: false)

When `true`, the subscription remains active until the current cycle ends and `cancelAtCycleEnd` is set to `true` locally.

**subscription** `object`

The updated local subscription row.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_ALREADY_CANCELLED`, `SUBSCRIPTION_CANCEL_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.cancel({
  cancelAtCycleEnd: true,
});
```

```ts server.ts theme={null}
const result = await auth.api.cancelSubscription({
  body: { cancelAtCycleEnd: true },
  headers: await headers(),
});
```

## Pause subscription

`POST /api/auth/subscription/pause`

Pauses an active subscription. The subscription must be active and not already paused.

**Server API name:** `pauseSubscription`\
**Client method:** `authClient.subscription.pause(...)`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**pauseAt** `string` (default: now)

When to pause. Only `"now"` is supported.

**subscription** `object`

The updated local subscription row with status `paused`.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_NOT_ACTIVE`, `SUBSCRIPTION_ALREADY_PAUSED`, `SUBSCRIPTION_PAUSE_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.pause({
  pauseAt: "now",
});
```

```ts server.ts theme={null}
const result = await auth.api.pauseSubscription({
  body: { pauseAt: "now" },
  headers: await headers(),
});
```

## Resume subscription

`POST /api/auth/subscription/resume`

Resumes a paused subscription. The subscription must be paused.

**Server API name:** `resumeSubscription`\
**Client method:** `authClient.subscription.resume(...)`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**resumeAt** `string` (default: now)

When to resume. Only `"now"` is supported.

**subscription** `object`

The updated local subscription row with status `active`.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_NOT_PAUSED`, `SUBSCRIPTION_RESUME_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.resume({
  resumeAt: "now",
});
```

```ts server.ts theme={null}
const result = await auth.api.resumeSubscription({
  body: { resumeAt: "now" },
  headers: await headers(),
});
```

## Update subscription

`POST /api/auth/subscription/update`

Updates an existing subscription. You can change the plan, quantity, offer, schedule, and metadata.

**Server API name:** `updateSubscription`\
**Client method:** `authClient.subscription.update(...)`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**planId** `string`

New Razorpay plan id to switch to.

**offerId** `string`

Razorpay offer id to apply.

**quantity** `integer`

New seat quantity.

**remainingCount** `integer`

New remaining billing cycle count.

**startAt** `integer`

Unix timestamp for when the update should take effect.

**scheduleChangeAt** `string`

`"now"` or `"cycle_end"`. When `"cycle_end"`, the change is deferred.

**customerNotify** `boolean`

Whether Razorpay should notify the customer.

**metadata** `object`

Metadata to merge into the subscription.

**subscription** `object`

The updated local subscription row.

**razorpaySubscription** `object`

The updated Razorpay subscription object.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_UPDATE_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.update({
  quantity: 5,
  scheduleChangeAt: "cycle_end",
});
```

```ts server.ts theme={null}
const result = await auth.api.updateSubscription({
  body: {
    quantity: 5,
    scheduleChangeAt: "cycle_end",
  },
  headers: await headers(),
});
```

## Restore subscription

`POST /api/auth/subscription/restore`

Restores a subscription that is scheduled to cancel at the end of the current cycle. This clears the local `cancelAtCycleEnd` flag. Razorpay does not expose a native restore API, so the plugin only updates the local row.

**Server API name:** `restoreSubscription`\
**Client method:** `authClient.subscription.restore(...)`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**subscription** `object`

The updated local subscription row.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_NOT_PENDING_CANCEL`, `SUBSCRIPTION_RESTORE_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.restore();
```

```ts server.ts theme={null}
const result = await auth.api.restoreSubscription({
  body: {},
  headers: await headers(),
});
```

## List subscriptions

`GET /api/auth/subscription/list`

Lists local subscriptions for the authenticated reference.

**Server API name:** `listSubscriptions`\
**Client method:** `authClient.subscription.list({ query: { ... } })`

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**subscriptions** `array`

Array of local subscription rows.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.list({
  query: { customerType: "organization" },
});
```

```ts server.ts theme={null}
const result = await auth.api.listSubscriptions({
  query: { customerType: "organization" },
  headers: await headers(),
});
```

## Get subscription

`GET /api/auth/subscription/get`

Retrieves a single local subscription by its local id.

**Server API name:** `getSubscription`\
**Client method:** `authClient.subscription.get({ query: { ... } })`

**subscriptionId** `string` *required*

Local subscription id.

**referenceId** `string`

Reference id. Defaults to the active organization id or the user id.

**customerType** `string` (default: user)

Either `user` or `organization`.

**subscription** `object`

The local subscription row.

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.get({
  query: { subscriptionId: "sub_123" },
});
```

```ts server.ts theme={null}
const result = await auth.api.getSubscription({
  query: { subscriptionId: "sub_123" },
  headers: await headers(),
});
```

## List Razorpay subscriptions

`GET /api/auth/razorpay/subscription/list`

Lists subscriptions directly from Razorpay with pagination and optional filters. This endpoint is always available regardless of the local subscription table.

**Server API name:** `fetchAllSubscriptions`\
**Client method:** `authClient.razorpay.subscription.list({ query: { ... } })`

**from** `integer`

Unix timestamp. Return subscriptions created after this time.

**to** `integer`

Unix timestamp. Return subscriptions created before this time.

**count** `integer`

Maximum number of subscriptions to return. Maximum value is `100`.

**skip** `integer`

Number of subscriptions to skip.

**planId** `string`

Filter by Razorpay plan id.

**status** `string`

Filter by status: `created`, `authenticated`, `active`, `pending`, `halted`, `paused`, `cancelled`, `reverted`, `expired`, or `completed`.

**expand** `string`

Comma-separated list of related resources to expand.

> [!NOTE]
>
> Errors: `SUBSCRIPTION_LIST_FAILED`.

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.list({
  query: { count: 10, skip: 0, status: "active" },
});
```

```ts server.ts theme={null}
const result = await auth.api.fetchAllSubscriptions({
  query: { count: 10, skip: 0, status: "active" },
  headers: await headers(),
});
```


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