> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supercycle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Revenue share formulas

> Define consignor revenue shares as Liquid formulas, including tiered rates and per-item deductions.

Consignor **revenue shares** can be a simple percentage of the sale or a [Liquid](https://shopify.github.io/liquid/) **formula** that returns the consignor's amount in **cents**. Both modes run through the same engine — a percentage compiles to a canonical formula — so what you preview is what gets frozen on each sale.

Set a **shop default** under **Settings** > **Consignment**, then override it per consignor when needed. Consignors set to **Inherit shop default** use whatever the shop default is at earning time.

<Note>
  **Item-level revenue share overrides are removed.** To treat one item differently, reference its custom fields in the formula (for example `item.fields.payout_rate`) instead of setting a separate rate on the item.
</Note>

***

## Set the shop default

<Steps>
  <Step title="Open consignment settings">
    In Shopify admin, go to **Supercycle** > **Settings** > [**Consignment**](https://admin.shopify.com/apps/supercycle/settings/consignment).
  </Step>

  <Step title="Choose a mode">
    Under **Default revenue share**, pick **Percentage of sale** or **Formula**. This applies to every consignor that inherits the shop default.
  </Step>

  <Step title="Enter the rate or formula">
    For a percentage, enter **Revenue share percentage** (0–100%). For a formula, select **Add formula** to open the editor.
  </Step>

  <Step title="Save">
    Select **Save**. Changes apply to future earnings only — past ledger entries keep their frozen amounts.
  </Step>
</Steps>

***

## Set a consignor's revenue share

On a consignor's page, the **Revenue share** selector has three options:

| Mode                     | What it does                                                                  |
| ------------------------ | ----------------------------------------------------------------------------- |
| **Inherit shop default** | Uses the shop default from consignment settings (default for new consignors). |
| **Percentage of sale**   | A fixed percentage of the charge subtotal for this consignor's items.         |
| **Formula**              | A Liquid expression returning the consignor's share in cents.                 |

When the consignor uses a formula (or inherits a shop default that is a formula), the consignors list and related displays show **Formula** instead of a percentage. When a percentage can be derived — including inherit → shop percent — the display shows that percentage.

***

## Write a formula

Select **Add formula** or **Edit formula** to open the formula editor. The sidebar shows a read-only preview; edits apply when you select **Done** and save the consignor or settings form.

### Rules

* The formula must render a **non-negative integer in cents**. For example, `$60.00` on a sale is written as `6000`.
* Formulas run in **strict mode** — referencing an undefined variable fails validation on save, or surfaces an error in **Try it out**.
* **Money values are in cents** throughout the formula context.

### Variable chips

The editor lists clickable variable chips you can insert into the formula. Available context:

| Prefix               | What it includes                                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `charge.subtotal`    | The charge revenue the share is calculated on, in cents (same value frozen as **Basis** on payout lines).                          |
| `cycle.*`            | Built-in cycle system values (schedule dates, charges totals, deposit, and similar).                                               |
| `item.*`             | Built-in item system values (completed cycles, acquisition cost, lifecycle revenue, ROI, utilization, variant price, and similar). |
| `item.fields.*`      | Custom and calculated fields on the item, by key.                                                                                  |
| `cycle.fields.*`     | Custom and calculated fields on the cycle, by key.                                                                                 |
| `consignor.fields.*` | Custom and calculated fields on the consignor, by key.                                                                             |

The same system fields available in [calculated fields](/documentation/configuration/custom-data/calculated-fields) are exposed here under `item.*` and `cycle.*`.

### Examples

**60% of the sale** (equivalent to percentage mode):

```liquid theme={null}
{{ charge.subtotal | times: 60.0 | divided_by: 100.0 | round }}
```

**60% minus a repair fee** stored as a money custom field on the item:

```liquid theme={null}
{% assign share = charge.subtotal | times: 60.0 | divided_by: 100.0 | round %}
{% assign fee = item.fields.repair_fee | default: 0 %}
{{ share | minus: fee }}
```

**Tiered rate** by sale amount:

```liquid theme={null}
{% if charge.subtotal >= 10000 %}
  {{ charge.subtotal | times: 70.0 | divided_by: 100.0 | round }}
{% else %}
  {{ charge.subtotal | times: 50.0 | divided_by: 100.0 | round }}
{% endif %}
```

***

## Try it out

Before saving, use **Try it out** in the formula editor:

1. Pick any **Item** in your shop (formulas can reference that item's fields regardless of who consigns it).
2. Enter a **Sale amount**.
3. Select **Calculate**.

Supercycle renders the draft through the real engine and shows what the consignor would receive. If the result exceeds the sale amount, you get a warning. Liquid errors appear verbatim — previews do not fall back to the shop default, so you see exactly why a formula is broken.

***

## What happens on a sale

<Steps>
  <Step title="Resolve the formula">
    Supercycle resolves the consignor's mode: consignor percent or formula, or the shop default when the consignor inherits. Percentages compile to the same cents formula path.
  </Step>

  <Step title="Render and freeze">
    When the charge is **paid**, the formula renders against that charge, cycle, item, and consignor. The resulting **amount**, **basis**, **formula text**, and **source** (`consignor`, `shop`, or `fallback`) are frozen on the ledger entry.
  </Step>

  <Step title="Fallback on failure">
    If a formula fails at earning time, Supercycle falls back to the shop default formula (or zero if that also fails), writes the entry with `source: fallback`, and logs the error. Money events never drop. Correct mistakes with an **adjustment** entry; the payout breakdown shows a **Fallback** badge on affected lines.
  </Step>

  <Step title="Refunds reverse proportionally">
    Refunds reverse `earning amount × refund basis ÷ earning basis` — the formula is never re-rendered. For percentage-based entries this matches the old rate-based reversal.
  </Step>
</Steps>

Changing a consignor's revenue share or the shop default only affects **future** earnings. Past entries stay frozen with the formula and amount recorded at the time.

***

## Per-item exceptions without overrides

Because item-level revenue share overrides are gone, express different terms through data the formula reads:

* Add a **money** or **integer** [custom field](/documentation/configuration/custom-data/custom-fields) on items (for example `payout_rate` or `repair_fee`).
* Reference it in the shop default or consignor formula with `item.fields.payout_rate`.
* Set the field per item in **Inventory** — no separate commission field on the item.

For read-only derived values, use a [calculated field](/documentation/configuration/custom-data/calculated-fields) on items or cycles and reference it the same way.