### Successful response for get program by ID

Source: https://refref.ai/docs/api/get-program-by-id

Example 200 response body containing the program object with id, name, description, startDate, endDate, status, createdAt, and updatedAt fields.

```json
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "startDate": "2019-08-24",
    "endDate": "2019-08-24",
    "status": "active",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

--------------------------------

### 200 response for GET /programs

Source: https://refref.ai/docs/api/get-programs

Example successful response containing a list of programs and pagination metadata. The response includes fields like id, name, description, startDate, endDate, status, createdAt, updatedAt, and meta with total, limit, and offset.

```json
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "startDate": "2019-08-24",
      "endDate": "2019-08-24",
      "status": "active",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

--------------------------------

### Successful response for get all participants

Source: https://refref.ai/docs/api/get-participants

Example of a 200 response containing a list of participants and pagination metadata.

```json
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
      "firstName": "string",
      "lastName": "string",
      "email": "user@example.com",
      "status": "active",
      "joinedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

--------------------------------

### Quick Start: Pull and Start RefRef with Docker Compose

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest RefRef image and start the containers with docker-compose. Requires Docker 20.10+ and Docker Compose.

```bash
# Pull the latest RefRef image
docker pull refref/refref:latest
 
# Create a docker-compose.yml file with the necessary configuration
# Start the containers
docker-compose up -d
```

--------------------------------

### GET /programs

Source: https://refref.ai/docs/api/get-programs

Retrieves a list of all programs. Supports filtering by status and pagination through limit and offset parameters.

```APIDOC
## GET /programs

### Description
Retrieves a list of all programs.

### Method
GET

### Endpoint
/`programs`

### Parameters
#### Query Parameters
- **`status`** (string) - Optional - Filter programs by status. Value in: `"active" | "inactive" | "completed"`
- **`limit`** (integer) - Optional - Maximum number of programs to return. Default: `20` Minimum: `1` Maximum: `100`
- **`offset`** (integer) - Optional - Number of programs to skip. Default: `0` Minimum: `0`

### Authentication
API key authentication via header `api-key` or query parameter `api-key`.

### Request Example
```
curl -X GET "https://api.refref.com/v1/programs?status=active" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
Successful operation

#### Response Example
```
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "startDate": "2019-08-24",
      "endDate": "2019-08-24",
      "status": "active",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

### Error Responses
- 401 - Unauthorized
- 500 - Internal Server Error
```

--------------------------------

### Successful response for get participant by ID

Source: https://refref.ai/docs/api/get-participant-by-id

Example of a 200 response containing the participant data. The response includes id, programId, firstName, lastName, email, status, joinedAt, createdAt, and updatedAt.

```JSON
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "status": "active",
    "joinedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

--------------------------------

### GET /programs/{programId}

Source: https://refref.ai/docs/api/get-program-by-id

Retrieves a specific program by its unique identifier. Requires API key authentication via header or query parameter.

```APIDOC
## GET /programs/{programId}

### Description
Retrieve a specific program by its ID.

### Method
GET

### Endpoint
/programs/{programId}

### Authentication
- **api-key** (string, header) - Required - API key authentication.
- **api-key** (string, query) - Required - API key authentication via query parameter.

### Path Parameters
- **programId** (string, format: uuid) - Required - ID of the program to retrieve.

### Request Example
```
curl -X GET "https://api.refref.com/v1/programs/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data.id** (string) - The program ID.
- **data.name** (string) - The program name.
- **data.description** (string) - The program description.
- **data.startDate** (string, date) - The program start date.
- **data.endDate** (string, date) - The program end date.
- **data.status** (string) - The program status (e.g., active).
- **data.createdAt** (string, date-time) - The program creation timestamp.
- **data.updatedAt** (string, date-time) - The program last update timestamp.

#### Response Example
```
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "startDate": "2019-08-24",
    "endDate": "2019-08-24",
    "status": "active",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

### Error Responses
- **401** - Unauthorized.
- **404** - Not found.
- **500** - Internal server error.

```

--------------------------------

### cURL request to GET /programs

Source: https://refref.ai/docs/api/get-programs

Sends a GET request to https://api.refref.com/v1/programs with the status query parameter set to 'active'. Requires an API key in the 'api-key' header.

```bash
curl -X GET "https://api.refref.com/v1/programs?status=active" \
  -H "api-key: <token>"
```

--------------------------------

### cURL request to get all participants

Source: https://refref.ai/docs/api/get-participants

Use this cURL command to fetch participants with optional query parameters. The API key is passed in the 'api-key' header.

