Affiliate Tracking for Stripe Checkout and Payment Links

This guide is for merchants who sell through Stripe Payment Links, Buy Buttons, Pricing Tables, or Checkout Sessions created by their own server. It explains how to pass the generated AffiliateBase referral ID to Stripe so a sale is attributed to the affiliate.

Attribution depends on Stripe receiving the generated referral ID through client_reference_id or the affiliatebase_referral_id metadata key. Keep merchant-owned client_reference_id values intact; metadata can carry the AffiliateBase referral alongside them. The public ?via token is only the affiliate link token; do not copy it into Stripe.

After AffiliateBase receives the setup-test click, you can choose Do this later in Setup step 5 (Verify tracking) and continue before any checkout happens. That saves your setup but does not claim that checkout attribution works. Step 5 shows Tracking is verified only after Stripe returns the generated referral ID on a completed Checkout Session.

Connect Stripe separately in AffiliateBase before running the checkout verification. For automatic Stripe links and components, install this one script tag on the same published page as the checkout:

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

The automatic path does not require a command-queue preloader. Use that preloader only when advanced code calls affiliatebase(...) before the remote script has loaded.

Choose a setup path

Payment Links

Keep the Stripe Payment Link on the same published page as the AffiliateBase script:

<a href="https://buy.stripe.com/your_payment_link">Buy now</a>

<!-- Optional explicit marker for custom Stripe Payment Link URLs -->
<a data-affiliatebase href="https://link.payment/your_payment_link">Buy now</a>

AffiliateBase appends client_reference_id after a referred visitor lands on your site. Leave standard buy.stripe.com and link.payment links unchanged. If your checkout uses another Stripe-hosted or redirected Payment Link URL, mark that anchor with data-affiliatebase so AffiliateBase owns client_reference_id for that link.

Buy Buttons and Pricing Tables

The tracking script sets the referral on Stripe Buy Buttons and Pricing Tables automatically. Keep the Stripe-hosted element on the same published page as the AffiliateBase script:

<stripe-buy-button buy-button-id="buy_btn_xxx" publishable-key="pk_live_xxx"></stripe-buy-button>

<stripe-pricing-table
  pricing-table-id="prctbl_xxx"
  publishable-key="pk_live_xxx"
></stripe-pricing-table>

Memberstack on Webflow

For Webflow sites that use Memberstack, AffiliateBase automatically integrates with Memberstack’s DOM checkout. You can keep your existing Memberstack checkout buttons; no second AffiliateBase snippet or custom checkout handler is required.

1. Install the AffiliateBase tracking script on the pages where visitors arrive and start checkout.
2. Connect the same Stripe account that Memberstack uses for your payments.
3. Open your AffiliateBase setup-test link and follow the tracking verification checklist through checkout.

Before Memberstack starts checkout, the AffiliateBase tracker adds the generated referral UUID as metadataForCheckout.affiliatebase_referral_id. The adapter preserves other checkout options and metadata. It waits briefly for the current attribution attempt, then lets checkout continue without AffiliateBase referral metadata if attribution is unavailable, blocked, failed, or takes too long.

A captured visit or a referral ID in the browser does not confirm payment attribution. Complete the verification checklist through checkout and check the result in AffiliateBase.

For custom calls to the Memberstack DOM SDK, continue using purchasePlansWithCheckout; AffiliateBase’s adapter is enabled by default. See the tracking script reference for its readiness wait, metadata preservation, and configuration options.

Custom or backend-created Checkout Sessions

If your server creates Checkout Sessions, the browser must submit the referral ID to your server first:

<form action="/checkout" method="post" data-affiliatebase data-affiliatebase-param-name="referral_id">
  <button type="submit">Start checkout</button>
</form>

Then set client_reference_id and mirrored metadata on the server:

referral_id = params[:referral_id].presence
referral_metadata = { affiliatebase_referral_id: referral_id }.compact

checkout_params = {
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  line_items: [{ price: "price_xxx", quantity: 1 }],
  mode: "subscription"
}
checkout_params[:client_reference_id] = referral_id if referral_id.present?
checkout_params[:metadata] = referral_metadata if referral_metadata.present?
if checkout_params[:mode] == "payment"
  checkout_params[:payment_intent_data] = { metadata: referral_metadata } if referral_metadata.present?
elsif checkout_params[:mode] == "subscription"
  checkout_params[:subscription_data] = { metadata: referral_metadata } if referral_metadata.present?
end

session = Stripe::Checkout::Session.create(checkout_params)

Do not read window.AffiliateBase inside server-side Stripe code. Read the referral ID in the browser, submit it with the checkout request, then use that generated referral ID server-side.

For a one-time payment Session, mirror affiliatebase_referral_id into payment_intent_data.metadata. For a recurring subscription Session, mirror it into subscription_data.metadata. Keep the nested field matched to the Session mode; Stripe does not accept payment-only or subscription-only fields in the other mode.

Why client_reference_id is used

Stripe sends client_reference_id back on Checkout Sessions and webhooks. AffiliateBase uses it to connect the Stripe sale to the referral created when the affiliate link was opened. Mirrored affiliatebase_referral_id metadata gives AffiliateBase an additional recovery path for sparse payment and recurring invoice events.

Local testing and test mode

Local browser checks are useful for confirming window.AffiliateBase.referral exists, but the final Stripe checkout test should run from a deployed page. If you test locally, use /track.js, set data-debug="true", and confirm the checkout link or form includes the referral value before testing the deployed page.

Setup shows whether the connected Stripe account is in test or live mode. Use a test payment in test mode. In live mode, do not create a charge only to clear onboarding; a free trial counts, or choose Do this later and verify during the next appropriate live checkout.

If the tracker fails to load, is blocked, or times out, let checkout continue without attribution. Attach a referral only after the current tracking attempt has settled successfully.

Related guides

• Tracking Script Reference
• Install Tracking Script
• Verify Tracking