Calculated fields

Calculated fields are read-only custom fields whose value comes from a Liquid formula. One formula can pull from custom fields, Supercycle’s built-in system values, and Shopify metafields on the same record. For example, divide acquisition cost by completed cycles, or set a flag from a metafield. Calculated fields are available on items, cycles, and consignors, and appear with the regular custom fields in the Custom fields section on the record. Their value updates on demand with Recalculate. Definitions live under Custom data.

Create a calculated field

Open custom data settings

Go to Custom data and select Items, Cycles, or Consignors.

Add a calculated definition

Select Add definition on the Calculated fields card.

Set up the field

Enter a Name, the display name shown on the record, such as Total rental cost. The Key is generated from the name and can be edited. Set the Result type to the type the formula produces: single line text, multi line text, money, integer, boolean, date, or date and time. Enter the Formula as a Liquid expression.

Save

Select Save.

The result type can’t be changed after creation.

When consignment is on and the result type is Money or Integer, definitions on items or cycles show Include in consignor payouts. Flagged fields appear as columns on payout breakdown reports. Values recompute when you view the report, and a failing formula shows a blank cell.

Write formulas

Formulas use Liquid, the templating language Shopify themes and notifications use. A formula is any Liquid expression that renders to a value matching the field’s result type. The form lists the available variables as pills. Select one to insert it into the formula.

General rules

Formulas run in strict mode. Referencing an undefined variable makes the formula fail.
Only scalar custom fields can be referenced. Reference fields (customer, cycle, item, return), color, URL, and JSON fields aren’t available in formulas.
Built-in system fields (completed cycles, acquisition cost, schedule dates, charges, and similar) are available alongside custom fields. The formula picker lists them as pills.
A calculated field can’t reference another calculated field.
Money values are integers in cents. $15.00 is 1500, and a money-typed formula must also produce cents. Multiply and divide accordingly when combining money with other numbers.
Durations from system fields are in days, for example utilized_days and total_utilized_days.

To take 10% off a daily rate stored as money:

{{ fields.daily_rate | times: 0.9 }}

To turn an integer number of dollars into a money result, multiply by 100:

{{ fields.dollars | times: 100 }}

Liquid basics

Liquid has two kinds of markup. Output, {{ ... }}, renders a value, and everything a formula produces has to end up inside output tags. Tags, {% ... %}, control logic and render nothing themselves, for example {% if %}, {% assign %}, and {% case %}. Values are transformed with filters, chained with |:

{{ fields.daily_rate | times: fields.days | plus: fields.cleaning_fee }}

Common filters in formulas:

Arithmetic

plus, minus, times, divided_by, modulo

{{ fields.rate | times: fields.days }}

Rounding

round, ceil, floor

{{ fields.total | divided_by: 3 | round }}

Fallback

default substitutes a value when the input is empty.

{{ fields.rate | default: 0 }}

Text

upcase, downcase, capitalize, append, prepend

{{ fields.sku | prepend: "SC-" }}

Dates

date formats a date with a strftime string.

{{ fields.starts_on | date: "%Y-%m-%d" }}

See the Liquid reference for the full list.

Conditional logic

Use {% if %} to branch. The formula still has to render a value that matches the result type, so return one on every branch:

{% if item.fields.replacement_cost > 50000 %}true{% else %}false{% endif %}

For more than two branches, {% case %} is often cleaner:

{% case fields.tier %}
  {% when "gold" %}   {{ fields.base_rate | times: 0.8 }}
  {% when "silver" %} {{ fields.base_rate | times: 0.9 }}
  {% else %}          {{ fields.base_rate }}
{% endcase %}

Intermediate values

{% assign %} names intermediate values so complex formulas stay readable:

{% assign gross = fields.daily_rate | times: fields.days %}
{% assign discount = gross | times: fields.discount_percent | divided_by: 100 %}
{{ gross | minus: discount }}

Liquid variable reference

The variables available in a formula depend on the calculated field’s owner. Custom field keys are shop-defined, so they’re shown as fields.<key> and metafields.<key>.

