Skip to main content

Stripe Checkout and Payment Links

Implement Stripe attribution using client_reference_id from AffiliateBase referral state

Table of Contents

Stripe Checkout and Payment Links

Attribution for Stripe depends on Stripe receiving the generated AffiliateBase referral ID as client_reference_id. The public ?via token is only the affiliate link token; do not copy it into Stripe.

Which Path Should I Use?

If your checkout uses…Use this setup
Stripe Payment LinkPut the tracking script on the same page as the Stripe link. Standard buy.stripe.com and link.payment URLs are detected automatically; custom Payment Link URLs can opt in with data-affiliatebase.
Stripe Buy ButtonPut the tracking script on the same page as the <stripe-buy-button> element.
Stripe Pricing TablePut the tracking script on the same page as the <stripe-pricing-table> element.
Custom or backend-created Checkout SessionSubmit referral_id to your server, then set client_reference_id and mirrored affiliatebase_referral_id metadata in Stripe.

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

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>

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?
checkout_params[:payment_intent_data] = { metadata: referral_metadata } if referral_metadata.present?
checkout_params[:subscription_data] = { metadata: referral_metadata } if referral_metadata.present?

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

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

Why client_reference_id?

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

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.

Next steps