> 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/return-commission-policy.md).

# Return Commission Policy

Choose whether a retailer's commission is reversed or retained when a sale is refunded, set it per retailer through the API, and see exactly how each refund is calculated.

When a shopper is refunded, the channel's commission on that sale can go one of two ways. It can be handed back to the retailer along with the refund, or the channel can keep it. The **return commission policy** decides which, for each retailer connected to your app.

| Policy    | What happens to commission on a refund                                                                  | Typical contract                                            |
| --------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `REVERSE` | The commission on the refunded goods is reversed. The retailer bears the refund net of your commission. | Sale-and-return (SAR)                                       |
| `RETAIN`  | You keep the commission. The retailer repays the full refund, including the commission you keep.        | Sale-based retention (SBR), including SBR with Net Receipts |

`REVERSE` is the platform default, and it is how every refund worked before this setting existed. You do not need to do anything for a retailer that should stay on `REVERSE`.

{% hint style="info" %}
The policy never changes what the shopper gets back. The refund amount is the same under both policies. The policy only decides how the cost of that refund is split between you and the retailer.
{% endhint %}

## Where the Policy Is Set

The policy is resolved per retailer and app, in this order:

1. **Retailer override.** A value set for one retailer on your app, through the API below. Source `MERCHANT`.
2. **App default.** A value set for your whole app. Violet sets this on request; [contact Violet support](https://docs.violet.io/help/support-request.md) if you want every retailer to default to `RETAIN`. Source `APP`.
3. **Platform default.** `REVERSE`. Source `DEFAULT`.

The source tells you which level supplied the policy, and every read of the setting returns it.

{% hint style="warning" %}
A retailer whose payment configuration is set not to follow your app's settings ignores the app default. Without its own override, it falls back to the platform default, `REVERSE`. The `effective` block in the response always shows the policy that applies and where it came from, so read it back after any change.
{% endhint %}

## Reading and Changing a Retailer's Policy

Both calls use your usual channel credentials: `X-Violet-Token`, `X-Violet-App-Secret` and `X-Violet-App-Id`. The token must belong to the developer account that owns the app in the path, and the retailer must be enabled on that app. Retailers cannot read or change this setting themselves.

### Read the policy

```
GET /v1/merchants/{merchant_id}/app_relationships/{app_id}/return_commission_policy
```

```json
{
  "merchant_id": 10000,
  "app_id": 10001,
  "overrides": {
    "return_commission_policy": "RETAIN"
  },
  "effective": {
    "return_commission_policy": {
      "value": "RETAIN",
      "source": "MERCHANT"
    }
  }
}
```

`overrides.return_commission_policy` is the retailer's own value, or `null` when it has none. `effective` is what Violet applies to the retailer's next sale.

### Change the policy

```
PATCH /v1/merchants/{merchant_id}/app_relationships/{app_id}/return_commission_policy
Content-Type: application/json
```

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X PATCH "https://sandbox-api.violet.io/v1/merchants/10000/app_relationships/10001/return_commission_policy" \
  -H "X-Violet-Token: $VIOLET_TOKEN" \
  -H "X-Violet-App-Secret: $VIOLET_APP_SECRET" \
  -H "X-Violet-App-Id: 10001" \
  -H "Content-Type: application/json" \
  -d '{"return_commission_policy": "RETAIN"}'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const res = await fetch(
  "https://sandbox-api.violet.io/v1/merchants/10000/app_relationships/10001/return_commission_policy",
  {
    method: "PATCH",
    headers: {
      "X-Violet-Token": process.env.VIOLET_TOKEN,
      "X-Violet-App-Secret": process.env.VIOLET_APP_SECRET,
      "X-Violet-App-Id": "10001",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ return_commission_policy: "RETAIN" }),
  }
);
const policy = await res.json();
console.log(policy.effective.return_commission_policy); // { value: "RETAIN", source: "MERCHANT" }
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

