Set up referral tracking

Step 1. Install the pixel

Each creator in a tracked campaign has a unique share URL like https://yourbrand.com/?infl=ANNIE50 — where ANNIE50is the creator's unique code. When a referred visitor lands on your site, the pixel resolves the handle, stores the referral in a first-party ugcbloom_ref cookie on your domain, and exposes window.UGCBloom if your client code needs to read the bound state.

Already done? Skip to Step 2. If not, copy the snippet from Settings → Integrations → Tracking pixel (your org id is baked in) and add it to every page of your site.

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

Step 2. Identify the visitor at signup (server-side)

From the same request handler that creates the user, read the raw ugcbloom_ref cookie value (don't decode it — we do that on receipt) and POST it to /api/customers/identify with an API key (created in Settings → API Keys with the referrals scope enabled). We hash whatever you pass as externalId on receipt and never store the raw value.

const UGC_API_KEY = process.env.UGCBLOOM_API_KEY!;

// Call this from your signup handler after the user is created. Pass the value
// of the ugcbloom_ref cookie however your framework exposes it
// (e.g. req.cookies.ugcbloom_ref in Express).
export async function bindReferral(userId: string, ugcbloomRef: string | undefined) {
  if (!ugcbloomRef) return;
  await fetch("https://ugcbloom.com/api/customers/identify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${UGC_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ externalId: userId, ref: ugcbloomRef }),
  });
}

Call this once, on the request that completes signup. Idempotent on (org, externalId) — later calls just refresh the binding. If the visitor never had a referral cookie, skip the call. Returns 204 on success.

Step 3. Apply the discount at Stripe checkout

From your backend, on the request that creates a Stripe Checkout Session, look up the bound referral state and feed the promo code into Stripe's discounts parameter. Pick your stack:

// 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!);
const UGC_API_KEY = process.env.UGCBLOOM_API_KEY!;

// Call this from your checkout handler. Returns a Stripe Checkout Session.
export async function createCheckoutForUser(userId: string, userEmail: string) {
  // 1. Look up referral state for this user
  const lookup = await fetch(
    `https://ugcbloom.com/api/customers?externalId=${encodeURIComponent(userId)}`,
    { headers: { Authorization: `Bearer ${UGC_API_KEY}` } },
  ).then((r) => r.json());
  const discount = lookup.data?.discount;

  // 2. Create the Stripe Checkout Session with the discount applied
  return stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: "price_your_stripe_price_id", quantity: 1 }],
    customer_email: userEmail,
    success_url: "https://yourbrand.com/upgraded",
    cancel_url:  "https://yourbrand.com/pricing",
    ...(discount
      ? { discounts: [{ promotion_code: discount.stripe_promotion_code_id }] }
      : { allow_promotion_codes: true }),
    metadata: {
      userId,
      ...(discount && {
        ugcbloomPromoCode: discount.promotion_code,
        ugcbloomCampaignId: discount.campaign_id,
      }),
    },
  });
}

The discount payload also returns the underlying stripe_coupon_idif you prefer to apply the discount via Stripe's coupon field instead of promotion_code. Both work. The choice depends on whether you want the code to remain typeable for the customer (use promotion_code) or applied silently (use coupon).

Conversion attribution is automatic from here. When the customer completes checkout, we match the redeemed promo code and credit the creator.

Test your integration

Three quick checks confirm everything is wired up:

1. Click a referral link. Visit https://yourbrand.com/?infl=ANNIE50 (use any active code from your campaigns). Confirm the ugcbloom_ref cookie is set on your domain via DevTools → Application → Cookies.
2. Bind manually from your terminal. Copy the ugcbloom_ref cookie value from DevTools and paste it into the curl below as the ref field. Simulates Step 2 against a test externalId:

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

Expect 204. Then look up the binding:

curl "https://ugcbloom.com/api/customers?externalId=test_user_42" \
  -H "Authorization: Bearer ugcb_live_your_api_key_here"

Expect a JSON response with creator, campaign, and discount populated. If everything returns null, check that the creator handle has an active promo code for this org.

Privacy

Pass anything you want as the externalId. We hash it on receipt and never persist the raw value.

external_id_hash = hmac_sha256( server_secret, org_id + ":" + raw_value )

It's a keyed HMAC, not a plain hash — so even if our table were ever exposed, the hashes can't be brute-forced without the server-side secret. The org-id in the message also means the same email under different brands produces different hashes, so they can't be correlated across brands.

API reference

const response = await fetch(
  "https://ugcbloom.com/api/customers/identify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: "{\"externalId\":\"user_42\",\"ref\":\"eyJzZXNzaW9uX2lkIjoi…\"}"
}
);

const data = await response.json();

const response = await fetch(
  "https://ugcbloom.com/api/customers?externalId=user_42", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

{
  "data": {
    "creator": { "id": "user_abc123", "handle": "annie", "avatar_url": null },
    "campaign": { "id": "550e8400-…", "title": "Summer drop" },
    "discount": {
      "promotion_code": "ANNIE50",
      "stripe_promotion_code_id": "promo_xyz",
      "stripe_coupon_id": "coupon_abc",
      "discount_type": "percent_off",
      "discount_value": 20,
      "campaign_id": "550e8400-…"
    }
  }
}