# Referral quickstart: Supabase

The code saved in the new user's metadata, and an Edge Function that reports the signup with the verified user.

Referrals in an app on Supabase Auth: the tag on your site, the code saved with
the new user, a small Edge Function that reports each signup as a lead, and
sales from your billing system.

## Before you start

- A key with the **Referral tracking** preset (the single scope
  `conversions:write`), made under **Settings, Developers**. Keep it on your
  server as `BOLTCLAW_API_KEY`, never in a browser or an app.
- The program's id, on its **Setup** tab, as `BOLTCLAW_PROGRAM_ID`.

## 1. Put the tag on your site

Add the version 2 tag to every page, in your root layout or template. It keeps a
partner's code from `?via=<code>` in a first-party cookie on your own domain,
`bc_ref`, for the program's cookie window, and gives you
`BoltClawReferral.code()` in the browser.

```html
<script src="https://boltclaw.ai/referrals/v2.js" defer data-payment-links="auto"></script>
```

`data-payment-links="auto"` is only for Stripe Payment Links and the Buy Button;
`data-welcome="auto"` adds the friend's welcome. The tag makes no request at all
unless the welcome is on and the visitor arrived with a code.

## 2. Save the code with the new user

Pass the code in the user's metadata when they sign up:

```js
const { data, error } = await supabase.auth.signUp({
  email,
  password,
  options: { data: { boltclaw_ref: BoltClawReferral.code() } },
});
```

**Why set the cookie from your server.** Safari deletes a cookie a script
created once the visitor has gone 7 days of browsing without using your site,
and keeps one only 24 hours on a page reached through a tracking link, so a
code the tag keeps can be gone a week later. A cookie your OWN server sets in
its response keeps its full lifetime, unless it comes through somebody else's
host (a third-party CNAME or IP address), which Safari caps at 7 days
(WebKit's published tracking prevention rules, read 2026-10-23). Setting `bc_ref`
from your server, not `HttpOnly`, keeps the full window and the tag still reads
it. If your app also has a server (Next.js, Express), set the
cookie there as the [Next.js quickstart](https://boltclaw.ai/docs/referral-quickstart-nextjs) shows.

## 3. Report each signup from an Edge Function

An Edge Function the app calls right after sign-up (and after the email is
confirmed, if you require that). It takes the user from the verified session,
never from the request body, and reports the lead with the user's id.

```ts
// supabase/functions/report-signup/index.ts
import { createClient } from "jsr:@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(Deno.env.get("SUPABASE_URL")!, Deno.env.get("SUPABASE_ANON_KEY")!, {
    global: { headers: { Authorization: req.headers.get("Authorization") ?? "" } },
  });
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) return new Response("Unauthorized", { status: 401 });
  const code = typeof user.user_metadata?.boltclaw_ref === "string" ? user.user_metadata.boltclaw_ref : null;
  const res = await fetch("https://api.boltclaw.ai/v1/referrals/conversions", {
    method: "POST",
    headers: { Authorization: `Bearer ${Deno.env.get("BOLTCLAW_API_KEY")}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      program_id: Deno.env.get("BOLTCLAW_PROGRAM_ID"),
      event: "lead",
      event_id: `signup-${user.id}`,
      customer: { id: user.id },
      referral: code ? { code } : undefined,
    }),
  });
  return new Response(null, { status: res.ok ? 204 : 502 });
});
```

```js
// in the app, once the user has a session
await supabase.functions.invoke("report-signup");
```

Store the key with `supabase secrets set BOLTCLAW_API_KEY=...`. Calling the
function twice is harmless: the same `event_id` changes nothing.

## 4. Record sales

Connect the billing system you take payments with on the **Setup** tab (see
[Connect your billing system](https://boltclaw.ai/docs/referral-setup)), and pass the code to checkout
as its guide shows: sales, renewals and refunds are then reported for you, and
the setup status ticks them off. Not on one of the twelve? Report each sale from
your server with `event: "sale"`, your own `event_id` for the payment, the same
`customer.id` as the signup, `amount` in minor units and `currency`.

## 5. Send a test sale

Press **Send a test sale** on the Setup tab: a click, a signup, a sale with two
items and a partial refund go through your real rules as test data, credited to
the program's test partner, never paid and never counted. To check your own
wiring, send one of your own conversions with `"test": true`: it is test data
too, and **Clear test data** deletes it all. The setup status's rows turn green
only for live events.

<!-- https://boltclaw.ai/docs/referral-quickstart-supabase as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->