Net Receipts
How Net Receipts works: submitting per-bag transaction fees, how they change the commission split, configuration, refunds, and hold cases.
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 and Fee Structure). Net Receipts changes that along two independent axes:
Commission basis — commission can be computed on
subtotal − feeinstead 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.
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.
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_withholdingTax 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
Net Receipts order — commission on net basis, fee recovered from merchant
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:
Commission base = $100.00 − $3.90 = $96.10
Commission = $96.10 × 15% = $14.42
Merchant payout = $100.00 − $14.42 − $3.90 = $81.68
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.
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.
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:
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.
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.
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.
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.
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 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
Last updated
Was this helpful?