Referral data breaks when the click, checkout, customer, and invoice live in separate systems. Stripe referral tracking fixes that only when every record uses the same referral ID.
Rewardful can capture the affiliate click. Stripe can store the customer and subscription records. Your job is to connect those records, test the path, and keep a report your team can audit.
Stripe referral tracking starts with one data path
A referred visitor clicks an affiliate link. Rewardful stores the referral in a browser cookie. The visitor starts checkout. Stripe creates a Checkout Session, Customer, Subscription, and paid Invoice, depending on your billing flow.
Rewardful then matches the referred customer to the affiliate and creates commissions under your campaign rules. A click alone does not create revenue. A paid invoice tied to the right customer does.
Use the Stripe customer as the attribution anchor
The Stripe Customer is the most useful record for long-term attribution. It stays connected to subscriptions, invoices, renewals, and payment history.
Rewardful looks for a referral value in Stripe customer metadata. Store the Rewardful referral ID there when your checkout creates the customer. That gives both systems a stable reference point.
Record these IDs together in your internal data:
- Rewardful referral ID and affiliate ID
- Stripe Customer ID
- Stripe Subscription ID, if the buyer subscribes
- Stripe Invoice ID for each paid renewal
- Campaign name, commission status, and payout status
Put data on the right Stripe object
Stripe metadata is object-level. Metadata on a Checkout Session is not the same as metadata on a Customer or Subscription. Review Stripe’s metadata documentation before you build custom logic.
Use Customer metadata for referral ownership. Use Subscription metadata when your product needs subscription-level reporting. Use Checkout Session metadata for session-specific fulfillment or internal order context.
Do not rely on a single field copied through every object. Confirm where your application writes each value, then verify it after checkout.
Connect Rewardful to the correct Stripe account
Start in Rewardful and connect the Stripe account that processes your SaaS payments. Check whether your live billing account, test account, and connected accounts are separate. Many attribution problems start with the wrong account connection.
The Rewardful Stripe App listing is useful for confirming the supported Stripe connection path. Connect the account before you invite affiliates or send referral links.
Set campaign rules before traffic arrives
Create the campaign first. Define the commission rate, whether it applies to the first payment or recurring revenue, the cookie window, and the conditions for approval.
Rewardful’s default cookie period is 60 days, though campaign settings can change it. Put the actual attribution period in your affiliate terms. A partner cannot price their work if they do not know when a referral expires.
Also state how you handle:
- Trials that never convert to a paid invoice
- Refunds, chargebacks, and canceled subscriptions
- Coupon codes and manual attribution
- Existing customers who later click an affiliate link
Keep these rules fixed for each campaign period. Changing a live rule without an effective date creates payout disputes.
Install the tracking script across the buying path
Install the Rewardful tracking script on the root domain and every subdomain where a visitor can arrive before checkout. That includes your marketing site, pricing page, login flow, and hosted application pages when they participate in the purchase path.
A script on www.example.com does not help if checkout starts on app.example.com and the referral data never carries over. Test the actual visitor route, not only the page where your team installed the script.
Pass the referral ID into Stripe Checkout
Your checkout type decides how you pass the referral data. Use the Rewardful method that matches your implementation. Do not combine methods because they sound similar.
Use Payment Links when Stripe creates the customer
Stripe Payment Links can work for simple plans. For Rewardful’s Payment Links method, enable “Save payment details for future use.” This lets Stripe create or use a Customer record, which Rewardful needs for customer-based attribution.
Payment Links fit a simple public pricing page. They are less flexible when you need account provisioning, plan logic, seat counts, or a signed-in upgrade process.
Check the full checkout flow in a browser. A Payment Link that opens and accepts payment can still fail attribution if no Customer record is created.
Pass the ID in client-side Checkout
For client-side Stripe Checkout, Rewardful’s script exposes the referral ID through Rewardful.referral. Pass that value as clientReferenceId when your app calls Stripe’s client-side checkout method.
Follow Rewardful’s client-side Stripe Checkout instructions for the current script and Checkout configuration. The key point is simple: read the ID after Rewardful has loaded, then send that same ID into Checkout.
Do not hard-code an affiliate ID in your frontend. The value must come from the visitor’s actual referral session.
Store the referral on a custom Stripe customer
A server-side or custom billing flow gives you more control. When your server creates the Stripe Customer, write the referral value as customer metadata, such as metadata: { referral: referralId }.
Then create the subscription or Checkout Session for that Customer. Rewardful can inspect the Customer record and match it to the referred visitor.
Use Rewardful’s custom Stripe integration method when your app creates customers through the Stripe API. Keep the Rewardful API key and Stripe secret key on the server. Never send either key to the browser.
Test a referral link before you invite affiliates
Test the full path with a controlled referral. A dashboard configuration is not proof that a customer will be attributed correctly.
Use a new browser profile or clear site data. Open a real referral link from a test affiliate. Complete checkout with a unique test email address. Record the referral ID, Stripe Customer ID, Subscription ID, and Invoice ID as you go.
Check the click, customer, and conversion records
First, confirm that Rewardful records the referral visit. Next, open the Stripe Customer record and check for the referral metadata value if your flow uses customer metadata.
Then inspect Rewardful. The customer should appear as a conversion under the expected affiliate and campaign. If your buyer starts a subscription, confirm the Stripe Subscription belongs to the same Customer.
A successful Checkout Session proves payment flow worked. It does not prove the affiliate owns the resulting customer.
Use a test or sandbox path where your connected Stripe and Rewardful setup supports it. Do not mix live Customer IDs with sandbox Customer IDs in one commission report.
Test the events that happen after checkout
Subscriptions create events after the first screen closes. Test a successful first invoice, a renewal, a failed payment, and a cancellation when your billing setup allows it.
If your application maintains its own billing or commission records, listen to relevant Stripe events and verify webhook signatures. Stripe’s guide to subscription webhooks covers the event-driven payment lifecycle and sandbox testing.
Store the Stripe event ID in your own log. This prevents duplicate processing when Stripe retries a webhook delivery.
Track recurring commissions and payment changes
Recurring commission programs depend on paid invoices, not on the original referral click. When a referred customer renews, Rewardful can create a new commission based on the paid renewal invoice and campaign rules.
This is why the Stripe Customer link matters. A renewal may happen months after the original session has expired.
Match every commission to an invoice
Keep one row per customer, subscription, and invoice. A commission record should identify the Stripe invoice that created it.
Your finance record needs to answer three questions:
| Record | What it proves |
|---|---|
| Rewardful referral and commission | Which affiliate received credit |
| Stripe customer, subscription, and invoice | Which payment created the commission |
| Payout record | Whether the affiliate was paid |
This structure catches a common error. A team may match a commission to the correct customer but attach it to the wrong renewal invoice.
Keep refunds and reversals as adjustments
Do not overwrite the original commission when a refund arrives. Keep the original row. Add an adjustment row with the refund ID, amount, date, reviewer, and payout effect.
For example, a $100 paid invoice at a 20% commission creates a $20 commission. A full refund later needs a negative $20 adjustment, subject to your campaign rules and payout timing.
Separate pending, approved, reversed, and paid amounts. Dashboard labels can vary by account, so map them to one internal reporting standard. Created commissions are not cash paid to partners.
Build a referral report your team can trust
Use Rewardful for day-to-day conversion and affiliate views. Use Stripe for payment evidence. Keep a separate spreadsheet, database, or warehouse table as your historical record.
Rewardful also provides a documented referrals API, including GET /v1/referrals, for teams that need to pull referral records into internal reporting. Confirm current authentication, pagination, and access details in your account before putting it into a production job.
Track accepted revenue, not activity
Your report should include referral clicks, referred customers, paid invoices, approved commissions, reversals, and payouts. Do not treat clicks as revenue. Do not forecast cash from commissions that can still reverse.
Track these operating measures each month:
- Referred customers with valid Stripe Customer IDs
- Paid renewal invoices from referred subscriptions
- Approved commissions after refunds and chargebacks
- Reversals as a percentage of approved commissions
- Review time and correction time per reporting cycle
A process that creates 50 commission records but requires hours of cleanup is not efficient. Measure the records finance accepts without correction.
Protect data and fix attribution failures
Referral cookies and identifiers can fall under privacy rules in your market. Explain affiliate tracking in your privacy notice. Configure consent handling where required, and do not load tracking before the needed consent exists.
Do not store email addresses, names, payment details, or sensitive notes in Stripe metadata. Keep metadata limited to operational IDs such as a referral ID, account ID, or campaign code.
Missing attribution usually comes from one of these issues:
- The Rewardful script did not load before checkout.
- The visitor moved between domains and lost the referral context.
- The cookie expired before the purchase.
- The checkout flow failed to pass
client_reference_idor customer metadata. - The Payment Link did not create a Stripe Customer.
- The customer existed before the referral was attached.
- The invoice is unpaid, refunded, or outside campaign rules.
Collect the referral link, affiliate ID, customer email, Stripe IDs, campaign, date range, and screenshots before asking for help. If your checkout crosses several apps or Stripe accounts, Book A Call before changing live attribution rules.
Final checks before you scale
Reliable Stripe referral tracking is a record-matching process. Capture the referral at the click, attach it to the Stripe customer, confirm the paid invoice, then reconcile the commission and payout.
Run controlled tests before every major checkout change. Keep original commission records, log adjustments separately, and review approved revenue instead of clicks or automated actions.
