API Endpoints

Server-side referral tracking endpoints

On this page

Referral API Endpoints

If you prefer server-side referral tracking (or need it for backend-only integrations), you can call these endpoints directly instead of using the JavaScript tracking script.

All referral endpoints support CORS and do not require API key authentication.

Referral vs affiliate campaigns: Referral campaigns award points on signups and purchases. Affiliate campaigns award dollar commission on referred purchases using an exclusive payout structure — either a percentage of sale or a flat rate per sale (not both). Signup tracking does not pay commission on affiliate campaigns (purchase-only). Purchase responses include pointsAwarded for referral mode and commissionAwarded for affiliate mode.

Validate Referral Code

GET/api/referral/validate-code
No authentication required

Check if a referral code is valid and retrieve information about the referrer.

Query Parameters

codestring required

The referral code to validate

contestIdstring required

The contest identifier

Request

curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"

const params = new URLSearchParams({
  code: "REF-XYZ789",
  contestId: "clx1abc123",
});

const response = await fetch(
  `https://blitzrocket.com/api/referral/validate-code?${params}`
);

const data = await response.json();
if (data.valid) {
  console.log(`Referred by: ${data.referrerName || data.referrerEmail}`);
}

import requests

response = requests.get(
    "https://blitzrocket.com/api/referral/validate-code",
    params={
        "code": "REF-XYZ789",
        "contestId": "clx1abc123"
    }
)

data = response.json()
if data.get("valid"):
    print(f"Referred by: {data.get('referrerName') or data.get('referrerEmail')}")

Response

{
  "valid": true,
  "referrerEmail": "[email protected]",
  "referrerName": "Jane Doe",
  "contestId": "clx1abc123"
}

Track Visit

POST/api/referral/track-visit
No authentication required

Record that someone visited your site through a referral link.

Request Body

referralCodestring required

The referral code from the URL

contestIdstring required

The contest identifier

urlstring

The page URL that was visited (optional)

Request

curl -X POST https://blitzrocket.com/api/referral/track-visit \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123",
    "url": "https://yoursite.com/landing-page"
  }'

await fetch("https://blitzrocket.com/api/referral/track-visit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    referralCode: "REF-XYZ789",
    contestId: "clx1abc123",
    url: window.location.href,
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-visit",
    json={
        "referralCode": "REF-XYZ789",
        "contestId": "clx1abc123",
        "url": "https://yoursite.com/landing-page"
    }
)

Response

{
  "success": true
}

Track Signup

POST/api/referral/track-signup
No authentication required

Record that a referred visitor has signed up.

Request Body

emailstring required

Email address of the new signup

contestIdstring required

The contest identifier

referralCodestring

The referral code of the person who referred them (optional for direct signups)

externalSiteUrlstring required

URL of the page where the signup occurred

namestring

Name of the new signup (optional)

Request

curl -X POST https://blitzrocket.com/api/referral/track-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "externalSiteUrl": "https://yoursite.com/signup"
  }'

await fetch("https://blitzrocket.com/api/referral/track-signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    contestId: "clx1abc123",
    referralCode: "REF-XYZ789",
    name: "New User",
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-signup",
    json={
        "email": "[email protected]",
        "contestId": "clx1abc123",
        "referralCode": "REF-XYZ789",
        "name": "New User"
    }
)

Response

{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

Track Purchase

POST/api/referral/track-purchase
No authentication required

Record that a referred user has made a purchase. Used by RocketTracker.trackPurchase() in blitzrocket.js.

Request Body

campaignIdstring required

The contest identifier (same as contestId)

referralCodestring required

The advocate's referral code

orderIdstring required

Unique order identifier

amountnumber required

Purchase amount

externalSiteUrlstring required

URL of the page where the purchase occurred

emailstring

Email address of the purchaser (optional)

phonestring

Phone of the purchaser (optional)

currencystring

Currency code (default: 'USD')

Request

curl -X POST https://blitzrocket.com/api/referral/track-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "orderId": "order-12345",
    "amount": 99.99,
    "currency": "USD",
    "externalSiteUrl": "https://yoursite.com/checkout/success",
    "email": "[email protected]"
  }'

await fetch("https://blitzrocket.com/api/referral/track-purchase", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    campaignId: "clx1abc123",
    referralCode: "REF-XYZ789",
    orderId: "order-12345",
    amount: 99.99,
    currency: "USD",
    externalSiteUrl: "https://yoursite.com/checkout/success",
    email: "[email protected]",
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-purchase",
    json={
        "campaignId": "clx1abc123",
        "referralCode": "REF-XYZ789",
        "orderId": "order-12345",
        "amount": 99.99,
        "currency": "USD",
        "externalSiteUrl": "https://yoursite.com/checkout/success",
        "email": "[email protected]",
    }
)

Response

Referral campaign (points):

{
  "success": true,
  "message": "Purchase tracked successfully",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 50, "friend": 10 },
  "commissionAwarded": { "advocate": 0 }
}

Affiliate campaign (dollar commission):

{
  "success": true,
  "message": "Purchase tracked successfully",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 0, "friend": 0 },
  "commissionAwarded": { "advocate": 24.99 }
}

For email-only purchase tracking (no referral code in the request), use POST /api/contest/track-purchase instead.

Complete Server-Side Example

Here's a complete example of implementing referral tracking on your server:

const express = require("express");
const app = express();

const BLITZROCKET_BASE = "https://blitzrocket.com/api/referral";
const CONTEST_ID = process.env.CONTEST_ID;

app.post("/api/signup", async (req, res) => {
  const { email, name, referralCode } = req.body;

  // 1. Create user in your system
  const user = await createUser({ email, name });

  // 2. Track the referred signup in Blitz Rocket
  if (referralCode) {
    await fetch(`${BLITZROCKET_BASE}/track-signup`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        name,
        contestId: CONTEST_ID,
        referralCode,
      }),
    });
  }

  res.json({ success: true, user });
});

app.post("/api/purchase", async (req, res) => {
  const { email, orderId, amount, currency } = req.body;

  // 1. Process the purchase in your system
  const order = await processOrder({ email, orderId, amount });

  // 2. Track the purchase in Blitz Rocket
  await fetch(`${BLITZROCKET_BASE}/track-purchase`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email,
      contestId: CONTEST_ID,
      orderId,
      amount,
      currency,
    }),
  });

  res.json({ success: true, order });
});

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

BLITZROCKET_BASE = "https://blitzrocket.com/api/referral"
CONTEST_ID = os.environ["CONTEST_ID"]

@app.route("/api/signup", methods=["POST"])
def signup():
    data = request.get_json()
    email = data["email"]
    name = data.get("name")
    referral_code = data.get("referralCode")

    # 1. Create user in your system
    user = create_user(email=email, name=name)

    # 2. Track the referred signup in Blitz Rocket
    if referral_code:
        requests.post(
            f"{BLITZROCKET_BASE}/track-signup",
            json={
                "email": email,
                "name": name,
                "contestId": CONTEST_ID,
                "referralCode": referral_code
            }
        )

    return jsonify({"success": True, "user": user})

@app.route("/api/purchase", methods=["POST"])
def purchase():
    data = request.get_json()

    # 1. Process the purchase
    order = process_order(data)

    # 2. Track in Blitz Rocket
    requests.post(
        f"{BLITZROCKET_BASE}/track-purchase",
        json={
            "email": data["email"],
            "contestId": CONTEST_ID,
            "orderId": data["orderId"],
            "amount": data["amount"],
            "currency": data.get("currency", "USD")
        }
    )

    return jsonify({"success": True, "order": order})