> 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/help/troubleshooting.md).

# Troubleshooting

Quick answers to the most common "why did/didn't this happen?" questions. For anything money-related, the **sale's detail page** is your best diagnostic — it shows the full attribution decision trace and the eligibility reason code.

## A sale wasn't attributed to any affiliate

Open the sale and read the decision trace. Common causes:

* **No evidence** — the order had no coupon, no tracked link/cookie, and no connected customer/product.
* **Cookie expired** — the click was older than the program's cookie window (default 30 days).
* **Coupon not recognized** — the code used wasn't a synced affiliate code.

See [How attribution works](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/how-attribution-works/README.md).

## A commission is stuck in "Pending"

* The program has an **approval delay (hold period)** — it auto-approves after the set days. See [Hold period & keeping a commission](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/hold-period-and-keep-commission/README.md).
* The order was **flagged for manual review** by an eligibility/fraud rule — read the reason code and approve or reject. 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).

## A commission was reversed or reduced

The order was refunded, canceled, returned, or disputed. Reversals are prorated and audited — see [How refunds, returns & chargebacks affect commissions](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/refunds-returns-chargebacks/README.md). If it was already paid, check [Clawback](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/clawback/README.md).

## A payout batch won't pay

* **Max-payout guard** — paying would exceed a program's cap. Remove those commissions or raise the cap.
* **Payout account not ready** — the affiliate's payout account is Incomplete/Blocked. See [Thresholds & automatic payouts](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/payouts/thresholds-and-auto-payout/README.md).
* **Provider failure** — check the payout item's failure reason (e.g. unconfirmed PayPal email), fix, and retry.

## Per-product commission rates aren't applying

Confirm that the rule matches the purchased product, variant, or SKU. The runtime applies the most specific match in this order: variant, SKU, product, then collection. Collection matching exists in the engine, but it does not execute through currently supported merchant inputs: standard Shopify `orders/paid` webhooks omit collection membership, and the public Event API does not accept or preserve collection IDs. The line item therefore uses another matching rule or the program default. Verify the resulting commission on a test order. See [Commission types](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/programs/commission-types/README.md).

## An affiliate can't log in

* Confirm they're using the email you have on file.
* Have them use **magic link** or **Forgot password**; links expire, so request a fresh one.
* See [Logging in to your portal](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/portal/logging-in/README.md).

## The API returns 403 on a write

Professional and Enterprise API keys can use documented write methods. Check that the key is active, has the required scope, belongs to the current shop, and is sent as a Bearer token. A `403` can also mean the requested operation is outside the key's authorization. See [The public REST API](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/public-api/README.md).

## Related

* [How attribution works](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/how-attribution-works/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)
* [Payout methods & batches](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/payouts/payout-methods-and-batches/README.md)