# `plandalf.referral()`

Read the current affiliate referral and optionally mount a partner badge.

Implemented by the [browser object](https://github.com/plandalf/numi/blob/fc6f42b5ade3d63b71623934838a6509f17203e2/packages/sdk/src/browser.ts#L500); parameter and return types follow the [delegated class declaration](https://github.com/plandalf/numi/blob/fc6f42b5ade3d63b71623934838a6509f17203e2/packages/sdk/src/core/sdk.ts#L840).

**Workspace snapshot:** the inspected SDK has local changes. Source links identify its base commit and may differ from this working copy. Verify the SDK build you deploy before relying on unreleased behavior.

Call this after `plandalf.ready()`. The browser wrapper can return `undefined` before initialization.

## Signature

```typescript
plandalf.referral(opts?: ReferralHandleOptions): ReferralHandle
```

## Arguments

| Name | Type | Meaning |
| --- | --- | --- |
| `opts?` | [`ReferralHandleOptions`](https://plandalf.com/docs/packages/sdk/interfaces/ReferralHandleOptions) | Optional badge target, variant, theme and template. Program capture settings belong to SDK initialization, not this handle call. The browser wrapper declares this argument as `any` and passes it to the typed class method. |

## Example

```javascript title="referral.js" lineNumbers lineNumberStart=1
plandalf.ready(async () => {
  const handle = plandalf.referral()
  const referral = await handle
  const link = document.querySelector('a[data-referral-checkout]')
  if (referral && link) {
    link.href = handle.decorate(link.href)
  }
  // The shared handle stays available to other consumers on this page.
})
```

## Returns

[`ReferralHandle`](https://plandalf.com/docs/packages/sdk/interfaces/ReferralHandle)

## Behaviour

Await the handle for Referral or null after referral initialization. It also exposes events, decorate(url), metadata() and close(). Repeated calls share the current handle; closing it ends its event streams and allows the next call to create a new handle. It does not clear stored attribution. Native Plandalf checkout carries the captured referral automatically. A captured referral or displayed badge does not prove a paid sale or commission; verify those records separately. This reference describes the inspected workspace build.

[All plandalf methods](https://plandalf.com/docs/sdk)

Source: https://plandalf.com/docs/sdk/referral