> ## 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 that tells Supercycle how to create a cycle from a cart line

The `_cycle` line item property is a JSON-encoded object holding everything Supercycle needs to create a cycle from a line item when the order is placed. A line item without a `_cycle` property isn't processed by Supercycle.

<Note>
  The `_cycle` format can change between releases. Integrations and automations should build on [Shopify Flow](/documentation/manage/automation/create-workflow) rather than parse this property.
</Note>

***

## How it works

<Steps>
  <Step title="Fetch the property">
    When a customer selects a method option, the [Intent](/api-reference/storefront/intent) endpoint returns the `_cycle` property. The Methods app block does this for you. A custom storefront calls the endpoint directly.
  </Step>

  <Step title="Submit it with the cart line">
    The `properties[_cycle]` value goes into the add-to-cart request as a hidden input or a form data field.
  </Step>

  <Step title="Create the cycle">
    When the order is created, Supercycle reads the `_cycle` property and creates a cycle for that line item.
  </Step>
</Steps>

***

## Examples

<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": { "variant_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>

***

## Schema

<ResponseField name="item" type="object" required>
  How Supercycle selects an inventory item to assign to the cycle.

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

    <ResponseField name="filters" type="object">
      Filters that 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[]">
              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 it's created. Only the relevant keys are 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 come back in for the credits to be returned.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="subscription_contract_creator" type="object">
      Creates a Shopify subscription contract for the cycle. Used where selling plans aren't available, for example on 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 your custom field definitions.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="rental_start" type="date">
  The requested rental start date. Present for the subscription and calendar methods.
</ResponseField>

<ResponseField name="rental_end" type="date">
  The requested rental end date. Present for the calendar and membership methods.
</ResponseField>

<ResponseField name="minimum_term" type="string">
  The minimum rental duration. Present for the subscription method.
</ResponseField>