Troubleshoot Affiliate Tracking and Payout Issues

Diagnose AffiliateBase script loading, missing Stripe attribution, webhook failures, payout run errors, and coupon sync problems.

Table of Contents

Start with the symptom you can observe, check each item in order, and use the linked guide when the issue needs a full test path.

Tracking Script Not Attributing

Check:

Script loads from the AffiliateBase tracking CDN, or from /track.js when testing against a local app
data-account-id is correct
?via=TOKEN appears in test URL
/api/track returns success

Conversions Missing

Check:

Stripe Payment Link, Buy Button, or Pricing Table is on the same published page as the AffiliateBase script
Backend-created Checkout Session receives referral_id from the browser, sets client_reference_id, and mirrors affiliatebase_referral_id metadata
Browser identify only records a lead; purchase attribution requires a verified Stripe payment and referral handoff
Stripe events are delivered and verified

Stripe Webhook Errors

Check:

Correct webhook secret configured
Signature header present
Events are not being skipped for missing account context

Payout Run Failures

Check:

Affiliate PayPal or Wise details are present
Export execution is complete in PayPal or Wise
Reconciliation actions for stuck payout states

Coupon Sync Issues

Check:

Campaign has stripe_coupon_id
Affiliate is active
Stripe token is valid

When To Escalate

Escalate when any of these persist after one full retry cycle:

Repeated webhook signature failures
Repeated provider outage failures
Systematic missing attribution across environments

Detailed Troubleshooting Guides