# Get current billing cycle number for a subscription contract

Retrieves the current billing cycle number for a specific subscription contract. The cycle number represents how many successful billing attempts have occurred for this subscription, starting from 1 for the initial order.

What is a Billing Cycle?
A billing cycle represents one completed billing period in a subscription's lifetime. Each successful billing attempt increments the cycle count. This number is crucial for:
- Tracking subscription progress towards minimum/maximum cycle limits
- Applying cycle-based pricing adjustments (discounts after N cycles)
- Determining eligibility for cancellation (minimum cycles requirement)
- Calculating customer lifetime value
- Analyzing subscription retention metrics

How Cycle Counting Works:

Initial Order:
- Cycle 1 starts when subscription is first created
- Initial order counts as the first billing cycle
- Includes origin order that created the subscription

Subsequent Orders:
- Each successful billing attempt increments cycle by 1
- Only SUCCESS status billing attempts are counted
- Failed/skipped billing attempts do NOT increment cycle
- Paused subscriptions maintain their current cycle number

Calculation Formula:

Current Cycle = 1 + (Number of Successful Billing Attempts)


Example Timeline:
- Day 1: Subscription created, initial order → Cycle 1
- Day 30: First recurring order successful → Cycle 2
- Day 60: Second recurring order successful → Cycle 3
- Day 90: Billing fails (payment declined) → Still Cycle 3
- Day 95: Retry successful → Cycle 4

Use Cases:

1. Cancellation Eligibility:
- Verify customer has met minimum cycle requirement
- Enforce contract terms (e.g., "3 month minimum")
- Display "Can cancel after N more orders" messaging
- Block premature cancellations

2. Pricing Adjustments:
- Apply introductory pricing for first N cycles
- Trigger loyalty discounts after X cycles
- Calculate when pricing changes take effect
- Implement "First 3 months 50% off" promotions

3. Customer Retention:
- Identify subscriptions at risky cycle counts
- Send retention campaigns at specific milestones
- Track average cycles before churn
- Celebrate subscription anniversaries

4. Analytics & Reporting:
- Calculate customer lifetime value (cycle × price)
- Analyze subscription duration distribution
- Track retention curves by cohort
- Measure success of lifecycle campaigns

5. Customer Portal Display:
- Show "Order #X of Y" progress indicators
- Display remaining cycles until cancellation allowed
- Show subscription tenure/loyalty status
- Calculate and display subscription value earned

Response Format:

Returns a single integer representing the current cycle number:
json
3


Response Examples:

New subscription (just created):
json
1


After 5 successful billing attempts:
json
6

Note: Initial order (1) + 5 successful renewals = Cycle 6

Important Considerations:

Cycle vs. Billing Attempts:
- Failed billing attempts don't increment cycle
- Skipped orders don't increment cycle
- Manual order creation may not increment cycle
- Cycle represents successful billing events only

Paused Subscriptions:
- Cycle number remains frozen while paused
- Resumes at same cycle when un-paused
- Pause duration doesn't affect cycle count

Minimum/Maximum Cycles:
- minCycles: Minimum cycles before cancellation allowed
- maxCycles: Subscription auto-expires after this many cycles
- Use this endpoint to check progress towards these limits

Data Source:
- Queries Appstle database (not Shopify API)
- Counts records in subscription_billing_attempt table
- Filters by SUCCESS status only
- Fast response time ( r.json());

const minCycles = contract.minCycles || 0;

if (currentCycle >= minCycles) {
  console.log('Customer can cancel now');
  showCancelButton();
} else {
  const cyclesRemaining = minCycles - currentCycle;
  console.log(Must complete ${cyclesRemaining} more orders before canceling);
  showMinimumCommitmentMessage(cyclesRemaining);
}


Display progress to max cycles:
javascript
const currentCycle = await getCycleNumber(contractId);
const maxCycles = contract.maxCycles;

if (maxCycles) {
  const progress = (currentCycle / maxCycles) * 100;
  console.log(Subscription ${progress.toFixed(0)}% complete (${currentCycle}/${maxCycles}));
  
  if (currentCycle === maxCycles) {
    console.log('This is the final cycle - subscription will expire after this order');
  }
}
``

Performance Characteristics:

Fast Query:
- Simple database count query
- Indexed by shop and contractId
- Typical response time: 50-150ms
- Suitable for real-time UI updates

Best Practices:

1. Cache Results: Cache cycle number briefly (few minutes) to reduce API calls
2. Combine with Contract Data: Fetch contract details simultaneously for min/max cycles
3. Handle Edge Cases: Account for subscriptions with no successful billings yet
4. Display Progress: Show cycle number in customer-friendly format ("Order 3 of 12")
5. Sync with Billing: Update cycle number after each billing attempt completes

Common Misunderstandings:

Myth: Cycle = Months Subscribed
- Reality: Cycle = Successful billing attempts, not time elapsed
- A paused subscription stays at same cycle for months
- Failed payments don't advance the cycle

Myth: First order is Cycle 0
- Reality: Cycles start at 1, not 0
- Initial/origin order is Cycle 1

Related Fields:
- minCycles: Minimum cycles before cancellation (from contract)
- maxCycles: Maximum cycles before auto-expiry (from contract)
- billingInterval`: Frequency between cycles (from contract)

Authentication: Requires valid X-API-Key header

Endpoint: GET /api/external/v2/subscription-contract-details/current-cycle/{contractId}
Version: 0.0.1

## Header parameters:

  - `X-API-Key` (string, required)
    API Key for authentication
    Example: "sk_live_1234567890abcdef"

## Path parameters:

  - `contractId` (integer, required)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 404 fields