```bash
curl -X GET "https://api.refref.com/v1/participants?programId=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=active" \
  -H "api-key: <token>"
```

--------------------------------

### GET /participants

Source: https://refref.ai/docs/api/get-participants

Retrieves a list of all participants. Supports filtering by program ID and status, and pagination with limit and offset.

```APIDOC
## [GET] /participants

### Description
Retrieve a list of all participants

### Method
GET

### Endpoint
/participants

### Parameters
#### Query Parameters
- **programId** (string) - Optional - Filter participants by program ID. Format: `"uuid"`
- **status** (string) - Optional - Filter participants by status. Value in: `"active" | "inactive" | "completed"`
- **limit** (integer) - Optional - Maximum number of participants to return. Default: `20`, Minimum: `1`, Maximum: `100`
- **offset** (integer) - Optional - Number of participants to skip. Default: `0`, Minimum: `0`

### Request Example
```
curl -X GET "https://api.refref.com/v1/participants?programId=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=active" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data** (array) - List of participants
  - **id** (string) - Participant ID
  - **programId** (string) - Program ID
  - **firstName** (string) - First name
  - **lastName** (string) - Last name
  - **email** (string) - Email address
  - **status** (string) - Participant status
  - **joinedAt** (string) - Join date
  - **createdAt** (string) - Creation date
  - **updatedAt** (string) - Last update date
- **meta** (object) - Pagination metadata
  - **total** (integer) - Total number of participants
  - **limit** (integer) - Limit used
  - **offset** (integer) - Offset used

#### Response Example
```
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
      "firstName": "string",
      "lastName": "string",
      "email": "user@example.com",
      "status": "active",
      "joinedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}
```

### Authentication
- **api-key** (header) - API key authentication
- **api-key** (query) - API key authentication via query parameter

### Error Responses
- **401** - Unauthorized
- **500** - Internal Server Error
```

--------------------------------

### Fire events with refcode

Source: https://refref.ai/docs/platform/installation/attribution-script

When a qualifying event occurs (signup, purchase, etc.), include the refcode in your event creation. This example shows a fetch request to the RefRef API.

```javascript
// After user signs up
await fetch('https://api.refref.app/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_API_KEY}`
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    externalId: user.id, // Your user's ID
    eventType: 'signup',
    refcode: storedRefcode, // The refcode from attribution
    metadata: {
      email: user.email,
      signupDate: new Date().toISOString()
    }
  })
});
```

--------------------------------

### Customize Widget Styling

Source: https://refref.ai/docs/platform/installation/widget

Customize the widget's appearance using CSS custom properties. The example shows light and dark theme overrides.

```css
refref-widget {
  --refref-primary-color: #3b82f6;
  --refref-border-radius: 8px;
  --refref-font-family: 'Inter', sans-serif;
  --refref-background: #ffffff;
  --refref-text-color: #1f2937;
}
 
/* Dark theme */
refref-widget[theme="dark"] {
  --refref-background: #1f2937;
  --refref-text-color: #f9fafb;
}
```

--------------------------------

### cURL request to get program by ID

Source: https://refref.ai/docs/api/get-program-by-id

Use this cURL command to retrieve a program by its ID. Requires an API key passed in the api-key header. The programId is a UUID path parameter.

```bash
curl -X GET "https://api.refref.com/v1/programs/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

--------------------------------

### GET /participants/{participantId}

Source: https://refref.ai/docs/api/get-participant-by-id

Retrieves a specific participant by their ID. The participant ID is provided as a path parameter, and the response contains the participant's details.

```APIDOC
## GET /participants/{participantId}

### Description
Retrieve a specific participant by their ID

### Method
GET

### Endpoint
/participants/{participantId}

### Parameters
#### Path Parameters
- **participantId** (string) - Required - ID of the participant to retrieve. Format: `"uuid"`

#### Headers
- **api-key** (string) - Required - API key authentication. In: `header`

#### Query Parameters
- **api-key** (string) - Required - API key authentication via query parameter. In: `query`

### Request Example
```
curl -X GET "https://api.refref.com/v1/participants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

### Response
#### Success Response (200)
- **data** (object) - Participant data
  - **id** (string) - Participant ID
  - **programId** (string) - Program ID
  - **firstName** (string) - First name
  - **lastName** (string) - Last name
  - **email** (string) - Email address
  - **status** (string) - Status (e.g., "active")
  - **joinedAt** (string) - Join date (ISO 8601)
  - **createdAt** (string) - Creation date (ISO 8601)
  - **updatedAt** (string) - Last update date (ISO 8601)

