Convert participants using the Server-Side API

When conversion events happen securely in your backend—such as payment processor webhooks, subscription renewals, database updates, or off-line transactions—triggering conversions on the client side with JavaScript is not an option.

By using the Viral Loops Server-Side / Private API, you can securely report participant conversions directly from your server.

When to Use API Conversion Tracking

Server-side API conversion tracking is ideal when:

Transactions occur on the backend: Payment processing via Stripe, PayPal, or Paddle, where the final confirmation happens via webhook.
Events happen asynchronously: Subscriptions that convert after a free trial period ends, or delayed manual account approvals.
High security is required: Preventing malicious users from attempting to trigger client-side JavaScript conversion calls artificially.
Value Tracking is involved: Transmitting sensitive transaction amounts or purchase values directly from your secure database.

Prerequisites

Viral Loops API Token: Your secret API key, available in your Viral Loops Campaign Settings > API Credentials. Keep this key secure and never expose it in public client-side code.
Participant Identifier: You need a way to identify which participant converted. This can be their email, userCode (referral code), or refCode.
Plan & Template: Conversion API requests are available on the Growing Plan or higher across supported templates (The Milestone Referral, The Altruistic Referral, Online to Offline, The Universal Referral, and The Tempting Giveaway).

How to Make the Conversion API Request

To trigger a conversion, send a POST request from your backend to the Viral Loops API endpoint.

API Endpoint

POST https://app.viral-loops.com/api/v2/events
Content-Type: application/json

Request Payload

Include your secret API token along with the event name "conversion" and the identifying details of the converted participant.

{
  "apiToken": "YOUR_VIRAL_LOOPS_API_TOKEN",
  "params": {
    "event": "conversion",
    "user": {
      "email": "[email protected]"
    }
  }
}

Tracking Conversion Value (Optional)

If your campaign measures purchase volume or revenue generated by referrals, you can pass transaction values alongside the conversion event.

Add the value property inside your params payload:

{
  "apiToken": "YOUR_VIRAL_LOOPS_API_TOKEN",
  "params": {
    "event": "conversion",
    "user": {
      "email": "[email protected]"
    },
    "options": {
      "value": 49.99
    }
  }
}

Example Integratoin: Webhook Handler (Node.js)

Here is a practical example of triggering a conversion when receiving a successful payment notification in a Node.js backend:

const express = require('express');
const fetch = require('node-fetch');
const app = express();

app.use(express.json());

app.post('/webhooks/payment-success', async (req, res) => {
  const { customerEmail, orderTotal } = req.body;

  try {
    const response = await fetch('[https://app.viral-loops.com/api/v2/events](https://app.viral-loops.com/api/v2/events)', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        apiToken: process.env.VIRAL_LOOPS_API_TOKEN,
        params: {
          event: 'conversion',
          user: {
            email: customerEmail
          },
          value: orderTotal
        }
      })
    });

    const data = await response.json();

    if (response.ok) {
      console.log('Conversion recorded successfully in Viral Loops:', data);
      res.status(200).send({ status: 'success' });
    } else {
      console.error('Viral Loops API Error:', data);
      res.status(400).send({ status: 'error', details: data });
    }
  } catch (error) {
    console.error('Failed to trigger conversion event:', error);
    res.status(500).send({ status: 'internal_error' });
  }
});

Best Practices & Tips

Idempotency & Duplicate Calls: The Viral Loops backend handles duplicate conversion events for a given participant based on your campaign settings. However, it's good practice to ensure your server logic only calls the conversion API once per converted action.
Keep API Keys Confidential: Never call the API endpoint using secret tokens directly from frontend JavaScript, mobile apps, or public repositories.
Value Tracking Setup: Ensure that Value Tracking is enabled under the Goals step in your Viral Loops campaign wizard if you intend to send numerical monetary values.
Accept only Authorized Conversions: Viral Loops supports blocking all conversions from public clients using the frontend JavaScript SDK and/or the campaign's public token