Tracking & referrals

Referrals & tracking pixel

The pixel ties clicks and purchases on your own website back to specific UGCBloom creators. Every creator in a tracked campaign gets a unique share URL like https://yourbrand.com/?infl=ANNIE50 — where ANNIE50 is their unique code on this campaign. When a visitor lands on your site via that URL, the pixel does the rest.

Stores the referral in a first-party cookie on your domain (90-day window).
Records a page_view event so you can see traffic by creator.
Exposes window.UGCBloom so your client code can read the bound state (creator handle, code, campaign id) if you want to surface it in the UI.

Final attribution happens when the customer redeems the code at Stripe — we record the conversion and credit the creator automatically. The pixel's job is just to make sure the right code is in front of the right customer at the right moment.

Install the pixel

Copy the snippet from Settings → Integrations → Tracking pixel (your org id is baked in) and add it to every page of your site — landing pages, product pages, and checkout.

index.html

html

<script src="https://ugcbloom.com/api/script.js" data-org="org_your_org_id" defer></script>

The script is tiny (~3 KB), runs asynchronously, and won't block your page load. It de-dupes itself if you accidentally embed it twice.

On the first visit with an ?infl= param, the pixel calls /api/promolink to resolve the code, then writes a first-party cookie named ugcbloom_ref on your domain. The cookie is base64-url-encoded JSON with a 90-day sliding max-age (refreshed on every page view).

ugcbloom_ref · decoded

json

{
  "session_id":    "0e8b…",        // random uuid, identifies this visitor
  "code":          "ANNIE50",      // the code from the ?infl= param
  "handle":        "annie",         // resolved creator handle
  "creator_id":    "user_abc123",  // resolved creator id
  "promo_code_id": "uuid",         // promo code id (use in /api/event)
  "campaign_id":   "uuid",         // which campaign this code belongs to
  "expires_at":    1735689600
}

Because the cookie is set client-side on your origin, your own server can read it on subsequent requests just like any other first-party cookie. That's the foundation for the server-side Stripe integration described below.

Applying coupons at Stripe checkout

Two server-side patterns, ordered by how reliably they survive real-world conditions (cookie clearing, device switching, long signup-to-purchase gaps).

Bind to your user id (recommended)

At signup, you bind the anonymous referral cookie to your own stable user id. From then on, attribution survives anything that breaks cookies. Full walkthrough in the Set up referral tracking guide. Short version:

At signup. Read the raw ugcbloom_ref cookie value, then POST /api/customers/identify with your user id and an API key. We decode the cookie server-side:

on signup (server)

bash

curl -X POST "https://ugcbloom.com/api/customers/identify" \
  -H "Authorization: Bearer $UGCBLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user_42","ref":"<value of ugcbloom_ref cookie>"}'

At checkout. Look up the bound referral and feed the discount into Stripe:

checkout.ts

// Replace price_your_stripe_price_id with your own Stripe price id.
const lookup = await fetch(
  `https://ugcbloom.com/api/customers?externalId=${user.id}`,
  { headers: { Authorization: `Bearer ${process.env.UGCBLOOM_API_KEY}` } },
).then((r) => r.json());
const discount = lookup.data?.discount;

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_your_stripe_price_id", quantity: 1 }],
  ...(discount
    ? { discounts: [{ promotion_code: discount.stripe_promotion_code_id }] }
    : { allow_promotion_codes: true }),
});

Pass whatever you want as the externalId: a user id, an email, a UUID. We hash it on receipt with sha256(org_id + ":" + value)and never persist the raw value. The brand DB has it, ours doesn't.

If you don't want to bind via /api/customers/identify, you can still drive checkout from your server by reading the cookie directly and passing the promo code straight to Stripe. Works fine for single-session DTC flows. Breaks on cross-device, cleared cookies, and SaaS-style long funnels.

create-checkout.ts

// Replace price_your_stripe_price_id and the yourbrand.com URLs with your own values.
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Call this from your checkout handler. Returns a Stripe Checkout Session.
// Pass the value of the ugcbloom_ref cookie however your framework exposes it.
export async function createCheckoutFromCookie(ugcbloomRef: string | undefined) {
  let ref: { code?: string } | null = null;
  if (ugcbloomRef) {
    try {
      const padded = ugcbloomRef.replace(/-/g, "+").replace(/_/g, "/");
      ref = JSON.parse(Buffer.from(padded, "base64").toString("utf-8"));
    } catch {
      ref = null;
    }
  }

  return stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: "price_your_stripe_price_id", quantity: 1 }],
    discounts: ref?.code ? [{ promotion_code: ref.code }] : undefined,
    success_url: "https://yourbrand.com/success",
    cancel_url:  "https://yourbrand.com/cancel",
  });
}

Stripe's promotion_code parameter takes the human-readable code string (e.g. ANNIE50) and resolves it server-side, so the customer doesn't need to type anything. Attribution to the creator happens automatically once the customer redeems.

Install the pixel

The cookie

Applying coupons at Stripe checkout

Bind to your user id (recommended)

Cookie-only (server-side)