#### Response Example
```
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "programId": "bc59f66b-913a-48ec-ae2b-7ee29d7bcfbb",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "status": "active",
    "joinedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

### Error Responses
- **401** - Unauthorized
- **404** - Not Found
- **500** - Internal Server Error
```

--------------------------------

### cURL request to get participant by ID

Source: https://refref.ai/docs/api/get-participant-by-id

Use this cURL command to retrieve a participant by their ID. Replace <token> with your API key. The participantId is a UUID.

```cURL
curl -X GET "https://api.refref.com/v1/participants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "api-key: <token>"
```

--------------------------------

### Sample Docker Compose Configuration for RefRef

Source: https://refref.ai/docs/platform/self-hosting/docker

A docker-compose.yml file defining RefRef, PostgreSQL, and Redis services. Sets environment variables for database and Redis connections, and uses named volumes for data persistence.

```yaml
version: '3.8'
 
services:
  refref:
    image: refref/refref:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/refref
      - REDIS_URL=redis://redis:6379
      # Add other environment variables as needed
    depends_on:
      - db
      - redis
 
  db:
    image: postgres:14
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=refref
 
  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
 
volumes:
  postgres_data:
  redis_data:
```

--------------------------------

### Initialize Without JWT

Source: https://refref.ai/docs/platform/widget

Initialize the widget without JWT authentication using only externalId. Only use if 'Enforce Referral Authentication' is disabled in product settings.

```javascript
window.RefRef.init({
  productId: 'your-product-id',
  externalId: 'user-123' // Your user's unique identifier
});
```

--------------------------------

### Upgrading RefRef Docker Deployment

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest image and restart containers. Always back up data before upgrading.

```bash
# Pull the latest image (or specific version)
docker pull refref/refref:latest
 
# Restart your containers
docker-compose down
docker-compose up -d
```

--------------------------------

### Add RefRef Attribution Script and Widget

Source: https://refref.ai/docs

Embed the attribution script and widget to track referral codes and enable sharing. The widget initialization requires your product ID and a JWT token from your backend.

```html
<!-- Attribution Script -->
<script src="https://assets.refref.app/attribution.js" defer></script>
 
<!-- Widget -->
<script src="https://assets.refref.ai/widget.js"></script>
<script>
  window.RefRef.init({
    productId: 'your-product-id',
    token: 'jwt-token-from-your-backend'
  });
</script>
```

--------------------------------

### Initialize & Trigger Widget

Source: https://refref.ai/docs/platform/widget

Basic initialization of the RefRef widget with a JWT token fetched from your backend. The widget displays a floating button once initialized.

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.ai/widget.js"></script>
</head>
<body>
  <!-- Your content -->
 
  <script>
    // Initialize widget with JWT token from your backend
    fetch('/api/refref-token')
      .then(res => res.json())
      .then(data => {
        window.RefRef.init({
          productId: 'your-product-id',
          token: data.token
        });
      });
  </script>
