Add a fully automated referral program to your Supabase app using Auth metadata, Database Webhooks, and Edge Functions.

Prerequisites

Before integrating Cello, ensure the following:

Your app uses Supabase Auth for user signup and authentication
Your app has a Stripe subscription or payment flow (for purchase tracking)
You have a Cello account with your Product ID, Product Secret, and API access keys from the Access Keys page

Use the Cello Sandbox environment when developing and testing your integration.

Optional: Connect the Cello MCP

Connect the Cello MCP server to your AI coding tool - it gives your tool access to Cello’s docs, health checks, and best practices so your AI can handle the implementation.

Cello MCP Server

Setup instructions for Cursor, VS Code, and Lovable

Step 1: Capture referral codes on your landing page

Add the Cello attribution script to your referral landing page to capture the referral code (ucc) when users click referral links:

Install the attribution script. Choose the option best suited for your setup:
Embedded Script Tag
Google Tag Manager
Verify the installation
To verify, follow these steps:
1. Add ?productId=test and ?ucc=test to your website URL
  https://yourwebsite.com/?productId=test&ucc=test
2. Make sure that these values are saved in the cookies as cello-product-id and cello-referral
3. Navigate to your signup page and try to access the ucc using the getUcc() method from the browser console
  window.CelloAttribution('getUcc')
  This method should return a promise with value test
  Promise {<fulfilled>: 'test'}
If this check passes, the script is installed correctly.

Step 2: Track signups with Supabase Auth + Edge Functions

This is the Supabase-specific step. You will pass the referral code through Supabase Auth, then use a Database Webhook and Edge Function to send the signup event to Cello. During signup, retrieve the ucc and store it in the user’s raw_user_meta_data:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

const ucc = await window.CelloAttribution('getUcc')

const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'password',
  options: {
    data: {
      ucc: ucc ?? null,
    },
  },
})

Create an Edge Function that receives the Database Webhook payload and sends a new-signup event to the Cello POST /events API. All Cello referral events use eventName: 'ReferralUpdated' - the trigger field inside context.event specifies the event type (new-signup, invoice-paid, etc.).

supabase functions new cello-track-signup

import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'

async function getCelloAccessToken(): Promise<string> {
  const response = await fetch('https://api.cello.so/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      accessKeyId: Deno.env.get('CELLO_ACCESS_KEY_ID'),
      secretAccessKey: Deno.env.get('CELLO_SECRET_ACCESS_KEY'),
    }),
  })

  if (!response.ok) {
    throw new Error(`Failed to get Cello token: ${await response.text()}`)
  }

  const { accessToken } = await response.json()
  return accessToken
}

serve(async (req: Request) => {
  const payload = await req.json()
  const record = payload.record

  const ucc = record.raw_user_meta_data?.ucc
  const userId = record.id
  const email = record.email

  if (!ucc) {
    return new Response('No referral code - skipping', { status: 200 })
  }

  const accessToken = await getCelloAccessToken()

  const response = await fetch('https://api.cello.so/events', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      eventName: 'ReferralUpdated',
      payload: {
        ucc,
        newUserId: userId,
      },
      context: {
        newUser: {
          id: userId,
          email,
        },
        event: {
          trigger: 'new-signup',
          timestamp: new Date().toISOString(),
        },
      },
    }),
  })

  if (!response.ok) {
    console.error('Cello signup tracking failed:', await response.text())
    return new Response('Error', { status: 500 })
  }

  return new Response('OK', { status: 200 })
})

Set your Cello API access keys. You can find these in your Cello Portal:

supabase secrets set CELLO_ACCESS_KEY_ID=your_access_key_id
supabase secrets set CELLO_SECRET_ACCESS_KEY=your_secret_access_key

Deploy the function:

supabase functions deploy cello-track-signup --no-verify-jwt

The --no-verify-jwt flag is required because the function is called by a Database Webhook, not by an authenticated user.

2c. Create a Database Webhook on auth.users

