Affonso tracks a Stripe purchase as an affiliate referral when the customer's Checkout Session includes affonso_referral in its metadata. This guide walks through the chain from cookie to commission.
1. Live mode only
Affonso only processes Stripe live-mode webhooks. Test-mode purchases are ignored. For end-to-end testing, use live mode with a 100% off coupon.
2. The cookie is set in the browser
Open your site with an affiliate link (e.g. https://yourdomain.com/?atp=affiliate-id) and check DevTools → Application → Cookies. The cookie affonso_referral should exist on your domain.
If it's missing, the tracking script isn't loaded. See the tracking debug checklist.
3. The cookie is passed into Stripe metadata
On your server, read the cookie value when creating the Checkout Session and pass it as metadata:
stripe.checkout.sessions.create({
// ...
metadata: {
affonso_referral: cookieValue,
},
});The key must be exactly affonso_referral.
4. Verifying metadata on the Stripe side
- Open the customer in your Stripe dashboard.
- Scroll to Events and open the Checkout Session completed event.
- Confirm
metadata.affonso_referralis present and matches the cookie value.
If the metadata is missing, your server isn't reading the cookie or isn't including it in the session.
5. Webhook delivery
Your Stripe webhook endpoint must point at Affonso. Configure it in Tracking & Coupons → Connect. Webhook logs are available in your Affonso dashboard for diagnostics.
Deep links
Tracking parameters work on any path, not just the homepage. https://yourdomain.com/welcome?atp=affiliate-id and https://yourdomain.com/pricing?atp=affiliate-id both set the cookie correctly.