</body>
</html>
```

--------------------------------

### Add the attribution script tag (CDN)

Source: https://refref.ai/docs/platform/installation/attribution-script

Add this script tag to your website's <head> or before the closing </body> tag. The defer attribute ensures the script runs after the page loads without blocking rendering.

```html
<script src="https://assets.refref.app/attribution.js" defer></script>
```

--------------------------------

### Control Widget Layout

Source: https://refref.ai/docs/platform/installation/widget

Set the widget's layout properties such as width, max-width, and margin using CSS.

```css
refref-widget {
  display: block;
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
}
```

--------------------------------

### Generate JWT Token (Node.js)

Source: https://refref.ai/docs/platform/widget

Generate a JWT token for the widget using Node.js. Requires the jsonwebtoken package and your product's client secret. The token includes required claims: sub, productId, iat, exp. Optional claims: email, name. Expiry recommended 1 hour.

```javascript
import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string, userEmail?: string, userName?: string) {
  const payload = {
    sub: userId, // User's unique identifier (required)
    productId: productId, // Your RefRef product ID (required)
    email: userEmail, // Optional
    name: userName, // Optional
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
  };
 
  const token = jwt.sign(
    payload,
    process.env.REFREF_CLIENT_SECRET, // Product secret from RefRef dashboard
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// Express.js route example
app.get('/api/refref-token', (req, res) => {
  const user = req.user; // From your authentication system
  const token = generateWidgetToken(
    user.id,
    'your-product-id',
    user.email,
    user.name
  );
 
  res.json({ token });
});
```

--------------------------------

### Add the RefRef Attribution Script Tag

Source: https://refref.ai/docs/platform/attribution-script

Add this script tag to your website's <head> section or before the closing </body> tag. The script initializes automatically when the DOM is ready.

```html
<script src="https://assets.refref.ai/attribution.js"></script>
```

--------------------------------

### Add Widget Script (CDN)

Source: https://refref.ai/docs/platform/installation/widget

Include the RefRef widget script in your page using the CDN URL. The 'defer' attribute ensures the script loads after parsing.

```html
<script src="https://assets.refref.app/widget.js" defer></script>
```

--------------------------------

### Listen to Widget Events

Source: https://refref.ai/docs/platform/installation/widget

Listen to widget events such as 'refref:link-copied', 'refref:shared', 'refref:loaded', and 'refref:error' to handle user actions and errors.

```javascript
const widget = document.querySelector('refref-widget');
 
// When user copies referral link
widget.addEventListener('refref:link-copied', (event) => {
  console.log('Link copied:', event.detail.link);
  // Show success toast
});
 
// When user shares on social media
widget.addEventListener('refref:shared', (event) => {
  console.log('Shared on:', event.detail.platform);
  // Track analytics
});
 
// When widget loads successfully
widget.addEventListener('refref:loaded', (event) => {
  console.log('Widget loaded:', event.detail);
});
 
// When widget encounters an error
widget.addEventListener('refref:error', (event) => {
  console.error('Widget error:', event.detail.message);
});
```

--------------------------------

### Add Widget Script

Source: https://refref.ai/docs/platform/widget

Include the RefRef widget script in your page. The script uses Web Components and loads asynchronously with no additional dependencies.

```html
<script src="https://assets.refref.ai/widget.js"></script>
```

--------------------------------

### Programmatic Control

Source: https://refref.ai/docs/platform/widget

Control the widget programmatically using window.RefRef.open(), close(), and toggle() methods.

```javascript
// Open widget programmatically
window.RefRef.open();
 
// Close widget
window.RefRef.close();
 
// Toggle widget
window.RefRef.toggle();
```

--------------------------------

### Verify script is loaded in browser console

Source: https://refref.ai/docs/platform/installation/attribution-script

Open your browser's developer console and check for the RefRef script. This logs whether the script is loaded.

```javascript
// Check if script loaded
console.log(typeof window.RefRef !== 'undefined' ? 'RefRef loaded' : 'RefRef not loaded');
```

--------------------------------

### Generate JWT Token (Node.js)

Source: https://refref.ai/docs/platform/installation/widget

Generate a JWT token on your backend using the jsonwebtoken library. The token includes the user's externalId, productId, and a 1-hour expiry. Never expose your client secret in frontend code.

```javascript
import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string) {
  const payload = {
    externalId: userId, // Your user's ID
    productId: productId, // Your RefRef product ID
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
  };
 
  const token = jwt.sign(
    payload,
    process.env.REFREF_CLIENT_SECRET, // Your product's client secret
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// API route example
app.get('/api/refref-token', async (req, res) => {
  const userId = req.user.id; // From your auth system
  const token = generateWidgetToken(userId, 'your-product-id');
 
  res.json({ token });
});
```

--------------------------------

### Add referral data to Chargebee checkout

Source: https://refref.ai/docs/platform/chargebee

Use this snippet to include referral identifiers (refref_id and refref_campaign) in the Chargebee checkout metadata. This enables automatic attribution of new subscriptions to the referrer. The metadata is passed to the openCheckout method along with standard callback handlers.

```javascript
// Adding referral data to Chargebee checkout
Chargebee.getInstance().openCheckout({
  hostedPage: hostedPageObj,
  loaded: function() {
    console.log("Checkout loaded");
  },
  success: function(hostedPageId) {
    // Handle success
  },
  close: function() {
    // Handle close
  },
  step: function(value) {
    // Handle step change
  },
  metadata: {
    refref_id: "REF123",
    refref_campaign: "summer_promo"
  }
});
```

--------------------------------

### LemonSqueezy Checkout URL with Referral ID

Source: https://refref.ai/docs/platform/lemonsqueezy

Add the referral identifier to the checkout URL or custom data so RefRef can automatically attribute the purchase to the referrer. Replace [store], [product], and REF123 with your actual values.

```text
https://[store].lemonsqueezy.com/checkout/buy/[product]?checkout[custom][refref_id]=REF123
```

--------------------------------

### Programmatic Control of Widget

Source: https://refref.ai/docs/platform/installation/widget

Control the widget programmatically using methods like refresh(), generateRefcode(), getParticipant(), and getStats().

```javascript
const widget = document.querySelector('refref-widget');
 
// Refresh widget data
widget.refresh();
 
// Generate new refcode
await widget.generateRefcode();
 
// Get current participant data
const participant = await widget.getParticipant();
console.log('Participant:', participant);
 
// Get referral stats
const stats = await widget.getStats();
console.log('Stats:', stats);
```

--------------------------------

### RefRef entity hierarchy

Source: https://refref.ai/docs

Shows the hierarchical structure of RefRef entities, from Organization down to Participants, Referrals, and Rewards.

```text
Organization
  └── Products
        └── Programs
              └── Participants → Referrals → Rewards
```

--------------------------------

### Capture refcode in Node.js/Express backend

Source: https://refref.ai/docs/platform/installation/attribution-script

When processing signups, capture the refcode from the form submission. Store the refcode for later use when firing events.

```javascript
app.post('/api/signup', async (req, res) => {
  const { email, password, refcode } = req.body;
 
  // Create user in your database
  const user = await createUser({ email, password });
 
  // Store refcode for later use when firing events
  if (refcode) {
    await storeRefcodeForUser(user.id, refcode);
  }
 
  res.json({ success: true, userId: user.id });
});
```

--------------------------------

### Embed Widget (HTML)

Source: https://refref.ai/docs/platform/installation/widget

Embed the refref-widget component in your HTML. The script fetches a token from your backend and sets it as an attribute on the widget.

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.app/widget.js" defer></script>
</head>
<body>
  <div id="refref-widget-container">
    <refref-widget
      product-id="your-product-id"
      token="USER_JWT_TOKEN">
    </refref-widget>
  </div>
 
  <script>
    // Fetch token from your backend
    async function loadWidget() {
      const response = await fetch('/api/refref-token');
      const { token } = await response.json();
 
      const widget = document.querySelector('refref-widget');
      widget.setAttribute('token', token);
    }
 
    loadWidget();
  </script>
</body>
</html>
```

--------------------------------

### Adding referral data to PayPal checkout

Source: https://refref.ai/docs/platform/paypal

Use this JavaScript snippet to add referral data to the PayPal checkout flow. It sets a custom_id containing the referral identifier and campaign, which RefRef uses to attribute the purchase to the referrer.

```javascript
// Adding referral data to PayPal checkout
paypal.Buttons({
  createOrder: function(data, actions) {
    return actions.order.create({
      purchase_units: [{
        amount: {
          value: '19.99'
        },
        custom_id: 'refref_id=REF123&refref_campaign=summer_promo'
      }]
    });
  },
  onApprove: function(data, actions) {
    // Handle successful payment
  }
}).render('#paypal-button-container');
```

--------------------------------

### Add referral data to Stripe checkout session

Source: https://refref.ai/docs/platform/stripe

Use this code when creating a Stripe Checkout session to include referral metadata. The metadata fields refref_referral_id and refref_campaign are required for RefRef to attribute the purchase to the referrer.

```javascript
const session = await stripe.checkout.sessions.create({
  line_items: [...],
  mode: 'payment',
  metadata: {
    refref_referral_id: 'REF123',
    refref_campaign: 'summer_promo'
  },
  ...
});
```

--------------------------------

### Enable Automatic Form Field Population with data-refref

Source: https://refref.ai/docs/platform/attribution-script

Add the `data-refref` attribute to your forms to enable automatic form field population. The script detects all forms with this attribute and adds a hidden `refcode` field automatically, working with static HTML, server-rendered pages, SPAs, and forms added after page load.

```html
<form data-refref action="/api/signup" method="POST">
  <input type="email" name="email" required />
  <input type="password" name="password" required />
  <!-- Hidden refcode field will be auto-created and populated -->
  <button type="submit">Sign Up</button>
</form>
```

--------------------------------

### Custom Trigger Button

Source: https://refref.ai/docs/platform/widget

Add a custom trigger button for the widget by using the data-refref-trigger attribute on any button element.

```html
<!-- Add data-refref-trigger attribute to any button -->
<button data-refref-trigger>Refer & Earn</button>
```

--------------------------------

### Add hidden form field with data-refref attribute

Source: https://refref.ai/docs/platform/installation/attribution-script

Add a hidden input field to your signup form with the data-refref attribute. The attribution script automatically finds all elements with data-refref="refcode" and populates them with the stored refcode.

```html
<form id="signup-form" action="/api/signup" method="POST">
  <input type="email" name="email" required />
  <input type="password" name="password" required />
 
  <!-- RefRef attribution field -->
  <input type="hidden" name="refcode" data-refref="refcode" />
 
  <button type="submit">Sign Up</button>
</form>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.