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

# Cycle line item property

> Schema for the `_cycle` line item property.

<Note>
  The `_cycle` property format is subject to change as we iterate on it.
  Integrations and automations should use [Shopify
  Flow](/documentation/manage/automation/create-workflow) instead of relying
  directly on this token.
</Note>

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.

<CodeGroup>
  ```json Full theme={null}
  {
    "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"
  }
  ```

  ```json Calendar theme={null}
  {
    "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"
  }
  ```

  ```json Membership theme={null}
  {
    "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"
  }
  ```

  ```json Subscription theme={null}
  {
    "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"
  }
  ```

  ```json Resale theme={null}
  {
    "item": {
      "type": "existing",
      "filters": {
        "location": { "shopify_id": 123456 },
        "condition": { "ids": [3] }
      }
    },
    "attachments": {
      "custom_fields": {
        "gift_message": "Enjoy!"
      }
    },
    "method_type": "resale"
  }
  ```
</CodeGroup>

<ResponseField name="item" type="object" required>
  Describes how Supercycle selects an inventory item to assign to the Cycle.

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"existing"` — selects from existing inventory items.
    </ResponseField>

    <ResponseField name="filters" type="object">
      Filters used to narrow down which inventory item is selected.

      <Expandable title="properties">
        <ResponseField name="availability" type="object">
          Restricts selection to items available within a date range.

          <Expandable title="properties">
            <ResponseField name="from" type="date">
              Start of the required availability window.
            </ResponseField>

            <ResponseField name="to" type="date">
              End of the required availability window.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object">
          Restricts selection to items at a specific Shopify location.

          <Expandable title="properties">
            <ResponseField name="shopify_id" type="integer">
              Shopify ID of the location.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="condition" type="object">
          Restricts selection to items in specific conditions.

          <Expandable title="properties">
            <ResponseField name="ids" type="integer[]">
              Array of Supercycle condition IDs the item must match.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="attachments" type="object">
  Optional objects applied to the Cycle after creation. Only relevant keys will be present.

  <Expandable title="properties">
    <ResponseField name="deposit" type="object">
      Links a deposit line item to the Cycle.

      <Expandable title="properties">
        <ResponseField name="variant_id" type="integer">
          Shopify variant ID of the deposit.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="membership_credit" type="object">
      Deducts credits from the customer's membership balance.

      <Expandable title="properties">
        <ResponseField name="cost" type="integer">
          Number of credits to deduct.
        </ResponseField>

        <ResponseField name="return_condition" type="string">
          The condition the item must be returned in to receive credits back.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="subscription_contract_creator" type="object">
      Creates a Shopify subscription contract for the Cycle. Used when selling plans are unavailable (e.g. draft orders).

      <Expandable title="properties">
        <ResponseField name="selling_plan_id" type="integer">
          Shopify selling plan ID used to configure the contract.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="custom_fields" type="object">
      Key-value pairs of custom field values to attach to the Cycle. Keys must match configured custom field definitions.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="method_type" type="string">
  The rental method. One of `"subscription"`, `"membership"`, `"calendar"`,
  `"resale"`.
</ResponseField>

<ResponseField name="rental_start" type="date">
  The requested rental start date. Present for Subscription and Calendar
  methods.
</ResponseField>

<ResponseField name="minimum_term" type="string">
  The minimum rental duration. Present for Subscription methods.
</ResponseField>

## How it works

1. When a customer selects a circular option, the `_cycle` property is fetched from the [Intent endpoint](/api-reference/storefront/intent) 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.
2. The `properties[_cycle]` value is submitted with the add-to-cart request as a hidden input or form data field.
3. When the order is created, Supercycle reads the `_cycle` property and creates a Cycle for that line item.

```
```