Build a Custom Referral Modal in Your App

Use this approach when you want a native "Refer a friend" modal without embedding the full referral dashboard.

Affonso handles the referral link and attribution. You handle the UI.

If users only need a link and a copy action, a custom modal is usually the better fit. If they also need stats, rewards, or a full referral workspace, use the Embedded Referral Dashboard instead.

Even if you use a lightweight custom modal, I still recommend keeping the Embedded Referral Dashboard available and linking to it from the widget or modal. That gives users a place to check stats, see whether they have already referred anyone, and review the rest of their referral details without overloading the small modal UI.

The Basic Flow

1. Your server creates an embed token for the signed-in user with the create embed token endpoint.
2. Your server uses that token to fetch the user's embed data from https://affonso.io/embed/data?token=....
3. Your frontend calls your own endpoint and renders the response in any modal, drawer, or card you want.

Keep token creation on the server. Never expose your Affonso API key in the browser.

Example Server Endpoint

You do not need special frontend integration code for the modal itself. A small authenticated backend endpoint is enough:

// app/api/referral-modal/route.ts
export async function GET() {
  const user = await getCurrentUser();

  const tokenResponse = await fetch('https://api.affonso.io/v1/embed/token', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AFFONSO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      programId: 'YOUR_PROGRAM_ID',
      partner: {
        email: user.email,
        name: user.name,
      },
      externalUserId: user.id,
    }),
  });

  const { data: tokenData } = await tokenResponse.json();

  const embedResponse = await fetch(
    `https://affonso.io/embed/data?token=${tokenData.publicToken}`,
    { cache: 'no-store' }
  );

  const { data: embedData } = await embedResponse.json();

  return Response.json({
    link: embedData.link,
    portalUrl: embedData.portalUrl,
    trackingId: embedData.affiliate.trackingId,
  });
}

If you already proxy embed routes through your own domain, you can resolve the same data through your proxied embed/data path instead.

UI Ideas

Keep the modal small. A headline, one sentence about the reward, the referral link, and a Copy link button are usually enough.

If you want design inspiration for your own modal or widget UI, this referral card on 21st.dev is a good starting point. I recommend adding a secondary link to the full Embedded Referral Dashboard so users can open their stats, payouts, and referral activity from the same flow.

Next Steps

• Embedded Referral Dashboard
• Proxy the Embedded Dashboard Through Your Own Domain
• API Integration