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 client_reference_id.

Which Path Should I Use?

If your checkout uses…Use this setup
Stripe Payment LinkAdd data-affiliatebase to the link.
Stripe Buy ButtonAdd data-affiliatebase to the <stripe-buy-button> element.
Stripe Pricing TableAdd data-affiliatebase to the <stripe-pricing-table> element.
Backend-created Checkout SessionSubmit referral_id to your server, then set client_reference_id in Stripe.

Add data-affiliatebase to the link:

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

AffiliateBase appends client_reference_id after a referred visitor lands on your site.

Buy Buttons and Pricing Tables

Use the same attribute on Stripe-hosted elements:

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

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

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 on the server:

referral_id = params[:referral_id].presence

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?

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 set client_reference_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.

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