> 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/referrals-sales-and-reversals/refunds-returns-chargebacks.md).

# Refunds, returns, and chargebacks

## What it does

When an order is refunded, canceled, returned, or loses a dispute, Wand Referrals appends an immutable financial event and updates the current commission balance. Every adjustment is deterministic, prorated, tenant-scoped, idempotent, and auditable. An opened dispute never reduces a commission by itself.

## The commission statuses

A commission moves through these statuses (`OrderCommissionStatus`):

The canonical path is `PENDING` → `APPROVED` → `PAYABLE` → `PAID`. Historical compatibility statuses remain readable. `PROTECTED` is a modifier, not a terminal status, so a protected commission can still be paid.

## Refunds & returns — full vs partial

Refunds are prorated against the **original** order subtotal and the **original** commission, and are **cumulative and non-compounding** (a second partial refund is measured against the original, not the already-reduced amount):

* **Full refund** (or cumulative refunds ≥ the original subtotal) → the commission is **reversed** to zero (`REVERSED`).
* **Partial refund** → the commission is **reduced** proportionally: `remaining ratio = (original subtotal − cumulative refunded) ÷ original subtotal`, and the new commission = `round(original commission × remaining ratio)`.

Refund handling is **idempotent** — the same refund id is processed once (a duplicate is skipped), and a commission already reversed/canceled/refunded is left alone.

## Cancellations

A canceled order appends the corresponding adjustment, subject to explicit protection and the program's legacy compatibility policy (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)).

## Chargebacks & disputes

* **Opened or pending:** creates or updates a manual-review chain; no financial reduction.
* **Won by the merchant:** resolves the review without a negative adjustment.
* **Lost by the merchant:** appends the deterministic adjustment or post-payment clawback.
* **Represented or reopened:** appends a replay-safe event linked to the prior dispute event.

If the commission is Protected, a lost dispute stays in manual review rather than reducing money automatically. Shopify dispute delivery is not production-validated until the required Shopify scope is separately approved and registered.

## Derived commissions reverse in lockstep

MLM upline rows and split rows tied to the source order are reversed **together** with the original, and that reversal is idempotent.

## What happens if the commission was already paid

The original **paid** award is never rewritten. Instead, the shortfall is appended as **clawback owed** so it can be recovered from future commissions when enabled, waived, or manually reconciled. See [Clawback](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/clawback/README.md).

## Audit & history

Every award, lifecycle transition, adjustment, review, protection decision, and clawback writes an immutable ledger entry with a stable event key. Current amount/status fields are query projections; the source award and event history remain unchanged. You can review the timeline on the **sale's detail page**.

## Related

* [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)
* [Clawback — reclaim or waive paid commissions](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/clawback/README.md)
* [How attribution works](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/how-attribution-works/README.md)