101 lines
2.1 KiB
Plaintext
101 lines
2.1 KiB
Plaintext
---
|
|
title: "useReferrals"
|
|
description: "Create and redeem referral codes"
|
|
---
|
|
|
|
import LearnHooksTip from '/snippets/learn-hooks-tip.mdx';
|
|
|
|
The `useReferrals` hook provides methods to create and redeem referral codes as part of a referral program.
|
|
|
|
<LearnHooksTip />
|
|
|
|
## 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
|
|
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
|
|
{
|
|
"code": "REF123ABC",
|
|
"customerId": "cus_123",
|
|
"createdAt": 1717000000
|
|
}
|
|
```
|
|
|
|
</Expandable>
|
|
|
|
### `redeemCode()`
|
|
|
|
Redeems a referral code for the current customer.
|
|
|
|
```tsx
|
|
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
|
|
{
|
|
"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`.
|