Advertiser Integration Guide

User clicks affiliate link
    │
    ▼
https://your-site.com/landing?swarm_ref=abc123xyz
    │
    ├── Step 1: YOUR CODE captures the ?swarm_ref= parameter
    │
    ▼
User converts on your platform (purchase, signup, etc.)
    │
    ├── Step 2: YOUR CODE fires a postback to AffiliateSwarm
    │
    ▼
AffiliateSwarm creates a verified lead, credits the affiliate

// Add this to your landing page
const params = new URLSearchParams(window.location.search);
const swarmRef = params.get("swarm_ref");

if (swarmRef) {
  // Store in a cookie (30 days)
  document.cookie = "swarm_ref=" + swarmRef + "; path=/; max-age=2592000; SameSite=Lax";

  // Also send to your backend for server-side storage
  fetch("/api/store-ref", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ swarm_ref: swarmRef }),
  });
}

// Middleware: capture swarm_ref on any incoming request
app.use((req, res, next) => {
  const swarmRef = req.query.swarm_ref;
  if (swarmRef) {
    // Store in session (or database tied to user)
    req.session.swarmRef = swarmRef;
  }
  next();
});

from flask import request, session

@app.before_request
def capture_swarm_ref():
    swarm_ref = request.args.get("swarm_ref")
    if swarm_ref:
        session["swarm_ref"] = swarm_ref

class ApplicationController < ActionController::Base
  before_action :capture_swarm_ref

  private

  def capture_swarm_ref
    if params[:swarm_ref].present?
      session[:swarm_ref] = params[:swarm_ref]
    end
  end
end

<?php
session_start();

if (isset($_GET['swarm_ref'])) {
    $_SESSION['swarm_ref'] = $_GET['swarm_ref'];
}
?>

https://your-site.com/signup?swarm_ref=abc123xyz&promo=SWARM20

app.use((req, res, next) => {
  const swarmRef = req.query.swarm_ref;
  const promo = req.query.promo;
  if (swarmRef) {
    req.session.swarmRef = swarmRef;
    res.cookie("swarm_ref", swarmRef, { path: "/", maxAge: 30 * 24 * 60 * 60 * 1000, sameSite: "lax" });
  }
  if (promo) {
    req.session.swarmPromo = promo;
    res.cookie("swarm_promo", promo, { path: "/", maxAge: 30 * 24 * 60 * 60 * 1000, sameSite: "lax" });
  }
  next();
});

import { useEffect, useState } from "react";

function useSwarmPromo(): string | null {
  const [promo, setPromo] = useState<string | null>(null);
  useEffect(() => {
    const match = document.cookie.match(/swarm_promo=([^;]+)/);
    if (match) setPromo(decodeURIComponent(match[1]));
  }, []);
  return promo;
}

// In your checkout component
function CheckoutPage() {
  const swarmPromo = useSwarmPromo();
  const [promoCode, setPromoCode] = useState("");

  useEffect(() => {
    if (swarmPromo) setPromoCode(swarmPromo);
  }, [swarmPromo]);

  return (
    <input
      placeholder="Add promotion code"
      value={promoCode}
      onChange={(e) => setPromoCode(e.target.value)}
    />
  );
}

function getSwarmPromo() {
  const match = document.cookie.match(/swarm_promo=([^;]+)/);
  return match ? decodeURIComponent(match[1]) : null;
}

document.addEventListener("DOMContentLoaded", () => {
  const promo = getSwarmPromo();
  if (promo) {
    // Adjust the selector to match your promotion code input
    const input = document.querySelector('input[placeholder*="promotion code"]');
    if (input) {
      input.value = promo;
      input.dispatchEvent(new Event("input", { bubbles: true }));
      input.dispatchEvent(new Event("change", { bubbles: true }));
    }
  }
});

curl -X POST https://affiliateswarm.ai/api/v1/postback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "swarm_ref": "abc123xyz",
    "externalId": "order_12345",
    "eventType": "PURCHASE",
    "revenueCents": 9900,
    "metadata": { "plan": "pro", "orderId": "order_12345" }
  }'

