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

# Subscription links and offers

> Create Razorpay subscription links, manage offers and pending updates, attach add-ons, and fetch subscription invoices with better-auth-razorpay.

The better-auth-razorpay plugin exposes Razorpay subscription link and offer APIs, plus add-on and invoice management. Use these features to generate shareable checkout links, apply promotional offers, attach extra items to subscriptions, and inspect billing history.

## Create a subscription link

A subscription link is a hosted checkout page that Razorpay generates for a given plan. You can share the `shortUrl` directly or embed it in emails and dashboards.

```ts theme={null}
const { data, error } = await authClient.razorpay.subscriptionLink.create({
  planId: "plan_monthly_pro",
  totalCount: 12,
  quantity: 3,
  expireBy: Math.floor(Date.now() / 1000) + 7 * 86400, // expires in 7 days
  customerNotify: true,
  addons: [
    {
      item: {
        name: "Priority support",
        amount: 50000, // INR 500 in paise
        currency: "INR",
        description: "24-hour support SLA",
      },
      quantity: 1,
    },
  ],
  notifyInfo: {
    notifyPhone: "+919000090000",
    notifyEmail: "customer@example.com",
  },
  notes: { source: "referral_campaign_march" },
});

if (!error) {
  console.log("Link:", data.shortUrl);
  console.log("Razorpay subscription ID:", data.razorpaySubscription.id);
}
```

**planId** `string` *required*

Razorpay plan ID (for example, `plan_XXXX`).

**totalCount** `number` *required*

Total billing cycles.

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

Number of subscriptions or seats.

**expireBy** `number`

Unix timestamp when the link expires.

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

Whether Razorpay should notify the customer.

**addons** `array`

Add-ons to include at creation. Each add-on needs an `item` (either `{ id: "item_XXX" }` or a new item with `name`, `amount`, `currency`, and optional `description`) and an optional `quantity`.

**notifyInfo** `object`

`{ notifyPhone, notifyEmail }` to pre-fill contact details.

**notes** `object`

Up to 15 key-value pairs stored on the subscription.

> [!NOTE]
>
> Subscription links are created directly on Razorpay and do not require an existing customer. When the customer completes checkout, Razorpay creates the subscription and sends webhook events.

## Link and delete offers

Apply an existing Razorpay offer to a subscription, or remove it.

### Link an offer

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

### Delete an offer

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

> [!WARNING]
>
> Offers must already exist in your Razorpay dashboard. The plugin does not create offers; it only links and unlinks them from subscriptions.

## Pending updates

When you schedule a subscription change for the next cycle, Razorpay creates a pending update. You can fetch or cancel it before it applies.

### Fetch pending update

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

### Cancel pending update

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

> [!NOTE]
>
> Canceling a pending update keeps the subscription on its current plan and quantity. The change scheduled for the next cycle is discarded.

## Subscription add-ons

Attach extra chargeable items to an existing subscription. Add-ons appear on future invoices.

### Create a subscription add-on

```ts theme={null}
// Add an existing item by ID
const { data, error } = await authClient.razorpay.subscription.addon.create({
  subscriptionId: "sub_XXXX",
  item: { id: "item_XXXX" },
  quantity: 2,
});

// Or create an inline item
const { data, error } = await authClient.razorpay.subscription.addon.create({
  subscriptionId: "sub_XXXX",
  item: {
    name: "Extra storage pack",
    amount: 100000, // INR 1000
    currency: "INR",
    description: "100 GB additional storage",
  },
  quantity: 1,
});
```

**subscriptionId** `string` *required*

Razorpay subscription ID (for example, `sub_XXXX`).

**item** `object` *required*

Either `{ id: "item_XXX" }` or a new item with `name`, `amount`, `currency`, and optional `description`.

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

How many units of the add-on to bill.

## Fetch invoices for a subscription

List all invoices generated for a Razorpay subscription.

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

if (!error) {
  data.invoices.forEach((invoice: any) => {
    console.log(invoice.id, invoice.status, invoice.amount);
  });
}
```

## Fetch a Razorpay subscription

Retrieve the current state of a subscription directly from Razorpay.

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

## List all Razorpay subscriptions

Query subscriptions across your Razorpay account with filters and pagination.

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

**planId** `string`

Filter by Razorpay plan ID.

**status** `string`

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

**count** `number`

Number of results to return (max 100).

**skip** `number`

Number of results to skip for pagination.

## React hooks

Use the TanStack Query hooks for links, offers, pending updates, add-ons, invoices, and subscription lookups.

```tsx app/subscription/manage/page.tsx theme={null}
"use client";

import { authClient } from "@/lib/auth-client";
import {
  useRazorpaySubscription,
  useRazorpayInvoices,
  useSubscriptionPendingUpdate,
  useCreateSubscriptionAddon,
} from "@amank-root/better-auth-razorpay/react";

export default function ManageSubscriptionPage({
  params,
}: {
  params: { id: string };
}) {
  const { data: rzpSub } = useRazorpaySubscription(authClient, params.id);
  const { data: invoices } = useRazorpayInvoices(authClient, params.id);
  const { data: pending } = useSubscriptionPendingUpdate(authClient, params.id);
  const createAddon = useCreateSubscriptionAddon(authClient);

  return (
    <div>
      <h1>Subscription details</h1>
      {rzpSub && <p>Status: {rzpSub.status}</p>}

      <h2>Invoices</h2>
      {invoices?.map((inv: any) => (
        <p key={inv.id}>{inv.id} — {inv.status}</p>
      ))}

      {pending && (
        <div>
          <p>Pending update: {pending.change_schedule_at}</p>
          <button>Cancel pending update</button>
        </div>
      )}

      <button
        onClick={() =>
          createAddon.mutate({
            subscriptionId: params.id,
            item: { id: "item_support_01" },
            quantity: 1,
          })
        }
      >
        Add support addon
      </button>
    </div>
  );
}
```

## Common errors

| Error code | When it occurs |
| - | - |
| `SUBSCRIPTION_LINK_CREATE_FAILED` | Razorpay rejected the subscription link request. |
| `OFFER_LINK_FAILED` | Failed to link the offer to the subscription. |
| `OFFER_DELETE_FAILED` | Failed to remove the offer from the subscription. |
| `PENDING_UPDATE_NOT_FOUND` | No pending update exists for the given subscription. |
| `PENDING_UPDATE_CANCEL_FAILED` | Razorpay rejected the request to cancel the pending update. |
| `ADDON_CREATE_FAILED` | Razorpay rejected the add-on creation request. |
| `SUBSCRIPTION_INVOICE_FETCH_FAILED` | Failed to fetch invoices for the subscription. |


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