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

# Items and add-ons

> Create and manage Razorpay items and subscription add-ons with the Better Auth plugin.

Items are reusable catalog entries that you can reference in invoice line items and subscription add-ons. Add-ons are extra charges attached to a subscription. This page covers creating items, using them in invoices and subscriptions, managing add-ons, and the available React hooks.

## Create an item

Items represent products or services in your catalog. You can create them with tax fields and reuse them across invoices and subscriptions.

```ts client.ts theme={null}
import { authClient } from "./auth-client";

async function createItem() {
  const { data, error } = await authClient.razorpay.item.create({
    name: "Premium support",
    amount: 15000,
    currency: "INR",
    description: "Priority email and chat support",
    active: true,
    tax_inclusive: false,
    hsn_code: "9983",
    tax_rate: 18,
  });

  if (error) throw error;
  return data;
}
```

**name** `string` *required*

The display name of the item.

**amount** `integer` *required*

The price in the smallest currency unit (paise for INR).

**currency** `string` *required*

Three-letter currency code, for example `"INR"`.

**description** `string`

A longer description of the item.

**active** `boolean`

Whether the item is active and available for use.

**tax\_inclusive** `boolean`

Whether the amount already includes tax.

**hsn\_code** `string`

Harmonized System of Nomenclature code for tax classification.

**sac\_code** `string`

Services Accounting Code for tax classification.

**tax\_rate** `number`

The tax rate percentage to apply.

**tax\_id** `string`

A Razorpay tax ID to apply.

**tax\_group\_id** `string`

A Razorpay tax group ID to apply.

## Edit, list, and delete items

Manage your catalog after items are created.

```ts client.ts theme={null}
// Edit an item
const { data: editData, error: editError } = await authClient.razorpay.item.edit({
  itemId: "item_XXXX",
  amount: 16000,
  description: "Updated priority support",
});

// List items
const { data: list, error: listError } = await authClient.razorpay.item.list({
  query: { active: 1, count: 20 },
});

// Fetch a single item
const { data: item, error: fetchError } = await authClient.razorpay.item.get({
  query: { id: "item_XXXX" },
});

// Delete an item
const { data: deleted, error: deleteError } = await authClient.razorpay.item.delete({
  itemId: "item_XXXX",
});
```

**active** `integer`

Filter by active status: `1` for active, `0` for inactive.

**count** `integer`

Number of results to fetch, up to 100.

**skip** `integer`

Number of results to skip.

## Use items in invoice line items

When creating an invoice, reference an existing item by its ID instead of defining the line item inline.

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.invoice.create({
  type: "invoice",
  description: "Monthly services",
  line_items: [
    {
      id: "item_XXXX",
      quantity: 2,
    },
  ],
  customer: {
    name: "Acme Corp",
    email: "billing@acme.example",
    contact: "+919000090000",
    billing_address: {
      line1: "123 Main St",
      zipcode: "560001",
      city: "Bangalore",
      country: "IN",
    },
  },
});
```

## Use items in subscription add-ons

Attach add-ons to a subscription by referencing item IDs in the `lineItems` field during an upgrade, or by creating an add-on directly on an existing subscription.

### Add line items during upgrade

```ts client.ts theme={null}
const { data, error } = await authClient.subscription.upgrade({
  plan: "pro",
  lineItems: [
    { item_id: "item_XXXX", quantity: 1 },
  ],
});
```

### Create an add-on on an existing subscription

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

You can also create an inline item when adding an add-on:

```ts client.ts theme={null}
const { data, error } = await authClient.razorpay.subscription.addon.create({
  subscriptionId: "sub_XXXX",
  item: {
    name: "One-time setup fee",
    amount: 50000,
    currency: "INR",
    description: "Initial configuration",
  },
  quantity: 1,
});
```

## Manage add-ons

List and delete add-ons that are attached to subscriptions.

```ts client.ts theme={null}
// List add-ons
const { data: addons, error: listError } = await authClient.razorpay.addon.list({
  query: { count: 20 },
});

// Fetch a single add-on
const { data: addon, error: fetchError } = await authClient.razorpay.addon.get({
  query: { id: "ao_XXXX" },
});