Scalar custom field types

Every fields.<key> variable takes its Liquid type from the underlying custom field definition:

Custom field type	Liquid type	Example	Notes
`money`	integer	`1500`	Cents
`integer`	integer	`3`
`boolean`	boolean	`true` or `false`
`single_line_text_field`	string	`"hello"`
`multi_line_text_field`	string	`"hello\nworld"`
`date`	string	`"2024-01-15"`	ISO 8601 date
`date_time`	string	`"2024-01-15T12:30:00"`	ISO 8601 date and time

Liquid references by owner

Expand an owner to see every variable it exposes, with its Liquid type and where the value comes from.

Item

varies

One entry per scalar custom field defined on items, keyed by the definition’s key. The Liquid type mirrors the custom field type: money and integer are integers (money in cents), boolean is a boolean, and text, date, and date_time are strings.

integer

Number of completed cycles on the item.

integer

Number of unfulfilled (upcoming) cycles on the item.

integer

Number of currently active cycles on the item.

integer

Item acquisition cost in cents.

integer

Lifetime revenue attributed to the item, in cents.

integer

Lifetime ROI for the item in cents.

number

Share of the item’s published lifetime spent utilized, as a fraction from 0 to 1. 0 when the item has no published_at.

number

Total days the item has been utilized, rounded to two decimal places. Fleet age is measured from published_at when set.

number

Total days the item has not been utilized since publish, rounded to two decimal places. 0 when the item has no published_at.

string

Item visibility status, such as active or draft.

string

Item processing status.

object

The item’s linked Shopify variant. Only available when the item has a linked variant.

Show variant properties

integer

Shopify purchase price in cents.

integer

Shopify unit cost in cents. May be nil.

string

Locally stored Shopify variant metafield value, keyed by metafield key.

object

The variant’s parent product.

Show product properties

string

Shopify product metafield value, keyed by metafield key.

Cycle

varies

One entry per scalar custom field defined on cycles, keyed by the definition’s key. The Liquid type mirrors the custom field type: money and integer are integers (money in cents), boolean is a boolean, and text, date, and date_time are strings.

date

Planned fulfill date for the outbound leg.

date

Date the cycle was fulfilled, when set.

date

Cycle start date.

date

Cycle end date.

date

Planned receive date for the inbound leg.

date

Date the cycle was received back, when set.

date

Restock-by date for the inbound leg.

number

Days this cycle utilized the item, rounded to two decimal places.

integer

Original unit price on the line item, in cents.

integer

Discounted unit price on the line item, in cents.

integer

Subtotal of open (not canceled) charges on the cycle, in cents.

integer

Amount paid across open charges on the cycle, in cents.

integer

Amount still due across open charges on the cycle, in cents.

integer

Deposit amount on the cycle in cents, or 0 when there is no deposit.

integer

Deposit amount refunded in cents, or 0 when there is no deposit.

object

The rented item. Includes the item’s custom fields, system fields, and, when the item has a linked Shopify variant, its variant data. Nested as item.*, for example item.completed_cycles or item.acquisition_cost.

Show item properties

varies

One entry per scalar custom field defined on items, keyed by the definition’s key.

integer

Number of completed cycles on the item.

integer

Number of unfulfilled (upcoming) cycles on the item.

integer

Number of currently active cycles on the item.

integer

Item acquisition cost in cents.

integer

Lifetime revenue attributed to the item, in cents.

integer

Lifetime ROI for the item in cents.

number

Share of the item’s published lifetime spent utilized, as a fraction from 0 to 1.

number

Total days the item has been utilized.

number

Total days the item has not been utilized since publish.

string

Item visibility status.

string

Item processing status.

object

The item’s linked Shopify variant. Only available when the item has a linked variant.

Show variant properties

integer

Shopify purchase price in cents.

integer

Shopify unit cost in cents. May be nil.

string

Locally stored Shopify variant metafield value, keyed by metafield key.

object

The variant’s parent product.

Show product properties

string

