Calculated fields

Calculated fields are read-only custom fields whose value is computed from a Liquid formula. A single formula can pull from Supercycle custom fields, built-in Supercycle system values, and Shopify metafields on the same record. For example, you can divide acquisition cost by completed cycles, or set a flag from a metafield. Calculated fields are available on the same resources as custom fields (items, cycles, and consignors) and appear alongside regular custom fields in the Custom fields section on the record. Their value updates on demand via a Recalculate button on each field.

Create a calculated field

Open custom data settings

In Shopify Admin, head to Supercycle > Settings > Custom data and choose Items, Cycles, or Consignors.

Add a calculated definition

Click Add definition on the calculated fields card.

Configure the field

Set up your calculated field:

Name: Display name shown on the record (e.g., “Total rental cost”).
Key: Auto-generated identifier based on the name (can be manually edited).
Result type: The type of value the formula produces. Choose from single line text, multi line text, money, integer, boolean, date, or date and time.
Formula: A Liquid expression that computes the value.

Save definition

Click Save to create the calculated field.

The result type cannot be changed after creation. Choose the appropriate type when creating the definition.

Writing formulas

Formulas use Liquid, the same 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 clickable pills. Click one to insert it into your formula.

General rules

Formulas are evaluated in strict mode. Referencing an undefined variable causes the formula to fail.
Only scalar custom fields are referenceable. Reference fields (customer, cycle, item, return), color, URL, and JSON custom fields are not 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 clickable pills.
A calculated field cannot reference another calculated field.
Money values are always in cents (integer). For example, $15.00 is 1500. A money-typed formula must also produce cents.
Durations from system fields are in days (for example utilized_days and total_utilized_days).

Money fields are represented in cents inside formulas. Multiply and divide accordingly when combining money with other numbers, and remember that the result of a money-typed formula also has to be in cents.

For example, to compute a 10% discount off a daily rate stored as money:

{{ fields.daily_rate | times: 0.9 }}

To convert 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. Everything a formula produces has to end up inside output tags.
Tags: {% ... %} control logic and don’t render anything themselves (e.g. {% if %}, {% assign %}, {% case %}).

Values are transformed with filters, chained with |:

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

Common filters you’ll use 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 %}

Working with intermediate values

{% assign %} lets you name 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; below they are shown as fields.<key> and metafields.<key>.

Scalar custom field types

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

Custom field type	Liquid type	Example	Notes
`money`	integer	`1500`	Cents
`integer`	integer	`3`
`boolean`	boolean	`true` / `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 datetime

Liquid references by owner

The variables available in a formula depend on the calculated field’s owner. Expand an owner below to see every variable it exposes, along 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 cancelled) 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.

More information on using Liquid can be found on Shopify’s developer documentation.

Allowed result types

A calculated field’s output must match its declared result type. Result types are the same scalar set as the referenceable custom field types:

money (stored as cents, e.g. "4500")
integer
boolean
single_line_text_field
multi_line_text_field
date
date_time

Example formulas

Miles completed during a cycle (integer)

Set on a cycle. Record the item’s odometer reading at drop-off 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.

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

Because calculated fields recalculate on demand, click Recalculate on the item’s total_miles field after each cycle to roll its value forward.

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 remaining cost to recover by average revenue per cycle, using system fields for acquisition cost and lifecycle revenue plus a merchant-managed average_revenue_per_cycle metafield 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 charges paid on the cycle.

{{ discounted_unit_price | plus: charges_paid }}

Recalculating values

Calculated fields don’t update automatically when the fields they depend on change. To update a value:

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 locate the calculated field you want to update.

Recalculate

Click the field, then press Recalculate. The formula is rendered against the record’s current field values and the result is saved.

If the formula is invalid, or the rendered result doesn’t match the declared result type (for example, the formula produces "abc" for a money field), the recalculation fails and the previously stored value is left unchanged. Fix the formula in Settings > Custom data and try again.

Overview

Setup

Methods

Manage

Sales channels

Configuration

Create a calculated field

Writing formulas

General rules

Liquid basics

Conditional logic

Working with intermediate values

Liquid variable reference

Scalar custom field types

Liquid references by owner

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

Recalculating values

​Create a calculated field

​Writing formulas

​General rules

​Liquid basics

​Conditional logic

​Working with intermediate values

​Liquid variable reference

​Scalar custom field types

​Liquid references by owner

​Allowed 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)

​Recalculating values

Create a calculated field

Writing formulas

General rules

Liquid basics

Conditional logic

Working with intermediate values

Liquid variable reference

Scalar custom field types

Liquid references by owner

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

Recalculating values