res = requests.patch(
    "https://sandbox-api.violet.io/v1/merchants/10000/app_relationships/10001/return_commission_policy",
    headers={
        "X-Violet-Token": os.environ["VIOLET_TOKEN"],
        "X-Violet-App-Secret": os.environ["VIOLET_APP_SECRET"],
        "X-Violet-App-Id": "10001",
    },
    json={"return_commission_policy": "RETAIN"},
)
res.raise_for_status()
print(res.json()["effective"]["return_commission_policy"])
```

{% endtab %}
{% endtabs %}

The body takes one field, `return_commission_policy`:

| Value sent                | Result                                                              |
| ------------------------- | ------------------------------------------------------------------- |
| `"REVERSE"` or `"RETAIN"` | Sets the retailer's override. Values are case-sensitive.            |
| `null`                    | Clears the override, so the retailer follows the app default again. |
| Field left out, or `{}`   | Nothing changes.                                                    |

The response is the same shape as the `GET`. Every change is recorded with who made it and the old and new values.

| Status | Error                      | When                                                                                                                             |
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `bad_request`              | The value is not `REVERSE`, `RETAIN` or `null`, the body has an unknown field, or the JSON is malformed.                         |
| 400    | `empty_body`               | No body was sent.                                                                                                                |
| 403    | `insufficient_permissions` | The token's developer does not own the app, the retailer is not connected to or enabled on the app, or the caller is a retailer. |
| 409    | `bad_request`              | Another change to the same setting was made at the same moment. Read the setting and try again.                                  |
| 415    |                            | The body was not sent as `application/json`.                                                                                     |

Nothing is changed when a request fails.

See the API reference: [Get Return Commission Policy](https://docs.violet.io/api-reference/merchants/app-relationships/get-return-commission-policy.md) and [Update Return Commission Policy](https://docs.violet.io/api-reference/merchants/app-relationships/update-return-commission-policy.md).

## Each Sale Keeps the Policy It Was Sold Under

Violet records the effective policy on a sale when it splits the bag into distributions, a few seconds after the order is accepted. From then on, every refund of that sale uses the recorded policy, however long the return takes to arrive. Changing a retailer's policy only affects sales made after the change.

* **Allow up to an hour.** Settings are cached, so a change can take up to an hour to reach new sales. If the timing matters, for example when a new contract starts on a given date, make the change the day before.
* **Older sales.** Sales split before Violet started recording the policy on sales (rolled out by 14 October 2026) have none, and are treated as `REVERSE`.
* **A changed contract is not retroactive.** A retailer moving from SAR to SBR keeps `REVERSE` on every sale made before you set `RETAIN`.

## How a Refund Is Calculated

Both policies start from the same figure: the commission on the goods being refunded.

```
goods_refunded      = refund_amount − shipping − tax − duty
commission_on_goods = goods_refunded × commission_rate          (on the sale's commission base)
```

Shipping, tax and duty are never part of the commission, on the sale or on the refund. The commission base, including how tax-inclusive prices are handled, is described in [Commission Base: Tax, Duty and Discounts](https://docs.violet.io/prism/payments/payouts/commission-base.md). A refund uses the same base the sale used.

Each refund's figure is capped at the commission the sale charged. Under `RETAIN` it is also capped at what earlier refunds of the bag have left, so several partial refunds can never keep more commission than the sale earned.

Then the policies part ways:

|                                                     | `REVERSE`                                                     | `RETAIN`                                                     |
| --------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| Commission returned by the channel                  | `commission_on_goods`                                         | 0                                                            |
| Commission kept by the channel                      | 0                                                             | `commission_on_goods`                                        |
| Reversed from the retailer's transfer for this sale | `refund − commission_on_goods` (less any tax your app remits) | the same amount                                              |
| Still owed by the retailer after that reversal      | nothing                                                       | `commission_on_goods`, recovered from the retailer's payouts |

Under `RETAIN` the retailer repays the shopper's full refund. Most of it comes back through the usual reversal of the sale's own transfer; the commission you keep is recovered on top of that, from the retailer's payouts, by Violet's recovery process. See [Retained Commission Recovery](https://docs.violet.io/prism/payments/payouts/commission-recovery.md).

{% hint style="info" %}
**A full refund reverses the whole transfer.** When a refund covers the order's full total, Violet reverses everything that remains on the retailer's transfer for the sale, under either policy.
{% endhint %}

### Refunds Entered as an Amount

A retailer can refund in its store either by selecting items or by entering an amount. Some platforms, Shopify among them, send no line items for a refund entered as an amount, so Violet reads the amount itself, **goods first**:

1. The amount is goods, up to the goods the bag still has to refund (the subtotal less discounts, less goods earlier refunds returned).
2. Anything above that is shipping, tax and duty, in proportion to what remains of each.
3. Anything above everything left to refund on the bag is recorded as `refund_discrepancy`, as a negative figure. On almost every refund there is none, and the field is `null`.

Shipping, tax or duty that the platform does report on the refund is taken as reported, and only the rest of the amount is read this way.

So a partial refund entered as an amount returns commission under `REVERSE` in the same way as a refund of items, and a full refund entered as an amount gives the same result as a full refund of items or a cancellation. Goods first means that when a retailer refunds an item's price as an amount, all of it counts as goods, which is how retailers usually use it.

{% hint style="info" %}
Refunds recorded before this rule (October 2026) keep their original figures. Some of them recorded the whole amount as `refund_discrepancy` and returned no commission.
{% endhint %}

### Examples

All examples use a 15% commission rate, a retailer that remits its own tax, and one bag paid by one transfer.

<details>

<summary>Full refund</summary>

**Sale:** goods $100.00, shipping $10.00, tax $8.00. The shopper pays $118.00. Commission is $15.00, and the retailer's transfer is $103.00.

**Refund:** the shopper is refunded $118.00.

|                                               | `REVERSE` | `RETAIN`    |
| --------------------------------------------- | --------- | ----------- |
| Goods refunded                                | $100.00   | $100.00     |
| Commission on those goods                     | $15.00    | $15.00      |
| Reversed from the retailer's $103.00 transfer | $103.00   | $103.00     |
| Commission returned by the channel            | $15.00    | $0.00       |
| Recovered from the retailer's other payouts   |           | $15.00      |
| **Retailer's net on the order**               | **$0.00** | **−$15.00** |
| **Channel's commission kept**                 | **$0.00** | **$15.00**  |

</details>

<details>

<summary>Partial refund of one item</summary>

**Sale:** as above. The shopper returns one $40.00 item and is refunded $40.00 plus $3.20 tax, $43.20 in all. Shipping is not refunded.

|                                       | `REVERSE`  | `RETAIN`                                                |
| ------------------------------------- | ---------- | ------------------------------------------------------- |
| Goods refunded                        | $40.00     | $40.00                                                  |
| Commission on those goods             | $6.00      | $6.00                                                   |
| Reversed from the retailer's transfer | $37.20     | $37.20                                                  |
| Commission returned by the channel    | $6.00      | $0.00                                                   |
| Recovered from the retailer           |            | $6.00, normally from the room left on the same transfer |
| **Retailer keeps from the order**     | **$65.80** | **$59.80**                                              |
| **Channel's commission kept**         | **$9.00**  | **$15.00**                                              |

</details>

<details>

<summary>Shipping-only or tax-only refund</summary>

A refund that contains no goods carries no commission. Nothing is reversed or retained, and under `RETAIN` no recovery is needed.

</details>

## Transaction Fees on Refunds

If your app supplies a transaction fee for the bag (see [Net Receipts](https://docs.violet.io/prism/payments/payouts/net-receipts.md)), that fee is **never returned on a refund**, under either policy. Only commission depends on the policy. Who economically absorbs the fee is part of your contract with the retailer and is set by the retailer's fee settings, not by its return policy.

The same holds for a cancellation and for a full refund: neither returns the transaction fee.

**The payment provider's processing fee** (for example Stripe's) is not returned either. The provider keeps it when a payment is refunded, so whoever paid it on the sale has still paid it. Refund distributions record `0` for it, and no reversal is reduced by it.

## Reading the Result on Distributions

Each refund writes a `REFUND` distribution for the retailer and one for your app. On those rows:

* `net_distribution_amount` is the amount the refund takes back from that account, as a negative figure. It is the figure that moves.
* `commission_reversed_amount` is the commission the refund reversed. It is `0` under `RETAIN`.
* `commission_retained_amount` is the commission you kept under `RETAIN`, with the same sign convention as `commission_reversed_amount` (negative on the channel's row, positive on the retailer's). It is `null` under `REVERSE`.
* `commission` on a refund row is the whole bag's commission, repeated on every refund of the bag. Do not add it up across refunds.

To total the commission you kept on a bag, add `commission_retained_amount` across its refund rows. Every field's sign on refund rows, with a worked example under each policy, is in [Reading Refund Rows](https://docs.violet.io/prism/payments/payouts/distributions/distributions-apis.md#reading-refund-rows).

## Things to Know Before Using `RETAIN`

* **Subscribe to the recovery webhooks first.** Every `RETAIN` refund that leaves an amount owed opens a recovery case. Subscribe to the four [Recovery Case Webhooks](https://docs.violet.io/prism/webhooks/events/recovery-case-webhooks.md) before you move the first retailer.
* **Stripe only.** `RETAIN` works for orders paid through Stripe. A refund of a `RETAIN` sale paid through Nuvei is refused. For other payment providers, Violet cannot recover the commission you keep.
* **Commission deducted before payment.** If your app's commission is taken before the retailer is paid (the bag's payment distributions show `totals_include_commission` as `false`), a refund reverses no commission and none is retained, under either policy.
* **Retailers you pay yourself.** Recovery works through the transfers Violet sends. For a retailer on custom or external transfers, Violet cannot recover retained commission automatically. Its cases are marked exhausted straight away, and you settle the amount with the retailer directly.

## Common Questions

**Does the policy apply to cancellations as well as returns?** Yes. The policy applies to every refund of a sale, whatever the reason, including a cancellation before the order ships.

**Why does an older partial refund show no commission reversed?** If the retailer entered the refund as an amount and it was recorded before the [goods-first rule](#refunds-entered-as-an-amount), the whole amount was recorded as `refund_discrepancy` and no commission was reversed. Contact Violet support about any refund you need corrected.

**Is a refund entered as an amount treated differently from a refund of items?** No longer. Both return commission the same way; see [Refunds Entered as an Amount](#refunds-entered-as-an-amount).

**Can I switch a retailer from `RETAIN` back to `REVERSE`?** Yes, at any time. Sales already made keep `RETAIN`; new sales use `REVERSE`.

**Does Violet work out the contract type?** No. Violet applies the settings you set. Set each retailer's return policy and [fee settings](https://docs.violet.io/prism/payments/payouts/net-receipts.md#setting-a-retailers-fee-settings) to match its contract.

**Why does the retailer's reversal not include the commission I kept?** A reversal can only take back money the transfer sent, and the transfer never included your commission. The commission is recovered separately, from the retailer's other payouts.

## Related

* [Retained Commission Recovery](https://docs.violet.io/prism/payments/payouts/commission-recovery.md)
* [Commission Base: Tax, Duty and Discounts](https://docs.violet.io/prism/payments/payouts/commission-base.md)
* [Commission Rates](https://docs.violet.io/prism/payments/payouts/commission-rates.md)
* [Net Receipts](https://docs.violet.io/prism/payments/payouts/net-receipts.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/return-commission-policy.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.