// Delete an add-on
const { data: deleted, error: deleteError } = await authClient.razorpay.addon.delete({
  addonId: "ao_XXXX",
});
```

## React hooks

The React entry point provides hooks for items and add-ons.

### List items

```tsx item-list.tsx theme={null}
import { useRazorpayItemList } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function ItemList() {
  const { data, isLoading, error } = useRazorpayItemList(authClient, {
    query: { active: 1, count: 20 },
  });

  if (isLoading) return <p>Loading items...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data?.items?.map((item) => (
        <li key={item.id}>
          {item.name} — {item.amount / 100} {item.currency}
        </li>
      ))}
    </ul>
  );
}
```

### Create and delete items

```tsx item-actions.tsx theme={null}
import { useCreateItem, useDeleteItem } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function ItemActions() {
  const createItem = useCreateItem(authClient);
  const deleteItem = useDeleteItem(authClient);

  async function handleCreate() {
    await createItem.mutateAsync({
      name: "Extra storage",
      amount: 10000,
      currency: "INR",
      active: true,
    });
  }

  return (
    <div style={{ display: "flex", gap: 8 }}>
      <button onClick={handleCreate} disabled={createItem.isPending}>
        {createItem.isPending ? "Creating..." : "Create item"}
      </button>
      <button onClick={() => deleteItem.mutate({ itemId: "item_XXXX" })} disabled={deleteItem.isPending}>
        {deleteItem.isPending ? "Deleting..." : "Delete item"}
      </button>
    </div>
  );
}
```

### List add-ons

```tsx addon-list.tsx theme={null}
import { useRazorpayAddonList } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function AddonList() {
  const { data, isLoading, error } = useRazorpayAddonList(authClient, {
    query: { count: 20 },
  });

  if (isLoading) return <p>Loading add-ons...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data?.items?.map((addon) => (
        <li key={addon.id}>
          {addon.item?.name} — {addon.item?.amount / 100} {addon.item?.currency} (qty: {addon.quantity})
        </li>
      ))}
    </ul>
  );
}
```

### Create and delete subscription add-ons

```tsx subscription-addon-actions.tsx theme={null}
import { useCreateSubscriptionAddon, useDeleteAddon } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function SubscriptionAddonActions({ subscriptionId }: { subscriptionId: string }) {
  const createAddon = useCreateSubscriptionAddon(authClient);
  const deleteAddon = useDeleteAddon(authClient);

  async function handleCreate() {
    await createAddon.mutateAsync({
      subscriptionId,
      item: {
        name: "Onboarding fee",
        amount: 25000,
        currency: "INR",
      },
      quantity: 1,
    });
  }

  return (
    <div style={{ display: "flex", gap: 8 }}>
      <button onClick={handleCreate} disabled={createAddon.isPending}>
        {createAddon.isPending ? "Adding..." : "Add add-on"}
      </button>
      <button onClick={() => deleteAddon.mutate({ addonId: "ao_XXXX" })} disabled={deleteAddon.isPending}>
        {deleteAddon.isPending ? "Deleting..." : "Delete add-on"}
      </button>
    </div>
  );
}
```

## Error codes

The following error codes may be returned during item and add-on operations:

* `ITEM_CREATE_FAILED`: the item could not be created.
* `ITEM_NOT_FOUND`: the requested item does not exist.
* `ITEM_FETCH_FAILED`: failed to fetch an item.
* `ITEM_LIST_FAILED`: failed to list items.
* `ITEM_EDIT_FAILED`: the item could not be updated.
* `ITEM_DELETE_FAILED`: the item could not be deleted.
* `ADDON_CREATE_FAILED`: the subscription add-on could not be created.
* `ADDON_NOT_FOUND`: the requested add-on does not exist.
* `ADDON_FETCH_FAILED`: failed to fetch an add-on.
* `ADDON_LIST_FAILED`: failed to list add-ons.
* `ADDON_DELETE_FAILED`: the add-on could not be deleted.

## Next steps

* [Invoices](https://better-auth-razorpay.amankushwaha.dev/guides/invoices.md) — use items in invoice line items.
* [Subscriptions](https://better-auth-razorpay.amankushwaha.dev/guides/subscriptions.md) — attach add-ons to recurring plans.
* [Plans](https://better-auth-razorpay.amankushwaha.dev/guides/plans.md) — define the billing plans that items and add-ons complement.


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