How to Set Up BTCPay Server Referral and Affiliate Tracking

If you use Oshi's referral or affiliate programs with BTCPay Server, you need to make sure referral tracking carries through from the initial link click all the way to the BTCPay invoice. Without this, Oshi can't attribute purchases to the referrer and commissions won't be issued.

How It Works

When a customer clicks a referral or affiliate link, they land on your website with a URL like this:

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

Here's what each parameter does:

• ref — The referral or affiliate code. This is how Oshi identifies who referred the customer.
• utm_source, utm_medium, utm_campaign — Standard tracking parameters.
• ttl — How long (in seconds) the referral should be tracked. For example, 7776000 = 90 days. Use this as your cookie expiry — a session cookie that disappears when the browser closes will break tracking.
• policy — Attribution policy. first means don't overwrite an existing referral cookie.

Your site needs to:

1. Capture those parameters when the customer lands
2. Store them (via cookies or local storage) so they persist as the customer browses
3. Include them in the BTCPay invoice metadata when the customer checks out

Implementation

Capture and Store Referral Parameters

When a customer lands on your site from a referral link, extract all URL parameters (e.g., ref, utm_source, campaign, ttl, etc.) and store them. Use cookies or local storage so the values persist if the customer navigates to other pages before checking out.

Include Parameters in Invoice Metadata

When creating the BTCPay invoice at checkout, pass the stored referral values in the metadata:

{
  "metadata": {
    "email": "customer@example.com",
    "ref": "pvHefU",
    "utm_source": "oshi",
    "buyerAcceptsMarketing": true
  }
}

When Oshi receives this invoice, it matches the ref value to the referrer or affiliate and issues the appropriate rewards and commissions in Bitcoin.

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.
• Connect BTCPay Server — If you haven't connected yet, start there first.