Shopify product metafield value, keyed by metafield key.

Consignor

varies

One entry per scalar custom field defined on consignors, keyed by the definition’s key. The Liquid type mirrors the custom field type: money and integer are integers (money in cents), boolean is a boolean, and text, date, and date_time are strings.

See Shopify’s Liquid reference for tags and filters.

Result types

A calculated field’s output must match its declared result type. The result types are the same scalar set as the referenceable custom field types: money (stored as cents, for example "4500"), integer, boolean, single_line_text_field, multi_line_text_field, date, and date_time.

Example formulas

Miles completed during a cycle (integer)

Set on a cycle. Record the item’s odometer reading at handover and return, and store the difference as the miles completed on this cycle.

{{ fields.odometer_return | minus: fields.odometer_start }}

Total miles completed on an item (integer)

Set on an item. Accumulate miles across cycles by adding this cycle’s contribution to the running total already stored on the item. Because calculated fields recalculate on demand, select Recalculate on the item’s total_miles field after each cycle to roll its value forward.

{{ fields.total_miles | plus: fields.miles_this_cycle }}

Average revenue per completed cycle (money)

Set on an item. Divide lifetime revenue by completed cycles. Money stays in cents.

{% if completed_cycles > 0 %}
  {{ lifecycle_revenue | divided_by: completed_cycles }}
{% else %}
  0
{% endif %}

Time to breakeven, in cycles (integer)

Set on an item. Divide the remaining cost to recover by the average revenue per cycle, using system fields for acquisition cost and lifecycle revenue plus an average_revenue_per_cycle metafield you maintain on the product.

{% assign remaining = acquisition_cost | minus: lifecycle_revenue %}
{{ remaining | divided_by: variant.product.metafields.average_revenue_per_cycle | ceil }}

Has broken even (boolean)

Set on an item. Flag items whose lifecycle revenue has met or exceeded their acquisition cost.

{% if lifecycle_revenue >= acquisition_cost %}true{% else %}false{% endif %}

Cycle yield including charges (money)

Set on a cycle. Add the discounted line price to the charges paid on the cycle.

{{ discounted_unit_price | plus: charges_paid }}

Recalculate a value

Calculated fields don’t update on their own when the fields they depend on change.

Open the record

Open the item, cycle, or consignor that owns the calculated field.

Find the calculated field

Scroll to the Custom fields section and find the field.

Recalculate

Select the field, then select Recalculate. The formula renders against the record’s current values and the result is saved.

If the formula is invalid, or the result doesn’t match the declared result type (for example "abc" for a Money field), the recalculation fails and the stored value is left unchanged. Fix the formula under Custom data and try again.

Overview

Setup

Methods

Manage

Sales channels

Configuration

Create a calculated field

Write formulas

General rules

Liquid basics

Conditional logic

Intermediate values

Liquid variable reference

Scalar custom field types

Liquid references by owner

Result types

Example formulas

Miles completed during a cycle (integer)

Total miles completed on an item (integer)

Average revenue per completed cycle (money)

Time to breakeven, in cycles (integer)

Has broken even (boolean)

Cycle yield including charges (money)

Recalculate a value

​Create a calculated field

​Write formulas

​General rules

​Liquid basics

​Conditional logic

​Intermediate values

​Liquid variable reference

​Scalar custom field types

​Liquid references by owner

​Result types

​Example formulas

​Miles completed during a cycle (integer)

​Total miles completed on an item (integer)

​Average revenue per completed cycle (money)

​Time to breakeven, in cycles (integer)

​Has broken even (boolean)

​Cycle yield including charges (money)

​Recalculate a value

Create a calculated field

Write formulas

General rules

Liquid basics

Conditional logic

Intermediate values

Liquid variable reference

Scalar custom field types

Liquid references by owner

Result types

Example formulas

Miles completed during a cycle (integer)

Total miles completed on an item (integer)

Average revenue per completed cycle (money)

Time to breakeven, in cycles (integer)

Has broken even (boolean)

Cycle yield including charges (money)

Recalculate a value