In your Supabase Dashboard, go to Database → Webhooks and create a new webhook:

Setting	Value
Name	`cello-track-signup`
Table	`auth.users`
Events	`INSERT`
Type	Supabase Edge Functions
Edge Function	`cello-track-signup`

Click Create webhook.

Every time a new user signs up via Supabase Auth, the Edge Function fires automatically and sends the referral attribution to Cello.

Step 3: Connect Stripe Webhook for purchase tracking

To send Cello purchase events, connect your Stripe Webhook to Cello. When creating a Stripe Customer, pass the referral metadata so Cello can attribute conversions:

const customer = await stripe.customers.create({
  email: 'user@example.com',
  metadata: {
    cello_ucc: ucc,                       // referral code stored during signup
    new_user_id: supabaseUserId,           // must match the productUserId used to boot the widget
    new_user_organization_id: orgId,       // optional - for organization-level referrals
  },
})

Cello uses the customer.created event to link the Stripe customer to the referral attribution captured in Step 2. Subsequent invoice.paid events trigger purchase tracking and reward calculation.

Follow this guide to connect the webhook:

Stripe Webhook

Send events using Stripe Webhook

Step 4: Integrate the Referral Component

Integrate the Cello Referral Component into your web app so your users can share their referral link. The component is installed using Cello JS - our client-side SDK. You can install it by:

Adding a script tag to the <head> of your application
Generating a JWT token for user authentication
Booting the component with the provided token and user details

Follow this installation guide:

Referral Component Quickstart

Cello requires a server-side JWT token signed with your PRODUCT_SECRET - this is not the Supabase session token (session.access_token). You must generate a separate token on your backend. See User Authentication for details.

Verify your integration

Use the Event Feed in the Cello Portal to confirm that signup and purchase events are arriving correctly and all required fields pass validation. See the Event Feed guide for details on what to check.

Next steps

Referral Component

Customise how the referral widget looks and behaves in your app

Track Purchases

Set up purchase conversion tracking via Stripe webhooks

Apply Discounts

Offer new user discounts as part of your referral program

Cello MCP Server

Connect Cursor or Lovable to Cello for AI-assisted integration

Getting Started

Integrate Cello with AI

Referral Component

Referral Conversion

Integrations

Cello + Supabase integration

Prerequisites

Optional: Connect the Cello MCP

Cello MCP Server

Step 1: Capture referral codes on your landing page

Embedded Script Tag

Google Tag Manager

Step 2: Track signups with Supabase Auth + Edge Functions

2c. Create a Database Webhook on auth.users

Step 3: Connect Stripe Webhook for purchase tracking

Stripe Webhook

Step 4: Integrate the Referral Component

Referral Component Quickstart

Verify your integration

Next steps

Referral Component

Track Purchases

Apply Discounts

Cello MCP Server

​Prerequisites

​Optional: Connect the Cello MCP

Cello MCP Server

​Step 1: Capture referral codes on your landing page

Embedded Script Tag

Google Tag Manager

​Step 2: Track signups with Supabase Auth + Edge Functions

​2a. Pass the referral code through Supabase Auth signup

​2b. Deploy an Edge Function to send signup events to Cello

​2c. Create a Database Webhook on auth.users

​Step 3: Connect Stripe Webhook for purchase tracking

Stripe Webhook

​Step 4: Integrate the Referral Component

Referral Component Quickstart

​Verify your integration

​Next steps

Referral Component

Track Purchases

Apply Discounts

Cello MCP Server

Prerequisites

Optional: Connect the Cello MCP

Step 1: Capture referral codes on your landing page

Step 2: Track signups with Supabase Auth + Edge Functions

2a. Pass the referral code through Supabase Auth signup

2b. Deploy an Edge Function to send signup events to Cello

2c. Create a Database Webhook on auth.users

Step 3: Connect Stripe Webhook for purchase tracking

Step 4: Integrate the Referral Component

Verify your integration

Next steps