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

# Razorpay subscriptions

> Interact directly with Razorpay subscription objects, hosted links, pending updates, invoices, offers, and add-ons.

These endpoints act on Razorpay subscription objects directly using Razorpay subscription ids (`sub_XXXX`). They are always registered, even when `subscription.enabled` is `false`, because they operate on raw Razorpay resources rather than the plugin-managed local subscription lifecycle.

## Get subscription

`GET /api/auth/razorpay/subscription/get`

Retrieves a single Razorpay subscription by its id.

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

**subscriptionId** `string` *required*

Razorpay subscription id, for example `sub_XXXX`.

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

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

## Create subscription link

`POST /api/auth/razorpay/subscription-link`

Creates a Razorpay subscription and returns a hosted authorization `shortUrl`. Use this when you want Razorpay to handle the checkout flow for a subscription.

**Server API name:** `createSubscriptionLink`\
**Client method:** `authClient.razorpay.subscriptionLink(...)`

**planId** `string` *required*

Razorpay plan id, for example `plan_XXXX`.

**totalCount** `integer` *required*

Total number of billing cycles for the subscription.

**quantity** `integer` (default: 1)

Number of subscriptions for the selected plan.

**startAt** `integer`

Unix timestamp when the subscription should start.

**expireBy** `integer`

Unix timestamp before which the authorization link must be used.

**customerNotify** `boolean` (default: true)

Whether Razorpay should notify the customer.

**addons** `array`

Add-ons to include with the subscription. Each item is an object with an `item` field and optional `quantity`. The `item` can be either `{ id: "item_XXXX" }` or a new item `{ name, amount, currency, description }`.

**offerId** `string`

Razorpay offer id to apply to the subscription.

**notes** `object`

Key-value pairs stored with the subscription.

**notifyInfo** `object`

Customer contact details for notifications. Contains `notifyPhone` and `notifyEmail`.

**subscriptionId** `string`

Razorpay subscription id.

**shortUrl** `string`

Hosted authorization link the customer can use to complete the subscription.

**razorpaySubscription** `object`

Full Razorpay subscription object.

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

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscriptionLink({
  planId: "plan_XXXX",
  totalCount: 12,
  quantity: 1,
  addons: [
    {
      item: { id: "item_YYYY" },
      quantity: 2,
    },
  ],
  notes: { source: "landing_page" },
});
```

```ts server.ts theme={null}
const result = await auth.api.createSubscriptionLink({
  body: {
    planId: "plan_XXXX",
    totalCount: 12,
    quantity: 1,
    addons: [{ item: { id: "item_YYYY" }, quantity: 2 }],
    notes: { source: "landing_page" },
  },
  headers: await headers(),
});
```

## Fetch pending update

`GET /api/auth/razorpay/subscription/pending-update`

Retrieves the pending update details for a subscription that has a scheduled change.

**Server API name:** `fetchPendingUpdate`\
**Client method:** `authClient.razorpay.subscription.pendingUpdate({ query: { subscriptionId } })`

**subscriptionId** `string` *required*

Razorpay subscription id.

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

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

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

## Cancel pending update

`POST /api/auth/razorpay/subscription/cancel-update`

Cancels a pending update on a subscription so the scheduled change does not take effect.

**Server API name:** `cancelPendingUpdate`\
**Client method:** `authClient.razorpay.subscription.cancelUpdate(...)`

**subscriptionId** `string` *required*

Razorpay subscription id.

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

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.cancelUpdate({
  subscriptionId: "sub_XXXX",
});
```

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

## Fetch invoices

`GET /api/auth/razorpay/subscription/invoices`

Retrieves all invoices generated for a given Razorpay subscription.

**Server API name:** `fetchInvoices`\
**Client method:** `authClient.razorpay.subscription.invoices({ query: { subscriptionId } })`

**subscriptionId** `string` *required*

Razorpay subscription id.

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

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

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

## Link offer

`POST /api/auth/razorpay/subscription/link-offer`

Links an existing Razorpay offer to a subscription.

**Server API name:** `linkOffer`\
**Client method:** `authClient.razorpay.subscription.linkOffer(...)`

**subscriptionId** `string` *required*

Razorpay subscription id.

**offerId** `string` *required*

Razorpay offer id, for example `offer_XXXX`.

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

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.linkOffer({
  subscriptionId: "sub_XXXX",
  offerId: "offer_YYYY",
});
```

```ts server.ts theme={null}
const result = await auth.api.linkOffer({
  body: {
    subscriptionId: "sub_XXXX",
    offerId: "offer_YYYY",
  },
  headers: await headers(),
});
```

## Delete offer

`POST /api/auth/razorpay/subscription/delete-offer`

Removes a linked offer from a subscription.

**Server API name:** `deleteOffer`\
**Client method:** `authClient.razorpay.subscription.deleteOffer(...)`

**subscriptionId** `string` *required*

Razorpay subscription id.

**offerId** `string` *required*

Razorpay offer id to remove.

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

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.deleteOffer({
  subscriptionId: "sub_XXXX",
  offerId: "offer_YYYY",
});
```

```ts server.ts theme={null}
const result = await auth.api.deleteOffer({
  body: {
    subscriptionId: "sub_XXXX",
    offerId: "offer_YYYY",
  },
  headers: await headers(),
});
```

## Create subscription addon

`POST /api/auth/razorpay/subscription/addon`

Adds an addon to an existing Razorpay subscription. The addon is billed immediately and included in subsequent invoices.

**Server API name:** `createSubscriptionAddon`\
**Client method:** `authClient.razorpay.subscription.addon(...)`

**subscriptionId** `string` *required*

Razorpay subscription id.

**item** `object` *required*

The addon item. Either reference an existing item with `{ id: "item_XXXX" }` or create a new item inline with `{ name, amount, currency, description }`.

**quantity** `integer` (default: 1)

Quantity of the addon.

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

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.addon({
  subscriptionId: "sub_XXXX",
  item: { name: "Extra Storage", amount: 10000, currency: "INR" },
  quantity: 1,
});
```

```ts server.ts theme={null}
const result = await auth.api.createSubscriptionAddon({
  body: {
    subscriptionId: "sub_XXXX",
    item: { name: "Extra Storage", amount: 10000, currency: "INR" },
    quantity: 1,
  },
  headers: await headers(),
});
```


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