Custom Commission Rates

Beta Feature: Custom commission rates on order creation is currently in beta. Functionality and API surface may change.

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

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.

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.

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).

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:

{
  "order": {
    "app_order_id": "order-1042",
    "customer": {
      "first_name": "Ultra",
      "last_name": "Violet",
      "email": "[e-mail]"
    },
    "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:

{
  "order": {
    "app_order_id": "order-1043",
    "customer": {
      "first_name": "Ultra",
      "last_name": "Violet",
      "email": "[e-mail]"
    },
    "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%:

{
  "order": {
    "app_order_id": "order-1044",
    "customer": {
      "first_name": "Ultra",
      "last_name": "Violet",
      "email": "[e-mail]"
    },
    "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

{
  "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.