> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useReferrals

> Create and redeem referral codes

The `useReferrals` hook provides methods to create and redeem referral codes as part of a referral program.

<Tip>
  Learn how to setup Autumn hooks in the [Getting Started](/documentation/getting-started/setup) guide.
</Tip>

## Parameters

<ParamField body="programId" type="string" required>
  The ID of your referral program.
</ParamField>

<ParamField body="queryOptions" type="UseQueryOptions">
  Optional [TanStack Query options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) to customize caching and refetching behavior.
</ParamField>

## Returns

### `data`

The referral code response. The hook starts with `enabled: false`, so call `refetch()` to create/fetch the code.

```tsx theme={null}
import { useReferrals } from "autumn-js/react";

export default function ReferralCode() {
  const { data, refetch, isLoading } = useReferrals({ programId: "refer-a-friend" });

  return (
    <div>
      <button onClick={() => refetch()}>Get My Referral Code</button>
      {data && <p>Share this code: {data.code}</p>}
    </div>
  );
}
```

<Expandable title="Response object">
  ```json theme={null}
  {
    "code": "REF123ABC",
    "customerId": "cus_123",
    "createdAt": 1717000000
  }
  ```
</Expandable>

### `redeemCode()`

Redeems a referral code for the current customer.

```tsx theme={null}
import { useReferrals } from "autumn-js/react";

export default function RedeemForm() {
  const { redeemCode } = useReferrals({ programId: "refer-a-friend" });

  const handleRedeem = async (code: string) => {
    const result = await redeemCode({ code });
    console.log("Redeemed! Reward:", result.rewardId);
  };

  return <button onClick={() => handleRedeem("REF123ABC")}>Redeem Code</button>;
}
```

**Parameters**

<ParamField body="code" type="string" required>
  The referral code to redeem.
</ParamField>

**Returns**

```json theme={null}
{
  "id": "red_123",
  "customerId": "cus_456",
  "rewardId": "reward_789"
}
```

### `isLoading`

Boolean indicating whether a referral code is being created/fetched.

### `error`

Any error that occurred.

### `refetch()`

Creates or fetches the referral code for the configured `programId`.