> For the complete documentation index, see [llms.txt](https://docs.wandreferrals.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wandreferrals.com/tracking-and-attribution/how-attribution-works.md).

# How attribution works

## What it does

**Attribution** decides *which affiliate gets credit* for an order. Wand Referrals uses an **explainable** engine with a fixed priority ladder and stable tie-breakers, and it records exactly why it reached a decision. There is no randomness. Most evidence windows use order timestamps, but lifetime customer eligibility currently compares its disconnect window with processing time. The same delayed or replayed order can therefore produce a different lifetime-customer candidate set when processed later; the recorded decision trace is the authority for that run.

## The priority ladder

When an order comes in, the engine gathers every piece of attribution *evidence* and sorts affiliates into buckets. The winner is the first non-empty bucket in this fixed priority order:

1. **Coupon** — the order used an affiliate's discount/coupon code. (Highest priority.)
2. **Direct link** — a landing-site ref or click id points to an affiliate.
3. **Link cookie** — a tracking cookie from an affiliate's link, within the cookie window.
4. **Connected customer** — the buyer is linked to an affiliate (including lifetime connections).
5. **Connected product** — a purchased product is connected to an affiliate. (Lowest priority.)

If no bucket has evidence, the order is **Unattributed** and earns no commission.

Buckets are never blended — a coupon always beats a cookie, which always beats a connected product. Within a single bucket, ties are broken deterministically (program-hint match, then most-recent evidence, then a stable id comparison).

## The decision trace

Every commission stores a **decision trace** (`decisionTraceJson`) that records:

* the method order the engine considered,
* the candidates in each bucket,
* the selected winner and the reason code (e.g. `ATTRIBUTED_BY_COUPON`), and
* if unattributed, why (`UNATTRIBUTED_NO_MATCH`).

You can read this on the **sale's detail page** — it's the definitive answer to "why did this affiliate get credit?" The trace also carries the eligibility outcome (see [Geo restrictions & eligibility](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/programs/geo-and-eligibility/README.md)).

## Attribution confidence

Each evidence type carries a confidence level, roughly: coupon and direct link = high, link cookie and connected customer/product = medium, lifetime = low. Confidence is informational — the priority ladder, not confidence, decides the winner.

## The cookie / attribution window

Link-cookie attribution only counts within the program's **cookie duration** (default **30 days**). Lifetime connections use a separate disconnect window. Set the cookie duration when [creating a program](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/programs/creating-a-program/README.md).

## Server-side conversions

Headless or non-Shopify checkouts can report conversions through the API, which funnel into this **same** engine — there is no parallel money path. The API maps its hints to the same evidence buckets (coupon, ref/click, customer, line items). See the [API events endpoint](/integrations-and-api-production-rollout-gate-pending/reference.md).

## Related

* [Coupon vs link tracking](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/coupon-vs-link/README.md)
* [Connected customers & products](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/connected-customers-and-products/README.md)
* [Geo restrictions & eligibility](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/programs/geo-and-eligibility/README.md)
* [Refunds, returns & chargebacks](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/refunds-returns-chargebacks/README.md)