> 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/net-receipts.md).

# Net Receipts

**Net Receipts** is a distribution model in which a Channel supplies the payment transaction fee it is charged for an order, and Violet uses that fee to adjust the split between the Merchant and the Channel. It is used by Channels whose contracts with their retailers are struck on net receipts terms: commission is taken on goods value after the transaction fee, and the retailer, not the Channel, bears that fee.

Under the standard model, commission is applied to the full subtotal and the Channel absorbs payment processing fees (see [Commission Rates](/prism/payments/payouts/commission-rates.md) and [Fee Structure](/prism/payments/payments-during-checkout/fee-structure.md)). Net Receipts changes that along two independent axes:

* **Commission basis** — commission can be computed on `subtotal − fee` instead of the full subtotal.
* **Fee remitter** — the transaction fee can be recovered from the Merchant's payout and moved to the Channel, rather than absorbed by the Channel.

{% hint style="info" %}
These two settings are independent. A retailer can be configured for either, both, or neither. The combination is resolved **per bag**, so a Channel can run Net Receipts retailers and standard retailers side by side, including within the same multi-merchant order.
{% endhint %}

## How the Calculation Changes

For a bag configured as Net Receipts, with an accepted transaction fee present:

```
commission_base = subtotal − discount − (deduct_before_commission ? fee : 0)
commission      = commission_base × commission_rate
fee_withholding = (fee_remitter == MERCHANT) ? fee : 0

merchant_share  = bag_total − commission − app_remitted_tax − app_remitted_duty − fee_withholding
channel_share   = commission − payment_provider_fee + app_remitted_tax + app_remitted_duty + fee_withholding
```

Tax and duty terms depend on the tax/duty remitter configuration, exactly as in the standard model. Payment provider (Stripe) fees are still handled per the algorithm's normal rules. The only Net Receipts additions are the `fee` subtraction in the commission base and the `fee_withholding` movement from the merchant leg to the channel leg.

### Example

<details>

<summary>Net Receipts order — commission on net basis, fee recovered from merchant</summary>

**Settings:** deduct before commission = true, fee remitter = MERCHANT

**Order Summary:**

* Goods subtotal: $100.00
* Discount: $0.00
* Transaction fee (supplied by Channel): $3.90
* Commission Rate: 15%

**Step-by-Step:**

1. Commission base = $100.00 − $3.90 = $96.10
2. Commission = $96.10 × 15% = $14.42
3. Merchant payout = $100.00 − $14.42 − $3.90 = $81.68
4. Channel receives = $14.42 + $3.90 = $18.32 *(before payment provider fees)*

The legs sum to the bag total exactly. Compared with the standard model, the Channel recovers its $3.90 fee from the merchant payout, and commission is taken on the reduced $96.10 base rather than the full $100.00.

</details>

## Sending Transaction Fees

Channels submit the fee for a single bag. The value you send is **authoritative** — Violet stores it as-is and does not recompute it.

```
PUT /v1/bags/{bag_id}/transaction_fee
```

**Authentication** (request headers): `X-Violet-Token`, `X-Violet-App-Secret`, `X-Violet-App-Id`. The submitting app must own the bag, or the request is rejected with `insufficient_permissions` (403). The fee's source app is taken from the authenticated `X-Violet-App-Id` — you do not supply it in the body.

**Request body:**

| Field                               | Type    | Required    | Description                                                                     |
| ----------------------------------- | ------- | ----------- | ------------------------------------------------------------------------------- |
| `transaction_fee_total_amount`      | integer | Yes         | Total fee in minor units (e.g. cents). Authoritative. Must be ≥ 0.              |
| `transaction_fee_percentage_amount` | integer | Yes         | Percentage component, minor units. Send `0` if not applicable.                  |
| `transaction_fee_fixed_amount`      | integer | Yes         | Fixed component, minor units. Send `0` if not applicable.                       |
| `currency`                          | string  | Yes         | ISO 4217. Must match the bag's **base currency** (compared case-insensitively). |
| `source_type`                       | string  | Yes         | Must be `APP_PROVIDED`.                                                         |
| `source_provider`                   | string  | No          | Free-form source identifier.                                                    |
| `source_reference_id`               | string  | No          | Your reference ID, for reconciliation.                                          |
| `idempotency_key`                   | string  | Recommended | Safe-retry key.                                                                 |

{% hint style="success" %}
**Safe to send for every retailer.** You can submit fees for all retailers and all bags. Violet only *consumes* a fee when the retailer is configured for Net Receipts. For any retailer that is not, the submission is stored as a rejected record (HTTP 200, `outcome = config_conflict_rejected`, `error_code = CONFIG_DISALLOWS_APP_PROVIDED_FEE`) and has no effect on the standard commission calculation. There is no risk in sending across your full catalog.
{% endhint %}

Submission outcomes: `accepted`, `duplicate_accepted` (identical resubmit under the same idempotency key), and `config_conflict_rejected` (retailer not configured for Net Receipts). Validation failures (bag not found, wrong owner, missing/negative amounts, currency mismatch, wrong source type) return the standard 4xx error envelope.

{% hint style="warning" %}
**Submit the fee before distributions are generated.** Violet consumes the fee at the moment it generates the bag's distributions; it looks for an `ACCEPTED` fee at that point. If the fee arrives after distributions are generated, it will not be applied to that bag. Send the fee as early in the order lifecycle as you can.
{% endhint %}

## Configuring a Retailer for Net Receipts

Net Receipts is enabled by Violet per **(retailer, channel)** pairing as part of contract setup. There is no self-serve toggle. When Violet enables Net Receipts for a retailer, it configures:

* **Fee submission** — whether the channel is allowed to submit transaction fees for the retailer at all.
* **Fee consumption** — whether Violet actually consumes the submitted fee for the retailer. When this is off, submitted fees are ignored and the standard commission calculation applies unchanged.
* **Commission basis** — whether commission is computed on `subtotal − fee` (net of fee) or on the full subtotal.
* **Fee remitter** — whether the fee is recovered from the merchant payout to the channel, or absorbed by the channel.

Retailers that are not configured for Net Receipts are unaffected and behave exactly as they do today.

To enable Net Receipts for one or more retailers, [contact Violet support](/help/support-request.md) with the list of retailers and the terms you want applied.

## Refunds

Refunds on Net Receipts bags are handled automatically:

* Commission is clawed back by prorating the **original commission** on the refunded goods ratio. Because the original commission was already taken on the net-of-fee base, this is inherently correct; there is no separate fee adjustment.
* The **transaction fee is not returned** on a refund. It stays retained with the Channel, so the retailer continues to bear it. This matches net receipts contract terms.
* Fee provenance is preserved on the reversal records for audit.

## Hold Conditions

To protect against bad splits, a Net Receipts bag is **held for review** (no funds move) rather than processed when:

* The fee would drive the commission base or any distribution leg negative (for example, a fee larger than the goods subtotal).
* More than one accepted fee exists for the same bag (a data conflict).

A zero fee is a valid no-op. When a bag is held because the fee would produce an invalid result, the fee's provenance is retained so it can be inspected before release. When a bag is held for a duplicate-fee conflict, there is no single fee to apply, so no fee is stamped onto the distribution — but the hold record still captures the order, bag, and reason for review.

## Related

* [Commission Rates](/prism/payments/payouts/commission-rates.md)
* [Fee Structure](/prism/payments/payments-during-checkout/fee-structure.md)
* [Distributions](/prism/payments/payouts/distributions.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.violet.io/prism/payments/payouts/net-receipts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.