Subscription Management

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 --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-min-cycles

{
  "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": "customer@example.com",
    "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

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

Update order note for subscription

Update maximum cycles for a subscription contract

Update minimum cycles for a subscription contract

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

{
  "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": "customer@example.com",
    "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"
          }
        }
      }
    ]
  }
}