Affiliate Tracking URL Parameters

AffiliateBase tracks affiliates through one standard URL parameter, via. This guide is for merchants and affiliates and covers the parameters the tracking script reads, the order it checks them, and how to build affiliate links, short links, and QR codes that keep attribution.

Supported parameters

Use via for link-token attribution:

You can add custom parameter names in the script tag:

<script
  async
  src="https://app.affiliatebase.io/track.js"
  data-account-id="YOUR_ACCOUNT_ID"
  data-affiliatebase-params="partner,invite"
></script>

data-params is also supported as an alias for data-affiliatebase-params.

How parameters work

Basic usage

Add the parameter to any URL on your site:

https://yoursite.com?via=john
https://yoursite.com/pricing?via=john
https://yoursite.com/features?via=john&utm_source=twitter

Parameter processing

When a visitor lands with a tracking parameter:

1. The script detects the parameter.
2. AffiliateBase validates the affiliate token.
3. AffiliateBase creates or updates the referral record.
4. The script stores the referral in the browser.
5. The script removes the token parameter from the address bar once tracking succeeds.

The script also reads via (and any custom parameter) from the URL hash, for example #via=john.

Token validation

The token must belong to an unarchived link of a pending or active affiliate in a campaign that isn’t archived. AffiliateBase ignores other tokens:

• Tokens that don’t exist or belong to an archived link: no tracking.
• Tokens for suspicious, rejected, disabled, banned, or archived affiliates: no tracking.
• Tokens in an archived campaign: no tracking.
• Valid tokens: referral created.

URL examples

Simple links

https://yoursite.com?via=john

Links with paths

https://yoursite.com/pricing?via=john
https://yoursite.com/blog/post-title?via=john

Links with other parameters

Tracking parameters work alongside other query parameters:

https://yoursite.com?via=john&utm_source=twitter&utm_medium=social
https://yoursite.com?plan=pro&via=john

Clean URLs

Some affiliates prefer shorter paths:

https://yoursite.com/go/john  (requires server-side redirect)

Parameter priority

If a URL has more than one tracking parameter, the tracking script checks them in this order and uses the first one it finds:

1. ab_handoff, a reserved parameter the script adds to approved cross-domain links. Don’t create it yourself. See Tracking and Attribution Reference.
2. referral (a referral preload)
3. via
4. Custom parameters from data-affiliatebase-params (or data-params), in the order listed

?via=john&partner=sarah → "john" is used (when partner is a custom parameter)
?referral=existing-referral-uuid&via=john → the existing referral is loaded; "john" is ignored

Special parameters

Referral preloading

Load an existing referral without creating new tracking:

?referral=existing-referral-uuid

Use it for return visitors from email links when you’ve stored their referral ID.

A referral ID in a URL works like an affiliate link: any browser that opens it is attributed to that referral, including the same visitor on another device. Preloading is rejected, and the visitor is not attributed, when:

• the referral has expired or been deactivated;
• the affiliate is not pending or active;
• the campaign is archived;
• the referral belongs to a different AffiliateBase account.

Only put a referral ID in links meant for the visitor it belongs to. Don’t publish or broadly share such a URL: everyone who opens it is credited to that affiliate. To carry a referral across your own domains, use approved-host handoff instead of a raw ?referral= link.

Custom parameters

Configure custom parameters

Add a script attribute to accept custom token parameter names. The via parameter always stays active.

• data-affiliatebase-params="partner,invite"
• data-params="partner,invite" (alias)

For affiliates

Create links

Affiliates can link to any page:

Main site: https://yoursite.com?via=TOKEN
Pricing:   https://yoursite.com/pricing?via=TOKEN
Features:  https://yoursite.com/features?via=TOKEN
Blog:      https://yoursite.com/blog?via=TOKEN

Best practices for affiliates

1. Link to relevant pages - Don’t always link to the homepage
2. Use descriptive anchors - “Start free trial” vs “Click here”
3. Test links first - Confirm tracking works
4. Keep URLs clean - Avoid unnecessary parameters

Link shorteners

Use a shortener

Affiliate links can be shortened:

Original: https://yoursite.com/pricing?via=john
Shortened: https://bit.ly/xyz123

Important: The shortener must pass query parameters through. Test it before you share it widely.

Recommended shorteners

Any shortener works if it redirects to the full URL with the via parameter intact. Test each one before you share it.

Shortener warnings

Some shorteners strip query parameters. Test each shortened link to confirm the via parameter reaches your site.

QR codes

Create QR codes

Generate QR codes for offline promotion:

Encode: https://yoursite.com?via=john

When someone scans the code, they land on your site with tracking active.

QR code use cases

• Business cards
• Print materials
• Product packaging
• Event displays
• Physical stores

Deep linking

Affiliates can make deep links themselves from Links in the affiliate portal: they pick a page on your site, and the portal adds their token. See Affiliate Portal Dashboard and Payout Settings. You can also build them by hand as shown below.

Product pages

Link straight to a product:

https://yoursite.com/products/widget?via=john

Checkout pages

Link to checkout with a product selected:

https://yoursite.com/checkout?product=pro&via=john

Campaign landing pages

Create dedicated pages for campaigns:

https://yoursite.com/special-offer?via=john

Parameter conflicts

With existing parameters

If your site already uses a query parameter for internal purposes:

# Conflict: your site already uses via for something else
?via=newsletter

# Better: rename your internal parameter
?source=newsletter&via=john

Solve conflicts

1. Keep via for affiliate attribution.
2. Keep your internal parameters under distinct names (for example internal_ref).
3. If needed, add custom token keys via data-affiliatebase-params.

Don’t pass the public ?via token to Stripe as client_reference_id. AffiliateBase turns that token into a generated referral ID in the browser, and Stripe should receive that generated referral ID.

Test parameters

Verify tracking works

1. Open your site with a real affiliate link (?via=YOUR_TOKEN)
2. Open the browser console
3. Check window.AffiliateBase.referral
4. It should contain the generated referral ID

Test different scenarios

• Homepage with parameter
• Deep page with parameter
• Parameter with other query strings
• Single-page apps: the script reads parameters once, when it loads. The affiliate link must land on a full page load with via in the URL. Parameters added later by client-side navigation are not read.

Troubleshooting

Parameter not tracked

1. Check the parameter spelling.
2. Check that the affiliate token is valid, and that the affiliate is pending or active with an unarchived link in an unarchived campaign.
3. Confirm the tracking script loads and its data-account-id matches the account that owns the affiliate.
4. Look for console errors.

Parameter stripped

Some systems strip unknown parameters:

• CDNs/caching layers
• Redirect services
• CMS configurations

Fix: Check each layer and make sure via survives end to end.

Next steps

• Learn about attribution windows
• Understand how attribution works
• Read the tracking and attribution reference