Update minimum cycles for a subscription contract

Updates the minimum number of billing cycles (orders) that a customer must complete before they can cancel their subscription. This creates a commitment period that helps with customer retention and business predictability.

Full behavior, validation rules, and side effects

What are Minimum Cycles? Minimum cycles represent a commitment period where:

• Customers must complete a specified number of orders
• Cancellation is blocked until the minimum is met
• Often tied to special pricing or promotional offers
• Counted from the subscription start date

Key Features:

• Updates commitment period for existing subscriptions
• Can increase or decrease minimum cycles
• Setting to null removes the minimum commitment
• Preserves all other subscription settings
• Automatically handles invalid discount codes
• Updates future billing queue after change

Common Use Cases:

• Promotional Offers: ‘3-month minimum for 50% off’
• Hardware Subsidies: ‘12-month commitment with free device’
• Loyalty Programs: Reduce minimum after customer proves loyalty
• Seasonal Campaigns: Temporary commitment requirements
• Contract Adjustments: Customer service exceptions

Impact on Customers:

• Cannot cancel via portal until minimum cycles complete
• Pause/resume typically still allowed (check settings)
• Shows commitment status in customer portal
• No automatic notification sent (consider sending separately)

Cycle Counting:

• Only successful billing attempts count toward minimum
• Failed payments don’t increment the cycle count
• Skipped orders (if allowed) don’t count
• Current cycle = successful past orders + 1

Interaction with Max Cycles:

• Min cycles must be less than or equal to max cycles
• If max cycles exist, subscription auto-cancels after maximum
• Common pattern: 3 min cycles, 12 max cycles

Best Practices:

• Clearly communicate commitment terms upfront
• Consider grandfathering existing customers
• Use reasonable minimums (typically 3-12 cycles)
• Document reason for changes in activity logs
• Send customer notification for transparency

Important Notes:

• Changes apply immediately to cancellation logic
• Doesn’t affect past or in-progress orders
• Customer portal respects this setting automatically
• Activity log tracks old and new values
• Consider legal requirements in your jurisdiction

Authentication: Requires valid X-API-Key header

PUT /api/external/v2/subscription-contracts-update-min-cycles

Update minimum cycles for a subscription contract

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-min-cycles

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]",
    "displayName": "John Doe"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 6,
    "maxCycles": null,
    "anchors": [
      {
        "type": "MONTHDAY",
        "day": 1
      }
    ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customerPaymentMethod": {
    "id": "gid://shopify/CustomerPaymentMethod/123456",
    "instrument": {
      "__typename": "CustomerCreditCard",
      "brand": "VISA",
      "lastDigits": "4242",
      "expiryMonth": 12,
      "expiryYear": 2025
    }
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "Premium Subscription Box",
          "currentPrice": {
            "amount": "49.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}

Headers

X-API-Key · string

Query Parameters

contractId · integer<int64> · required

Contract ID

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

minCycles · integer | null

Minimum Number of Orders. The minimum number of billing cycles a customer must complete before being allowed to cancel. Set to null to remove the minimum commitment. Common values:

• 3: Three-month commitment
• 6: Six-month commitment
• 12: Annual commitment
• null: No commitment

Required range: 1 <= x <= 9999

Response

200

application/json

Minimum cycles updated successfully

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes