> ## 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

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

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

Set a shop default under <Icon icon="shopify" iconType="solid" /> **[Consignment](https://admin.shopify.com/apps/supercycle/settings/consignment)**, then override it per consignor where you need to. Consignors set to **Inherit shop default** use whatever the default is at the moment they earn.

***

## Revenue share modes

The **Revenue share** selector on a consignor's page has three modes.

| Mode                     | What it does                                                                      |
| ------------------------ | --------------------------------------------------------------------------------- |
| **Inherit shop default** | Uses the shop default from consignment settings. This is what new consignors get. |
| **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.                     |

A consignor on a formula, or inheriting a shop default that is a formula, shows as **Formula** in the consignors table. Where a percentage can be derived, including inheriting a shop percentage, the table shows that percentage.

***

## Set the shop default

<Steps>
  <Step title="Open consignment settings">
    Go to <Icon icon="shopify" iconType="solid" /> **[Consignment](https://admin.shopify.com/apps/supercycle/settings/consignment)**.
  </Step>

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

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

  <Step title="Save">
    Select **Save**. The change applies to future earnings, and past entries keep their frozen amounts.
  </Step>
</Steps>

***

## Write a formula

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

### Rules

* The formula must render a non-negative integer in cents. A \$60.00 share is written as `6000`.
* Formulas run in strict mode. Referencing an undefined variable fails validation on save, or returns an error in **Try it out**.
* Money values are in cents throughout the formula context.

### Variables

The editor lists clickable chips you can insert into the formula.

| Prefix               | What it includes                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `charge.subtotal`    | The charge revenue the share is calculated on, in cents. This is the value frozen as **Basis** on payout lines.          |
| `cycle.*`            | Built-in cycle values, such as the schedule dates, charge totals, and deposit.                                           |
| `item.*`             | Built-in item values, such as completed cycles, acquisition cost, lifetime revenue, ROI, utilization, and variant price. |
| `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 system fields available in [calculated fields](/documentation/configuration/custom-data/calculated-fields) are exposed here under `item.*` and `cycle.*`.

### Examples

A 60% share, which is the same as percentage mode:

```liquid 60% of the sale theme={null}
{{ charge.subtotal | times: 60.0 | divided_by: 100.0 | round }}
```

A 60% share minus a repair fee held in a money custom field on the item:

```liquid 60% minus a repair fee 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 }}
```

A rate that changes with the size of the sale:

```liquid Tiered rate 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 %}
```

***

## Test the formula before publishing

Check a formula before you save it.

<Steps>
  <Step title="Pick an item">
    In the formula editor, select **Try it out** and pick any **Item** in your shop. A formula can read that item's fields whoever consigns it.
  </Step>

  <Step title="Enter a sale amount">
    Enter a **Sale amount** to render the formula against.
  </Step>

  <Step title="Calculate">
    Select **Calculate**. Supercycle renders the draft through the real engine and shows what the consignor would receive.
  </Step>
</Steps>

A result larger than the sale amount comes back with a warning. Liquid errors appear as they are, and a preview never falls 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: their percentage or formula, or the shop default when they inherit. Percentages compile to the same cents formula.
  </Step>

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

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

  <Step title="Reverse refunds proportionally">
    A refund reverses the earning amount multiplied by the refund basis and divided by the earning basis. The formula is never rendered again, which matches the old rate-based reversal for percentage entries.
  </Step>
</Steps>

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

***

## Per-item exceptions

An item has no revenue share of its own, so different terms for one item are expressed through data the formula reads.

* Add a money or integer [custom field](/documentation/configuration/custom-data/custom-fields) to items, such as `payout_rate` or `repair_fee`.
* Reference it in the shop default or in the consignor's formula as `item.fields.payout_rate`.
* Set the value per item in <Icon icon="shopify" iconType="solid" /> **[Inventory](https://admin.shopify.com/apps/supercycle/items)**.

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