> 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/checkout-guides/guides/custom-commission-rates.md). # Custom Commission Rates {% hint style="warning" %} **Beta Feature:** Custom commission rates on order creation is currently in beta. Functionality and API surface may change. {% endhint %} ## Overview When you create an order with the Create Order endpoint (`POST /v1/orders`), you can optionally set the commission rate that applies to that specific order — either as a single rate for an entire bag, or individually per line item. By default, every order uses the standard commission rate configured for your relationship with the merchant. Custom rates let you adjust that on a per-order basis without changing your merchant configuration. Common use cases include: * Applying a negotiated rate to a one-off promotional order * Charging different commission on different product lines in the same bag — for example, a higher rate on high-margin luxury items and a lower rate on low-margin commodity items * Running a zero-commission order for testing or partner arrangements {% hint style="info" %} Custom commission rates apply **only to orders created through the Create Order endpoint** (Direct Order Submission). Orders created through the multi-step cart and checkout flow always use your standard configured rate. {% endhint %} ## Rate Format Commission rates are expressed as **percentages**: `15.0` means 15%. Valid values are `0` through `100`, inclusive. A rate of `0` is valid and means no commission is collected for that item. ## How Rates Are Resolved You can provide a `commission_rate` at two levels of the order request, and each line item resolves its rate independently using the most specific value available: 1. **Line-item rate** — a `commission_rate` set directly on a SKU always wins. 2. **Bag rate** — if the SKU has no rate of its own, it uses the bag's `commission_rate`. 3. **Standard rate** — if neither is provided, the SKU uses the standard commission rate configured for your merchant connection. Omitting the field and passing `null` behave identically: the item simply falls through to the next level. Only an explicit numeric value sets a custom rate. Because each line item resolves independently, you can freely mix the levels — set a blanket bag rate and override just one SKU, set rates on every SKU with no bag rate, or provide nothing at all and keep today's behavior. Each bag in a multi-bag order also resolves independently; a custom rate on one bag never affects another. ## The Effective Bag Rate Commission for payout purposes is calculated at the bag level. When the line items in a bag have different rates, the bag's effective rate is the **weighted average** of the line-item rates, weighted by each line's total (price x quantity). **Example:** a bag contains item A at $1,000.00 with a 25% rate and item B at $3,000.00 with a 10% rate. The effective bag rate is: ``` (25.0 x 100000 + 10.0 x 300000) / 400000 = 13.75% ``` This effective rate is what appears on the bag, drives your earnings calculation, and is used for any future refunds on that bag. {% hint style="info" %} **Note on discounts:** the weighted average assumes discounts are distributed proportionally across the bag. If you apply a SKU-targeted discount to an item whose rate differs from the rest of the bag, the effective commission can diverge from an exact per-item calculation by a small amount (typically cents). {% endhint %} ## Reading Rates Back Order responses include the resolved rate and its origin on every bag and line item, so you can always confirm what was applied: * Each **line item** has `commission_rate` and a `commission_rate_source` of: * `SKU` — you set the rate directly on this line item * `BAG` — the rate was inherited from the bag-level rate you provided * `SYSTEM` — the standard rate for your merchant connection was used * Each **bag** has `commission_rate` (the effective rate described above) and a `commission_rate_source` of: * `BAG` — you provided a uniform bag-level rate and no line items overrode it * `WEIGHTED` — at least one line item had its own rate, so the bag rate is the weighted average * `SYSTEM` — no custom rates were provided anywhere in the bag `commission_rate_source` is always determined by Violet based on how the rate was resolved. It is a read-only audit field — any value you include for it in a request is ignored. If you provide a custom rate that happens to equal your standard rate, it is still recorded as `SKU` or `BAG`, so your records accurately reflect that you set the rate explicitly. ## Request Examples ### Uniform Rate for a Whole Bag Every item in the bag uses 15%. This example omits `payment_method`, which is valid when you are bypassing Violet payment orchestration: ```json { "order": { "app_order_id": "order-1042", "customer": { "first_name": "Ultra", "last_name": "Violet", "email": "customer@example.com" }, "bags": [ { "commission_rate": 15.0, "skus": [ { "sku_id": 12335, "price": 100000, "quantity": 1 }, { "sku_id": 12336, "price": 50000, "quantity": 2 } ], "tax_total": 10000, "shipping_method": { "carrier": "OTHER", "label": "Standard", "price": 1000 } } ], "shipping_address": { "address_1": "2815 Elliott Ave", "city": "Seattle", "state": "WA", "country": "US", "postal_code": "98121" }, "currency": "USD" } } ``` ### Per-Item Rates Each line item carries its own rate; the bag's effective rate becomes the weighted average: ```json { "order": { "app_order_id": "order-1043", "customer": { "first_name": "Ultra", "last_name": "Violet", "email": "customer@example.com" }, "bags": [ { "skus": [ { "sku_id": 12335, "price": 100000, "quantity": 1, "commission_rate": 25.0 }, { "sku_id": 12336, "price": 300000, "quantity": 1, "commission_rate": 10.0 } ], "tax_total": 10000, "shipping_method": { "carrier": "OTHER", "label": "Standard", "price": 1000 } } ], "shipping_address": { "address_1": "2815 Elliott Ave", "city": "Seattle", "state": "WA", "country": "US", "postal_code": "98121" }, "currency": "USD" } } ``` ### Mixed: Bag Rate with One Item Overridden The first item uses its own 30% rate; the second inherits the bag's 15%: ```json { "order": { "app_order_id": "order-1044", "customer": { "first_name": "Ultra", "last_name": "Violet", "email": "customer@example.com" }, "bags": [ { "commission_rate": 15.0, "skus": [ { "sku_id": 12335, "price": 100000, "quantity": 1, "commission_rate": 30.0 }, { "sku_id": 12336, "price": 100000, "quantity": 1 } ], "tax_total": 10000, "shipping_method": { "carrier": "OTHER", "label": "Standard", "price": 1000 } } ], "shipping_address": { "address_1": "2815 Elliott Ave", "city": "Seattle", "state": "WA", "country": "US", "postal_code": "98121" }, "currency": "USD" } } ``` ### Response Excerpt ```json { "bags": [ { "commission_rate": 22.5, "commission_rate_source": "WEIGHTED", "skus": [ { "sku_id": 12335, "commission_rate": 30.0, "commission_rate_source": "SKU" }, { "sku_id": 12336, "commission_rate": 15.0, "commission_rate_source": "BAG" } ] } ] } ``` ## Validation Every rate in the request must be between 0 and 100 inclusive. If any rate is out of range, the request is rejected with a `400` error identifying the exact field, for example: ``` bag[0].skus[1].commission_rate must be between 0 and 100 ``` No part of the order is created when validation fails. ## Lifecycle Behavior * **Rates are immutable.** The resolved rates are fixed when the order is created and cannot be changed afterward. To use a different rate, create a new order. * **Earnings use the effective rate automatically.** Your payout for the order is calculated from the bag's effective rate — no additional configuration or follow-up call is required. * **Refunds use the same rate.** When a bag is refunded (in full or in part), the refund is calculated with the same effective bag rate that was set at order creation. Partial refunds of a specific item use the bag's effective rate rather than that item's individual rate. * **Existing integrations are unaffected.** If you don't send any `commission_rate` fields, orders behave exactly as they do today, using your standard configured rate. Orders created before this feature report their rates as standard (`SYSTEM`). ## Notes and Limitations * **Submitting totals net of commission:** if your app is configured to submit order totals with commission already deducted, the rate you provide must match the deduction you applied when calculating your totals. Violet cannot detect a mismatch between the two, and an inconsistent rate will produce incorrect gross amounts. * **A 100% rate is valid** — the merchant receives no payout for the bag. * **Rate precision:** rates are accepted with decimal precision (e.g. `12.5`); they are not rounded to whole percentages. * Custom rates do not change your standard merchant configuration. They apply only to the individual order they were submitted with. --- # 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: ``` GET https://docs.violet.io/prism/checkout-guides/guides/custom-commission-rates.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.