// Call this from your payment webhook or order-completion handler.
// The postback is fire-and-forget from the buyer's perspective: log
// failures, never throw back into the request handler that's serving
// the buyer's confirmation page. Conversion tracking is between you
// and AffiliateSwarm — the buyer is not part of that conversation.
async function reportConversion(swarmRef, orderId, amountCents) {
  try {
    const response = await fetch("https://affiliateswarm.ai/api/v1/postback", {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + process.env.AFFILIATESWARM_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        swarm_ref: swarmRef,
        externalId: orderId,
        eventType: "PURCHASE",
        revenueCents: amountCents,
      }),
    });

    if (!response.ok) {
      console.error("[affiliateswarm] postback non-2xx", response.status, await response.text());
    }
  } catch (err) {
    console.error("[affiliateswarm] postback threw", err);
  }
}

import logging
import os

import requests

logger = logging.getLogger(__name__)

def report_conversion(swarm_ref, order_id, amount_cents):
    """Fire-and-forget. Log failures; never raise into the checkout handler."""
    try:
        response = requests.post(
            "https://affiliateswarm.ai/api/v1/postback",
            headers={
                "Authorization": f"Bearer {os.environ['AFFILIATESWARM_API_KEY']}",
                "Content-Type": "application/json",
            },
            json={
                "swarm_ref": swarm_ref,
                "externalId": order_id,
                "eventType": "PURCHASE",
                "revenueCents": amount_cents,
            },
            timeout=10,
        )
        if not response.ok:
            logger.error(
                "affiliateswarm postback non-2xx",
                extra={"status": response.status_code, "body": response.text},
            )
    except requests.RequestException:
        logger.exception("affiliateswarm postback failed")

require "net/http"
require "json"
require "uri"

# Fire-and-forget. Log failures; do not raise into the checkout handler.
def report_conversion(swarm_ref, order_id, amount_cents)
  uri = URI("https://affiliateswarm.ai/api/v1/postback")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = uri.scheme == "https"

  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer #{ENV['AFFILIATESWARM_API_KEY']}"
  request["Content-Type"] = "application/json"
  request.body = {
    swarm_ref: swarm_ref,
    externalId: order_id,
    eventType: "PURCHASE",
    revenueCents: amount_cents
  }.to_json

  response = http.request(request)
  unless response.is_a?(Net::HTTPSuccess)
    Rails.logger.error("[affiliateswarm] postback non-2xx #{response.code}: #{response.body}")
  end
rescue StandardError => e
  Rails.logger.error("[affiliateswarm] postback failed: #{e.message}")
end

<?php
// Fire-and-forget. Log failures; do not surface them to the buyer.
function reportConversion($swarmRef, $orderId, $amountCents) {
    $ch = curl_init("https://affiliateswarm.ai/api/v1/postback");

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("AFFILIATESWARM_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            "swarm_ref" => $swarmRef,
            "externalId" => $orderId,
            "eventType" => "PURCHASE",
            "revenueCents" => $amountCents,
        ]),
    ]);

    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error !== "" || $status < 200 || $status >= 300) {
        error_log("[affiliateswarm] postback failed status={$status} error={$error} body={$response}");
    }
}
?>

curl -X POST https://affiliateswarm.ai/api/v1/postback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "swarm_ref": "YOUR_TEST_TRACKING_CODE",
    "externalId": "test-confirm-1",
    "eventType": "PURCHASE",
    "revenueCents": 1000
  }'

{
  "success": true,
  "data": {
    "test": true,
    "id": "test-lead-uuid",
    "leadId": "test-lead-uuid",
    "created": false,
    "campaignId": "YOUR_CAMPAIGN_ID",
    "externalId": "test-confirm-1",
    "trackingConfirmedAt": "2026-04-28T15:30:00.000Z",
    "message": "Test postback received — tracking confirmed. You can now activate this campaign."
  }
}