How to Set Up Referral and Affiliate Tracking on Your Website

When a customer clicks a referral or affiliate link, they're sent to your website with tracking parameters in the URL. If your website doesn't capture and pass those parameters through to checkout, Oshi can't attribute the purchase to the referrer — and commissions won't be issued.

This guide covers the general pattern for any website or payment setup. If you use a specific platform, also see:

• Zaprite referral tracking
• BTCPay Server referral tracking

How Referral Links Work

When Oshi generates a referral or affiliate link, it sends the customer to your website with these URL parameters:

A typical referral URL looks like:

https://yourstore.com?ref=pvHefU&utm_source=oshi&utm_medium=referral&utm_campaign=ref_pvHefU&ttl=7776000&policy=first

What Your Website Needs to Do

There are three steps your site must handle:

1. Capture the Parameters

When a customer lands on your site, read the URL parameters from the query string.

// Read Oshi referral parameters from the URL
const params = new URLSearchParams(window.location.search);
const oshiParams = {};

['ref', 'utm_source', 'utm_medium', 'utm_campaign', 'ttl', 'policy'].forEach(key => {
  const value = params.get(key);
  if (value) oshiParams[key] = value;
});

2. Store Them

Save the parameters so they persist as the customer browses your site. Cookies are the most reliable option since they survive page navigations and can be read server-side.

// Store referral parameters in a cookie (expires when attribution window ends)
if (oshiParams.ref) {
  const ttlSeconds = parseInt(oshiParams.ttl || '7776000', 10); // Default: 90 days
  const expires = new Date(Date.now() + ttlSeconds * 1000).toUTCString();

  document.cookie = `oshi_referral=${encodeURIComponent(JSON.stringify(oshiParams))}; expires=${expires}; path=/; SameSite=Lax`;
}

3. Pass Them to Your Checkout

When the customer checks out, include the stored parameters so Oshi can match the purchase to the referrer. How you do this depends on your payment setup:

Option A: Append to checkout URL

If your checkout is on another domain or service, append the parameters to the checkout link:

// Read stored parameters
function getOshiReferral() {
  const match = document.cookie.match(/oshi_referral=([^;]+)/);
  if (!match) return null;
  return JSON.parse(decodeURIComponent(match[1]));
}

// Append to any checkout link
function appendReferralParams(checkoutUrl) {
  const referral = getOshiReferral();
  if (!referral) return checkoutUrl;

  const url = new URL(checkoutUrl);
  Object.entries(referral).forEach(([key, value]) => {
    url.searchParams.set(key, value);
  });
  return url.toString();
}

Option B: Include in payment metadata

If you create invoices or payment requests via an API (e.g., BTCPay Server, Zaprite API), include the parameters in the metadata:

{
  "metadata": {
    "email": "customer@example.com",
    "ref": "pvHefU",
    "utm_source": "oshi",
    "utm_medium": "referral",
    "utm_campaign": "ref_pvHefU"
  }
}

Testing

To verify your implementation:

1. Open a referral or affiliate link for your business (you can find these in Referrals > Affiliates in your dashboard)
2. Confirm the URL parameters appear when you land on your site
3. Browse to another page — confirm the cookie persists
4. Go through your checkout flow — confirm the parameters are included in the checkout URL or payment metadata

What's Next

• Set up referral rewards — Configure what referrers and referred friends earn.
• Set up your affiliate program — Create affiliate links and commission structures.
• Add custom products — If you don't use Shopify or WooCommerce, manually add products to the Oshi marketplace.