The _cycle property format is subject to change as we iterate on it.
Integrations and automations should use Shopify
Flow instead of relying
directly on this token. A JSON-encoded object that contains everything Supercycle needs to create a Cycle from the line item when an order is placed. If an item doesn’t have a _cycle property, Supercycle will not process that
item.
Full
Calendar
Membership
Subscription
Resale
{ "item" : { "type" : "existing" , "filters" : { "availability" : { "from" : "2025-01-01" , "to" : "2025-01-14" }, "location" : { "shopify_id" : 123456 }, "condition" : { "ids" : [ 1 , 2 ] } } }, "attachments" : { "deposit" : { "variant_id" : 987654 }, "membership_credit" : { "cost" : 5 }, "subscription_contract_creator" : { "selling_plan_id" : 123 }, "custom_fields" : { "damage_waiver_taken " : "true" , "message" : "Happy Birthday" } }, "method_type" : "subscription" , "minimum_term" : "3 months" , "rental_start" : "2025-01-01" }
{ "item" : { "type" : "existing" , "filters" : { "availability" : { "from" : "2025-01-10" , "to" : "2026-01-15" }, "location" : { "shopify_id" : 789 } } }, "attachments" : { "custom_fields" : { "delivery_notes" : "Leave at the front desk" } }, "method_type" : "calendar" , "rental_start" : "2025-01-05" , "rental_end" : "2025-01-20" }
{ "item" : { "type" : "existing" , "filters" : { "availability" : { "from" : "2026-03-15" , "to" : "2026-04-15" } } }, "attachments" : { "membership_credit" : { "cost" : 20 }, "custom_fields" : { "backup_item" : "234450" } }, "method_type" : "membership" , "rental_start" : "2026-03-15" , "rental_end" : "2026-04-15" }
{ "item" : { "type" : "existing" , "filters" : { "availability" : { "from" : "2026-04-01" , "to" : "2026-04-30" }, "location" : { "shopify_id" : 555 }, "condition" : { "ids" : [ 1 ] } } }, "attachments" : { "deposit" : { "shopify_id" : 999 }, }, "method_type" : "subscription" , "rental_start" : "2026-04-01" , "rental_end" : "2026-04-30" }
{ "item" : { "type" : "existing" , "filters" : { "location" : { "shopify_id" : 123456 }, "condition" : { "ids" : [ 3 ] } } }, "attachments" : { "custom_fields" : { "gift_message" : "Enjoy!" } }, "method_type" : "resale" }
Describes how Supercycle selects an inventory item to assign to the Cycle. Always "existing" — selects from existing inventory items.
Filters used to narrow down which inventory item is selected. Restricts selection to items available within a date range. Start of the required availability window.
End of the required availability window.
Restricts selection to items at a specific Shopify location. Shopify ID of the location.
Restricts selection to items in specific conditions. Array of Supercycle condition IDs the item must match.
Optional objects applied to the Cycle after creation. Only relevant keys will be present. Links a deposit line item to the Cycle. Shopify variant ID of the deposit.
Deducts credits from the customer’s membership balance. Number of credits to deduct.
The condition the item must be returned in to receive credits back.
subscription_contract_creator
Creates a Shopify subscription contract for the Cycle. Used when selling plans are unavailable (e.g. draft orders). Shopify selling plan ID used to configure the contract.
Key-value pairs of custom field values to attach to the Cycle. Keys must match configured custom field definitions.
The rental method. One of "subscription", "membership", "calendar",
"resale".
The requested rental start date. Present for Subscription and Calendar
methods.
The minimum rental duration. Present for Subscription methods.
How it works
When a customer selects a circular option, the _cycle property is fetched from the Intent endpoint and attached to the cart line item. The Supercycle methods app block handles this automatically. For custom storefronts, you can call the Intent endpoint directly.
The properties[_cycle] value is submitted with the add-to-cart request as a hidden input or form data field.
When the order is created, Supercycle reads the _cycle property and creates a Cycle for that line item.
