Update maximum cycles for a subscription contract

Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders.

Full behavior, validation rules, and side effects

What are Maximum Cycles? Maximum cycles define subscription duration limits where:

• Subscription automatically cancels after the specified number of orders
• No further orders are generated once maximum is reached
• Useful for fixed-term offers, trials, or seasonal subscriptions
• Customer is notified before final order (if configured)

Key Features:

• Cannot set below current cycle count (prevents immediate cancellation)
• Setting to null creates an indefinite subscription
• Automatically reschedules order queue based on new limit
• Preserves all other subscription settings
• Validates against current subscription progress

Current Cycle Calculation:

• Current cycle = Successful billing attempts + 1
• Failed payments don’t count toward maximum
• First order is cycle 1, second is cycle 2, etc.
• System prevents setting max below current position

Common Use Cases:

• Trial Subscriptions: ‘3-box trial’ that auto-ends
• Seasonal Programs: ‘6-month summer subscription’
• Limited Series: ‘12-issue magazine subscription’
• Promotional Offers: ‘First 5 boxes at special price’
• Gift Subscriptions: Fixed duration gifts that don’t renew

What Happens at Maximum: When a subscription reaches its maximum cycles:

1. Final order is processed normally
2. Subscription status changes to CANCELLED
3. No future orders are scheduled
4. Customer receives cancellation notification
5. Cannot be reactivated (new subscription required)

Interaction with Min Cycles:

• Can have both min and max (e.g., 3 min, 12 max)
• Min cycles enforces commitment period
• Max cycles enforces termination
• Common pattern: Commitment with defined end

Queue Management: After updating max cycles:

• System recalculates future order schedule
• Removes orders beyond the new maximum
• Adjusts upcoming order notifications
• Updates subscription end date projections

Important Notes:

• Validation prevents accidental immediate cancellation
• Changes apply to future billing cycles only
• Activity log tracks old and new values
• Consider customer communication for changes
• Setting null removes any duration limit

Authentication: Requires valid X-API-Key header

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

Update maximum cycles for a subscription contract

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-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": 3,
    "maxCycles": 12,
    "anchors": [
      {
        "type": "MONTHDAY",
        "day": 15
      }
    ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lastBillingAttemptDate": "2024-03-01T00:00:00Z",
  "orders": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/Order/5678901234",
          "createdAt": "2024-03-01T00:00:00Z",
          "fulfillmentStatus": "FULFILLED",
          "financialStatus": "PAID"
        }
      },
      {
        "node": {
          "id": "gid://shopify/Order/5678901233",
          "createdAt": "2024-02-01T00:00:00Z",
          "fulfillmentStatus": "FULFILLED",
          "financialStatus": "PAID"
        }
      },
      {
        "node": {
          "id": "gid://shopify/Order/5678901232",
          "createdAt": "2024-01-01T00:00:00Z",
          "fulfillmentStatus": "FULFILLED",
          "financialStatus": "PAID"
        }
      }
    ]
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "12-Month Subscription Box",
          "currentPrice": {
            "amount": "39.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)

maxCycles · integer | null · required

Maximum Cycles. The total number of orders after which the subscription will automatically terminate. Must be greater than or equal to the current cycle count and any configured minimum cycles. Common values:

• 3: Three-order trial
• 6: Six-month seasonal subscription
• 12: Annual subscription
• 24: Two-year commitment
• null: Ongoing subscription with no end date

Required range: 1 <= x <= 9999

Response

200

application/json

Maximum 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