> 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/webhooks/events/recovery-case-webhooks.md).

# Recovery Cases

Recovery case webhooks follow each [retained commission recovery](https://docs.violet.io/prism/payments/payouts/commission-recovery.md) case from the moment it opens until nothing is owed, or until Violet cannot recover more. They apply only to retailers on the [`RETAIN` return policy](https://docs.violet.io/prism/payments/payouts/return-commission-policy.md).

Subscribe to all four events before you move the first retailer to `RETAIN`, so you hear about every case from the first refund. Each event is a separate webhook subscription. See [Managing Webhooks](https://docs.violet.io/prism/webhooks/managing-webhooks.md).

## Available Events

### RECOVERY\_CASE\_OPENED

**Trigger:** A refund under `RETAIN` leaves an amount owed after the reversal of the sale's own transfer, and the shopper's refund is confirmed. Usually about 20 minutes after the refund.

**Carries:** the case's starting figures. `last_allocation` is the sale's own reversal (`seq` 0), and `amount_recovered` equals it. When that reversal returned nothing, `last_allocation` is left out.

### RECOVERY\_CASE\_GAP\_REMAINING

**Trigger:** A draw was made and something is still owed.

**Carries:** the draw that was just made, in `last_allocation`, and the running totals.

### RECOVERY\_CASE\_RECOVERED

**Trigger:** Nothing is owed. The case is closed.

**Carries:** the last draw, and `remaining_gap` of zero or less.

### RECOVERY\_CASE\_EXHAUSTED

**Trigger:** Violet cannot recover the rest of the amount right now. `exhausted_reason` says why. A case that cannot be recovered at all, such as one for a retailer on custom transfers, sends `RECOVERY_CASE_OPENED` and then `RECOVERY_CASE_EXHAUSTED`.

**Next:** for `NO_DONOR_HEADROOM`, Violet checks again every day and the case can start recovering again by itself. That return sends no event; the next event for the case follows the next draw. See [Exhausted cases](https://docs.violet.io/prism/payments/payouts/commission-recovery.md#exhausted-cases).

## Payload

Every recovery event has the same shape. Amounts are integers in minor units (cents) and are **running totals for the case**, not the change since the last event.

```json
{
  "event": "RECOVERY_CASE_GAP_REMAINING",
  "event_key": "recovery_case:401:RECOVERY_CASE_GAP_REMAINING:1",
  "recovery_case_id": 401,
  "refund_id": 30501,
  "order_id": 90001,
  "bag_id": 70001,
  "merchant_id": 5123,
  "payout_account_id": 9123,
  "currency": "USD",
  "gap_amount": 1500,
  "shortfall_amount": 0,
  "shortfall_unknown": false,
  "amount_to_recover": 11800,
  "amount_recovered": 11100,
  "remaining_gap": 700,
  "gap_amount_usd": 1500,
  "shortfall_amount_usd": 0,
  "amount_to_recover_usd": 11800,
  "last_allocation": {
    "seq": 1,
    "funding_type": "BORROWED_REVERSAL",
    "window": "IN_WINDOW",
    "amount": 800,
    "stripe_transfer_reversal_id": "trr_1Q9c…",
    "stripe_transfer_id": "tr_1PxD…",
    "funding_payout_transfer_id": 176002,
    "donor_order_id": 88310,
    "donor_bag_id": 69120
  },
  "case_status": "RECOVERING",
  "date": "2026-10-15T09:20:44+0000"
}
```

| Field                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event`                                                                                                         | The event name.                                                                                                                                                                                                                                                                                                                                           |
| `event_key`                                                                                                     | A key unique to this case, event and draw: `recovery_case:<case id>:<event>:<seq>`. Use it to deduplicate.                                                                                                                                                                                                                                                |
| `recovery_case_id`                                                                                              | The case. Read it with [Get a Case](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md#get-a-case).                                                                                                                                                                                                                  |
| `refund_id`, `order_id`, `bag_id`                                                                               | The refund, order and bag that opened the case.                                                                                                                                                                                                                                                                                                           |
| `merchant_id`, `payout_account_id`                                                                              | The retailer and its payout account.                                                                                                                                                                                                                                                                                                                      |
| `currency`                                                                                                      | The case currency.                                                                                                                                                                                                                                                                                                                                        |
| `gap_amount`, `shortfall_amount`, `shortfall_unknown`, `amount_to_recover`, `amount_recovered`, `remaining_gap` | The case amounts, as defined in [Case Fields](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md#case-fields).                                                                                                                                                                                                       |
| `gap_amount_usd`, `shortfall_amount_usd`, `amount_to_recover_usd`                                               | The same amounts in US cents, or `null` when a rate was unavailable.                                                                                                                                                                                                                                                                                      |
| `last_allocation`                                                                                               | The draw behind this event: `seq`, `funding_type`, `window`, `amount`, the Stripe reversal and transfer IDs, the Violet transfer drawn on, and the order and bag the money came from. If the draw reversed a transfer that paid for several sales, `amount` is the whole draw and only one of those sales is named; read the case for the full breakdown. |
| `case_status`                                                                                                   | The case's status after this event.                                                                                                                                                                                                                                                                                                                       |
| `escalation`, `exhausted_reason`                                                                                | Present only when the case is `EXHAUSTED`.                                                                                                                                                                                                                                                                                                                |
| `date`                                                                                                          | When the event was recorded, in UTC.                                                                                                                                                                                                                                                                                                                      |

{% hint style="info" %}
Fields with no value are left out of the body rather than sent as `null`. For example, `escalation` and `exhausted_reason` appear only on an exhausted case. Treat a missing field as `null`. Field order in the body is not fixed.
{% endhint %}

## Headers

Recovery events carry the [standard webhook headers](https://docs.violet.io/prism/webhooks/events.md#webhook-headers), plus one more:

| Header                        | Value                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Violet-Topic`              | The event name.                                                                                                                      |
| `X-Violet-Entity-Id`          | The recovery case ID.                                                                                                                |
| `X-Violet-Recovery-Event-Key` | The same value as `event_key` in the body.                                                                                           |
| `X-Violet-Event-Id`           | Identifies one delivery record. The same recovery event can be delivered again under a different value, so do not deduplicate on it. |
| `X-Violet-Hmac`               | The HMAC signature of the body. See [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks.md).                 |

## Handling Recovery Events

* **Deduplicate on `event_key`.** Violet may send an event more than once. `event_key` is the same each time; `X-Violet-Event-Id` may not be.
* **Do not rely on arrival order.** Violet sends a case's events in order, but they can reach you out of order. Use the running totals with the highest `last_allocation.seq`, or read the case from the API.
* **Expect transfer events too.** Each draw reverses part of one of the retailer's transfers, which sends `TRANSFER_PARTIALLY_REVERSED` or `TRANSFER_REVERSED` for that transfer. These usually arrive before the matching recovery event, but that order is not guaranteed.
* **Respond with a 2xx quickly.** Deliveries follow the usual [retry rules](https://docs.violet.io/prism/webhooks/handling-webhooks.md), with one thing to watch: a `4xx` response from your endpoint is treated as final and is not retried. Return a `5xx` if you want Violet to try again.

## Example Sequence

A full refund of a $100.00 sale at 15% commission, where the retailer's transfer for the sale was $103.00 and $15.00 is recovered from two earlier sales:

| # | Event                                                             | Highlights                                                                                               |
| - | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 1 | `ORDER_REFUNDED`                                                  | The shopper is refunded $118.00.                                                                         |
| 2 | `TRANSFER_REVERSED`                                               | The sale's own transfer, $103.00.                                                                        |
| 3 | `RECOVERY_CASE_OPENED`                                            | `amount_to_recover` 11800, `amount_recovered` 10300, `remaining_gap` 1500. `last_allocation` is `seq` 0. |
| 4 | `TRANSFER_PARTIALLY_REVERSED`, then `RECOVERY_CASE_GAP_REMAINING` | `seq` 1: $8.00 from the oldest earlier sale with room. `remaining_gap` 700.                              |
| 5 | `TRANSFER_PARTIALLY_REVERSED`, then `RECOVERY_CASE_RECOVERED`     | `seq` 2: $7.00 from the next earlier sale. `remaining_gap` 0.                                            |

## Related

* [Retained Commission Recovery](https://docs.violet.io/prism/payments/payouts/commission-recovery.md)
* [Recovery Cases API](https://docs.violet.io/prism/payments/payouts/commission-recovery/recovery-cases-api.md)
* [Transfer Webhooks](https://docs.violet.io/prism/webhooks/events/transfer-webhooks.md)
* [Order Webhooks](https://docs.violet.io/prism/webhooks/events/order-webhooks.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/webhooks/events/recovery-case-webhooks.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.
