> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/payments/payouts/commission-recovery.md).

# Retained Commission Recovery

How Violet recovers commission a channel keeps under the RETAIN return policy: when a recovery case opens, which payouts it draws on and in what order, its statuses, and what you see in Stripe and in

Under the [`RETAIN` return policy](https://docs.violet.io/prism/payments/payouts/return-commission-policy.md), you keep your commission when a sale is refunded, and the retailer repays the shopper's full refund. The usual reversal of the sale's transfer returns everything the retailer was paid for the refunded goods, but it cannot return your commission, because that was never part of the transfer. The commission you keep is therefore still owed by the retailer after the refund.

Violet recovers it automatically. For each refund that leaves an amount owed, Violet opens a **recovery case** and draws the amount back from the retailer's payouts through your app, using Stripe transfer reversals. You follow each case through [webhooks](https://docs.violet.io/prism/webhooks/events/recovery-case-webhooks.md) and the [Recovery Cases API](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md).

{% hint style="info" %}
Nothing here applies to a retailer on `REVERSE`. Under `REVERSE`, the commission is reversed with the refund and nothing is owed afterwards.
{% endhint %}

## When a Case Opens

A case opens for a refund when all of these hold:

* the sale was made under `RETAIN`;
* the refund leaves an amount owed: commission on refunded goods, or a [shortfall](#shortfall) on the sale's own reversal;
* the order was paid through Stripe. For a retailer you pay yourself (custom or external transfers), the case opens already exhausted.

A case can open before the shopper's refund is confirmed, but Violet sends no event and takes nothing from the retailer until it is. Violet reads each refund 15 minutes after the refund is recorded and checks for new refunds every 5 minutes, so **a case normally exists about 20 minutes after the refund**. The `RECOVERY_CASE_OPENED` webhook follows within about a minute.

There is one case for each retailer's bag in a refund. Two partial refunds of the same bag open two cases.

No case opens when:

* the sale was made under `REVERSE`, or was split before Violet started recording the policy on sales (rolled out by 14 October 2026);
* the order was paid through a payment provider other than Stripe;
* the refund contains no goods (a shipping-only or tax-only refund) and there is no shortfall;
* your app's commission is deducted before payment, so there is no commission to retain;
* payment capture was bypassed, or the retailer's transfers are disabled.

## How Much a Case Recovers

A case tracks three amounts, in the minor units of your platform currency:

| Amount              | Meaning                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `gap_amount`        | The commission you kept on this refund.                                                                                                    |
| `shortfall_amount`  | Any part of the sale's own reversal that came up short. Usually 0.                                                                         |
| `amount_to_recover` | The full amount the retailer owes back for this refund: what the sale's own reversal returned, plus `gap_amount`, plus `shortfall_amount`. |

`amount_recovered` is what has come back so far, including the sale's own reversal, and `remaining_gap` is `amount_to_recover − amount_recovered`. A case is recovered when `remaining_gap` reaches zero. Treat a value at or below zero as nothing owed.

### Shortfall

A sale's own transfer can be drawn on by an earlier recovery case, for a different refund. If that happens and the sale is later refunded, the reversal for the refund can come up short, because part of the transfer has already been taken. Violet adds the missing part to the case as `shortfall_amount`, so the retailer still repays it and an earlier recovery never costs the shopper's refund. `shortfall_unknown` is `true` when Violet could not measure it.

### Currency

A case is recorded in your platform currency: the currency of the Stripe account the order was paid through. If your app has Stripe accounts in more than one currency, each case uses the currency of the account its order went through. If the bag was sold in another currency, the commission is converted once, when the case opens, at the exchange rate fixed for the bag. The `_usd` amounts on a case use rates fixed at the same moment, and are `null` when a rate is not available. A case whose conversion fails opens exhausted with `CURRENCY_UNKNOWN`, recorded in the bag's currency.

## Where the Money Comes From

Violet recovers each case in this order, stopping as soon as nothing is owed:

**1. The sale's own transfer.** The refund's reversal of the sale's own transfer comes first. It appears on the case as allocation `seq` 0, with `funding_type` `OWN_TRANSACTION`. If that transfer still has room after the reversal, for example because the refund was partial, Violet draws the commission from it next. If the transfer has not been sent yet, the case waits for it.

**2. The retailer's other transfers through your app, from the last 120 days.** Violet borrows from the retailer's other sales, **oldest sale first**. A transfer can be drawn on when it:

* paid the same retailer, for sales through your app;
* went to the same Stripe connected account, through the same payment connection as the sale;
* is in the same currency as the case;
* has been sent, and still has room that has not been reversed;
* paid for a sale made within the 120 days before the case opened.

A retailer's sales through any other channel are never used.

**3. Older transfers, newest first.** Violet looks beyond the 120 days only when the window holds nothing it can draw on at all, and the case has taken nothing from it. It then works backward from the transfers just past the window. Draws made this way are marked `"window": "BEYOND_WINDOW"`.

If the 120-day window covers part of the amount but not all of it, Violet takes what the window holds and the case becomes `EXHAUSTED` for the rest. It does not continue past the window in that case.

Each draw is also limited by the retailer's available balance in its Stripe account, in the case's currency. When the balance is empty, the case waits for it rather than being marked exhausted.

### How long recovery takes

Most cases recover in the same pass that opens them, about 20 minutes after the refund. A case takes longer when:

* **the retailer's available balance is empty.** A Stripe transfer reversal takes money back from the retailer's connected account, so Violet draws only when that account has an available balance in the case's currency. A retailer paid out daily can sit at zero for much of the day. The case keeps trying every few minutes and draws as soon as a new transfer lands. Nothing is lost while it waits.
* **the sale's own transfer has not been sent yet.** The case waits for it.
* **no eligible transfer has room.** The case becomes `EXHAUSTED` with `NO_DONOR_HEADROOM` and is checked again daily.

Each draw is one Stripe transfer reversal. The case records the order and bag every amount came from (`donor_order_id`, `donor_bag_id`), so each recovered amount maps to a specific sale. If the transfer a draw reverses paid for several sales, the case lists one allocation per sale, all with the same `seq`.

## Case Statuses

| Status       | Meaning                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| `OPENED`     | The case exists. Nothing beyond the sale's own reversal has been recovered yet. |
| `RECOVERING` | At least one draw has been made and something is still owed.                    |
| `RECOVERED`  | Nothing is owed. Final.                                                         |
| `EXHAUSTED`  | Violet cannot recover the rest right now. See below.                            |

```
OPENED ──► RECOVERING ──► RECOVERED
   │            │
   └────────────┴──► EXHAUSTED ──► RECOVERING   (only for NO_DONOR_HEADROOM, when room appears)
```

A case can sit in `OPENED` while it waits for the shopper's refund to be confirmed, for the sale's own transfer to be sent, or for room in the retailer's Stripe balance. Waits are not reported on the case.

### Exhausted cases

An exhausted case has `escalation` set to `RUNGS_1_2_EXHAUSTED` and an `exhausted_reason`:

| `exhausted_reason`              | Meaning                                                                                                                | Can it recover later?                                                                                                                                                                 |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NO_DONOR_HEADROOM`             | No eligible transfer has room now.                                                                                     | Yes. Violet checks every exhausted case daily at 09:00 UTC. If one of the retailer's transfers has gained room, the case returns to `RECOVERING` by itself and the next draw follows. |
| `TRANSFER_METHOD_NOT_AUTOMATIC` | The retailer is on custom or external transfers, so Violet has no transfers to recover from. The case opens exhausted. | No. Settle the amount with the retailer directly.                                                                                                                                     |
| `CURRENCY_UNKNOWN`              | A currency conversion the case needs could not be made, or the sale's transfer is in another currency.                 | No, without help from Violet.                                                                                                                                                         |
| `SHORTFALL_UNKNOWN`             | The sale's own reversal could not be measured.                                                                         | No, without help from Violet.                                                                                                                                                         |

A return from `EXHAUSTED` to `RECOVERING` sends no webhook of its own. The next event for the case follows the next draw, and the [Recovery Cases API](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md) shows `RECOVERING` as soon as the case returns.

Violet follows up with the retailer on exhausted cases. There is no automatic write-off.

## What You See

### In webhooks

Each case sends `RECOVERY_CASE_OPENED`, then an event after each draw: `RECOVERY_CASE_GAP_REMAINING` while something is still owed, or `RECOVERY_CASE_RECOVERED` when nothing is. `RECOVERY_CASE_EXHAUSTED` is sent when Violet cannot go further, with or without a new draw. Each draw also moves the transfer it was taken from to `PARTIALLY_REVERSED` or `REVERSED`, which sends the usual `TRANSFER_PARTIALLY_REVERSED` or `TRANSFER_REVERSED` event for that transfer. A draw Stripe refuses sends `TRANSFER_REVERSAL_FAILED` for that transfer instead. See [Recovery Case Webhooks](https://docs.violet.io/prism/webhooks/events/recovery-case-webhooks.md).

### In Stripe

Draws are Stripe transfer reversals on your platform account, against the retailer's transfers. Each one carries this metadata:

| Metadata key              | Value                              |
| ------------------------- | ---------------------------------- |
| `violet_recovery_case_id` | The recovery case ID.              |
| `violet_recovery_seq`     | The draw's `seq` on the case.      |
| `violet_recovery_key`     | A key unique to the case and draw. |

Use the case ID to join Violet's records to yours. Each allocation also carries its `stripe_transfer_reversal_id` (`trr_…`) and `stripe_transfer_id` (`tr_…`).

### In distributions

A draw does not add a row to [Distributions](https://docs.violet.io/prism/payments/payouts/distributions.md) today. The refund's own rows show the commission you kept (`commission_retained_amount`), and the draw itself shows as a reversal of the retailer's transfer it was taken from. To see what was recovered, from which sale and for which refund, use the [Recovery Cases API](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md) or the [webhooks](https://docs.violet.io/prism/webhooks/events/recovery-case-webhooks.md).

We plan to add a distribution row for each draw, against the retailer, so that distributions account for every movement on a transfer. This page will describe it when it is available.

### On transfers and reversals

Every draw also appears as a [Transfer Reversal](https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals.md) on the transfer it was taken from, and the case lists their IDs in `transfer_reversal_ids`, the sale's own reversal first.

## Example

A $100.00 sale at 15% commission, with $10.00 shipping and $8.00 tax remitted by the retailer, is refunded in full under `RETAIN`. The retailer's transfer for the sale was $103.00.

| Time            | What happens                                                                                                                                                        | Case                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 0:00            | The shopper is refunded $118.00. The sale's $103.00 transfer is reversed in full. `ORDER_REFUNDED` and `TRANSFER_REVERSED` are sent.                                |                                                             |
| about 0:20      | Violet opens the case. You kept $15.00 of commission, and the sale's own transfer has no room left.                                                                 | `OPENED`: to recover 11800, recovered 10300, remaining 1500 |
| same pass       | Violet draws $15.00 from the retailer's transfer for a sale in August, the oldest in the window with room. `TRANSFER_PARTIALLY_REVERSED` is sent for that transfer. |                                                             |
| within a minute | `RECOVERY_CASE_RECOVERED` is sent.                                                                                                                                  | `RECOVERED`: recovered 11800, remaining 0                   |

The case's allocations are `seq` 0 (the $103.00 reversal of the sale's own transfer, `OWN_TRANSACTION`) and `seq` 1 ($15.00, `BORROWED_REVERSAL`, `IN_WINDOW`). Allocations with `status` `EXECUTED` always add up to `amount_recovered`.

## Before You Move a Retailer to `RETAIN`

1. Subscribe to the four `RECOVERY_CASE_*` webhooks. See [Managing Webhooks](https://docs.violet.io/prism/webhooks/managing-webhooks.md).
2. Make sure your handler deduplicates on `event_key`, not on `X-Violet-Event-Id`.
3. Confirm the retailer is paid by Violet's automatic transfers and is paid through Stripe.
4. Set the retailer's [return policy](https://docs.violet.io/prism/payments/payouts/return-commission-policy.md), then read it back.

## Common Questions

**Does a case do anything before the shopper is refunded?** No. A case can exist before the refund is confirmed, but nothing is drawn from the retailer and no event is sent until it is.

**Does one draw ever touch more than one Stripe object?** No. Each draw is exactly one Stripe transfer reversal, though it can be listed as several allocations when the transfer paid for several sales. A case makes as many draws as it needs.

**How are draws for one case tied together?** Every draw carries the case ID and its `seq` in its Stripe metadata, and appears as an allocation on the case.

**Why did a case stop short of the full amount when older payouts had room?** Older payouts are used only when the 120-day window holds nothing at all. See [Where the Money Comes From](#where-the-money-comes-from).

**Where do I find a recovery in my distributions?** Not as its own row yet. See [In distributions](#in-distributions).

**Why is a case still `OPENED` an hour after the refund?** Usually because the retailer has no available balance in its Stripe account. See [How long recovery takes](#how-long-recovery-takes).

**Can I pause or redirect a case?** Not today. Cases run automatically.

## Related

* [Recovery Cases API](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md)
* [Recovery Case Webhooks](https://docs.violet.io/prism/webhooks/events/recovery-case-webhooks.md)
* [Return Commission Policy](https://docs.violet.io/prism/payments/payouts/return-commission-policy.md)
* [Transfer Reversals](https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/prism/payments/payouts/commission-recovery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
