Custom fields

Add custom field definitions to your items, cycles, and consignors

Custom fields let you add custom field definitions to your items, cycles, and consignors, so you can capture additional information specific to your business needs. This is useful for tracking specialized attributes, internal notes, or business-specific data that isn’t covered by Supercycle’s standard fields.

Supercycle custom fields are available on:

• Items
• Cycles
• Consignors

For other Shopify resources such as products, variants, orders, and customers, use Shopify metafields to capture the same kind of structured custom data. Shopify metafields and Supercycle custom fields can coexist on the same resource.

For read-only fields whose values are computed from a formula, see Calculated fields.

Setting up custom fields

Access custom data settings

1. Navigate to custom data

   In Shopify Admin, head to Supercycle > Settings > Custom data.

Create custom field definitions

1. Choose data type

   Select whether you want to add custom fields to Items, Cycles, or Consignors.

2. Add new definition

   Click Add definition to create a new custom field.

3. Configure field details

   Set up your custom field:

   • Name: Display name for the field (e.g., “Serial Number”, “Condition Notes”)
   • Key: Auto-generated identifier based on the name (can be manually edited)
   • Type: Select from the available field types (see below)
4. Save definition

   Click Save to create the custom field definition.

Field types

Custom fields support the following types:

Type	Description
Single line text field	Short text input for simple values like serial numbers or codes
Multi line text field	Longer text input for notes or descriptions
Boolean	True/false checkbox for yes/no values
Date	Date picker for dates without time
Date and time	Date and time picker for timestamps
Money	Currency value input
Integer	Whole number input (positive or negative)
Color	Hex color value (e.g. #1a2b3c)
URL	Link to an external resource (must start with http:// or https://)
JSON	Arbitrary JSON-formatted value for structured data
Customer reference	Link to a customer record
Cycle reference	Link to a cycle record
Item reference	Link to an item record
Return reference	Link to a return order record

The field type cannot be changed after creation. Choose the appropriate type when creating your custom field definition.

Display as relative time

Field definitions with type Date or Date and time show a Display as relative time checkbox. Turn it on to show how long ago the date was instead of the date itself, so 1 January 2025 reads as 1 year 8 months.

This is useful for anything you would otherwise keep up to date by hand, such as the age of a bike. Store the date of purchase once and the elapsed time stays accurate on its own.

Stored value	Shown as
1 January 2025 (20 months ago)	1 year 8 months
Exactly 2 years ago	2 years
5 days ago	5 days ago
14 months from now	In 1 year 2 months

Dates less than a month old show in days, hours, or minutes instead of years and months.

Only the display changes. The stored value is still a date, editing the field still uses the date picker, and the API returns the date.

The checkbox clears automatically if you change the field type away from date or date and time.

Include in consignor payouts

When consignment is enabled, item and cycle field definitions with type Money or Integer show an Include in consignor payouts checkbox. Turn it on to add that field as a column on consignor payout breakdown reports — for example a repair fee your revenue share formula deducts.

Values read live from the entry’s item or cycle when you open the payout, so fees entered after the sale still appear. Money columns on the payout itself stay frozen at earning time. If the field is empty or its source record was deleted, the cell is blank.

The checkbox clears automatically if you change the field type away from money or integer.

Managing custom field definitions

Edit existing definitions

Click on any custom field definition name to edit its settings. You can update the name and key, but the type cannot be changed after creation.

View usage statistics

The custom data table shows how many items or cycles are using each field definition, helping you track adoption and identify unused fields.

Delete definitions

Use the Delete button on individual field definition pages to remove unused custom fields. Be careful as this action cannot be undone.

Best practices

Field naming

Use clear, descriptive names for your custom fields that will be easily understood by your team (e.g., “Warranty Expiration”, “Purchase Order Number”).

Key consistency

While keys are auto-generated, you can customize them for API consistency. Use lowercase letters, numbers, and underscores only.