Ambassly Attribution Rules

Ambassly uses last-click attribution from referral codes passed into Stripe, then turns paid invoices into held commissions with audit events. Refunds, duplicate customers, self-referrals, and fast conversions are handled as explicit ledger rules instead of hidden adjustments.

This document defines how Ambassly attributes customers and commissions. It is written as the operational trust document for merchants and affiliates.

Attribution source

Ambassly attributes Stripe customers from referral codes.

A referral code is the membership code carried in an affiliate URL as ?via=CODE. Ambassly also accepts ?ref=CODE.

Ambassly short links redirect through:

https://ambassly.com/r/[slug]

The short link records a click asynchronously, then redirects to the destination URL with ?via=code appended.

Last-click rule

Ambassly uses last-click attribution.

When a visitor lands with ?via=CODE or ?ref=CODE, the Ambassly script stores that referral in the first-party ambassly_ref cookie and mirrors it in localStorage.

If the same visitor later lands with a different Ambassly referral code before checkout, the newer code replaces the older code. The commissionable referral is the last stored Ambassly code passed into Stripe Checkout.

Attribution window

The default attribution window is 60 days.

The Ambassly cookie is stored for 60 days with SameSite=Lax. Programs have cookie_days with a default of 60.

Safari's Intelligent Tracking Prevention can cap client-set cookies to about 7 days in common referral flows. For long buying cycles, merchants should capture the referral server-side when the visitor arrives and pass it into Stripe from their server at checkout.

Stripe handoff

At checkout, merchants pass the referral code into Stripe as:

client_reference_id

and/or:

metadata.ambassly

On checkout.session.completed, Ambassly resolves the code from those fields, creates the referral row, and links it to the Stripe customer.

If neither field contains an Ambassly referral code, Ambassly does not attribute that Checkout Session.

Duplicate-customer guard

Ambassly allows one referral per Stripe customer.

If a Stripe customer already maps to a referral, later events for that same Stripe customer use the existing referral mapping. Ambassly does not create competing referrals for the same stripe_customer_id.

Commission creation

On invoice.paid, Ambassly checks whether the Stripe customer maps to a referral.

If the customer maps to a referral and the invoice is within the program's commission window — the first paid invoice for a one-time program, or an invoice within the recurring_months window (every invoice when the program is lifetime) for a recurring program — Ambassly creates a commission with:

status = pending
hold_until = now + hold_days

The program's hold_days value controls the hold period. The default hold period is 30 days.

Hold periods and approval

Commissions start as pending.

Pending commissions remain held until hold_until. After the hold period, commissions can move to approved.

If company auto-approve is on, Ambassly's reconciliation process moves commissions past hold_until to approved.

Approved commissions can be included in payout exports and marked paid.

Clawbacks

Ambassly listens for:

charge.refunded
customer.subscription.deleted

When one of those events matches a pending or approved commission, Ambassly marks the commission clawed_back and writes an audit event.

If the matching commission has already been paid, Ambassly creates a negative adjustment commission instead of changing the paid payout record.

Self-referral policy

Self-referrals are rejected.

If the referral email or customer email is the same as the affiliate email, Ambassly auto-rejects the commission and writes an audit event.

The rule is intentionally strict: affiliates cannot earn commission on their own purchases.

Fast-conversion flag

Ambassly flags conversions that happen less than 60 seconds after the click.

This is a fraud signal, not an automatic rejection rule by itself.

Audit trail

Commission changes are written to an append-only audit trail.

Ambassly records commission events in:

commission_events

Webhook deliveries are recorded in:

webhook_events

This gives merchants and affiliates a ledger for attribution, commission status changes, clawbacks, and payout decisions.