Embedded Referral Dashboard

Integrate a fully functional referral dashboard into your product. Your users see their stats, referral links, and earnings - all within your app’s interface.

Overview

The embedded dashboard displays:

Referral link with copy functionality
Performance metrics (clicks, leads, sales)
Commission earnings and payout status
Coupon codes (with optional self-service creation)
Marketing resources and creatives

Integration Flow

Your Server calls Affonso API

POST /v1/embed/token with user data (email, name, image)

Affonso returns token

Response includes publicToken, expiresAt, affiliate link, and partnershipStatus

Frontend renders iframe

Embed the dashboard using the token in the iframe URL

Step 1: Generate Token

Create an API route on your server that generates a token. This keeps your API key secure.

Body Parameters

programId

string

required

Your affiliate program ID.

partner

object

required

Information about the user you want to display the dashboard for.

Show Properties

string

required

User’s email address. If no affiliate exists with this email, one will be created automatically.

name

string

Display name for the affiliate. Used when generating their tracking ID.

image

string

URL to the user’s avatar image.

groupId

string

Affiliate group ID to assign the user to. If not specified, the user is assigned to your program’s default group. Use this to place users in specific commission tiers. Find your group IDs in Dashboard → Affiliate Program → Groups.

Example Request

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm12x98yz0005bnp8h9ld2ff9",
    "partner": {
      "email": "user@example.com",
      "name": "Jane Smith",
      "image": "https://example.com/avatar.jpg"
    },
    "groupId": "e3e6e1b2-5a12-434f-a1b2-4bb0f12c3a89"
  }'

Response

{
  "success": true,
  "data": {
    "publicToken": "emb_abc123def456...",
    "expiresAt": "2024-01-15T10:30:00Z",
    "link": "https://yoursite.com?via=jane-smith",
    "portalUrl": "https://affiliates.yoursite.com",
    "partnershipStatus": "APPROVED"
  }
}

New users are automatically registered as affiliates. Their partnership status depends on your program’s Access Mode setting:

Public (auto-approve): partnershipStatus is APPROVED – affiliate can start referring immediately
Private (manual approval): partnershipStatus is PENDING – requires manual approval in your dashboard

Step 2: Render the Dashboard

Use the publicToken in an iframe to display the dashboard.

<iframe
  src="https://affonso.io/embed/referrals?token=emb_abc123def456..."
  className="w-full h-screen border-0"
  allow="clipboard-write"
/>

Next.js Example

1. Create API Route

First, create a server-side API route that generates the token:

// app/api/embed-token/route.ts
import { NextResponse } from 'next/server';
import { getServerSession } from 'next-auth';

export async function POST() {
  const session = await getServerSession();

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const response = 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: process.env.AFFONSO_PROGRAM_ID,
      partner: {
        email: session.user.email,
        name: session.user.name,
        image: session.user.image,
      },
    }),
  });

  const data = await response.json();
  return NextResponse.json(data);
}

2. Create the Page Component

Then, fetch the token from your API route and render the iframe:

// app/referrals/page.tsx
'use client';

import { useEffect, useState } from 'react';

export default function ReferralsPage() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchToken() {
      const res = await fetch('/api/embed-token', { method: 'POST' });
      const { data } = await res.json();
      setToken(data.publicToken);
      setLoading(false);
    }
    fetchToken();
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src={`https://affonso.io/embed/referrals?token=${token}`}
      className="w-full h-screen border-0"
      allow="clipboard-write"
    />
  );
}

Token Lifecycle

Property	Details
Validity	30 minutes
Refresh	Generate new token on each page load
Cleanup	Old tokens are automatically invalidated

Always generate tokens server-side. Never expose your API key to the client.

Customization

URL Parameters

Add these parameters to the iframe URL for customization:

Parameter	Values	Description
`theme`	`light`, `dark`, `system`	Color scheme. Default: `light`
`bg`	HEX color (without `#`)	Background color. Use this to match your app’s background. Example: `0f0f0f` for dark, `ffffff` for white
`lang`	Language code	UI language. Default: `en`. See supported languages below
`showHeader`	`true`, `false`	Show header card with program logo and name. Default: `true`
`showRewards`	`true`, `false`	Show rewards card with commission structure and incentives. Default: `true`
`showReports`	`true`, `false`	Show reports tab with statistics and earnings table. Default: `true`
`showResources`	`true`, `false`	Show resources tab with marketing materials and creative assets. Default: `true`
`enableQRCode`	`true`, `false`	Enable QR code download for referral links. Default: `true`
`enableTrackingIdEdit`	`true`, `false`	Allow affiliates to customize their tracking ID. Default: `true`
`enableSubParams`	`true`, `false`	Enable sub-parameters (sub1-sub5) input fields. Default: `true`
`padding`	`true`, `false`	Add padding around the dashboard. Default: `true`

Supported Languages

The dashboard supports 14 languages:

Code	Language
`en`	English (default)
`de`	Deutsch
`fr`	Français
`es`	Español
`it`	Italiano
`pt`	Português
`nl`	Nederlands
`pl`	Polski
`tr`	Türkçe
`ja`	日本語
`zh`	中文
`ko`	한국어
`ru`	Русский
`ar`	العربية

If an invalid language code is provided, the dashboard falls back to English. Example with dark mode, custom background, and German:

<iframe
  src="https://affonso.io/embed/referrals?token=emb_...&theme=dark&bg=0f0f0f&lang=de"
  ...
/>

Example with light mode and Japanese:

<iframe
  src="https://affonso.io/embed/referrals?token=emb_...&theme=light&lang=ja"
  ...
/>

Brand Colors

The dashboard inherits your brand colors from Portal Settings:

Primary Color - Buttons, links, accents
Secondary Color - Highlights, backgrounds

Configure colors in HEX format (e.g., #881337) in your Affonso dashboard under Portal Settings.

Visual Preview Editor

Don’t want to write code to test settings? Use the visual editor:

Go to Affiliate Program → Appearance
Click the Embed tab
Customize in real-time:
- Theme: Light, dark, or system (follows user’s device preference)
- Language: Select from 14 languages – preview updates instantly
- Background: Pick a color that matches your app
Click Integration Code to copy the configured code snippets

The preview shows your actual branding (logo, colors) so you know exactly what users will see.

Embed preview editor in Affonso dashboard

Overview

Affiliates

Referrals

Commissions

Payouts

Embed

Coupons

Clicks

Embedded Referral Dashboard

Overview

Integration Flow

Step 1: Generate Token

Body Parameters

Example Request

Response

Step 2: Render the Dashboard

Next.js Example

1. Create API Route

2. Create the Page Component

Token Lifecycle

Customization

URL Parameters

Supported Languages

Brand Colors

Visual Preview Editor

Overview

Affiliates

Referrals

Commissions

Payouts

Embed

Coupons

Clicks

​Overview

​Integration Flow

​Step 1: Generate Token

​Body Parameters

​Example Request

​Response

​Step 2: Render the Dashboard

​Next.js Example

​1. Create API Route

​2. Create the Page Component

​Token Lifecycle

​Customization

​URL Parameters

​Supported Languages

​Brand Colors

​Visual Preview Editor

Overview

Integration Flow

Step 1: Generate Token

Body Parameters

Example Request

Response

Step 2: Render the Dashboard

Next.js Example

1. Create API Route

2. Create the Page Component

Token Lifecycle

Customization

URL Parameters

Supported Languages

Brand Colors

Visual Preview Editor