Plandalf
Browse Product guides

Referrer badge and referral handle

The referral handle and page badge are live. They show referral context on your page and expose referral events to your code. A checkout order-summary badge and a React <ReferralBadge> component are not live.

Add a page badge

<div
  data-plandalf-referral
  data-plandalf-referral-template="Recommended by {partner}"
  data-plandalf-referral-variant="pill"
></div>

Variants are pill, note, bar and float. The default is pill. The SDK renders a <plandalf-referral> element and uses inherited page font styles. Dismissal is stored per referral token.

The template supports {partner}. If you pass data-plandalf-style, pass a JSON object.

Use the handle

plandalf("ready", async (sdk) => {
  const handle = sdk.referral({ target: "#referral" });
  const referral = await handle;

  if (referral) {
    console.log(referral.code);
    console.log(referral.partner.name);
    console.log(handle.metadata());
  }
});

handle.decorate(url) can add pf_rt to configured outbound links and adds Stripe Payment Link client_reference_id when the host is buy.stripe.com and the URL does not already have one.

The referral token is mirrored into the pf_rt cookie. The SDK probes for the broadest accepted registrable domain and falls back to a host-only cookie when needed. Override it with data-config-referral-cookie-domain on the script tag, referral.cookieDomain in SDK init, or the program cookie_domain config.

Events

The referral system emits DOM events and object events for captured, changed, expired, shown, held-out, clicked and dismissed badge states. The global event bridge also supports plandalf("on", "referral", handler) and short names such as badge-click.

plandalf:purchase includes the referral summary when a referred purchase completes. It does not include badge variant metadata.

Holdout

The Referral badge settings include a holdout percentage capped at 50. Holdout hides the page badge for that click; it does not change attribution or commissions. Conversion comparison reporting for badge holdout is not currently documented as a live report.

React

Use useReferral() from @plandalf/react to read referral state. There is no exported ReferralBadge component today; mount the declarative badge in markup or call sdk.referral({ target }).

Feature detail