Get subscription contract analytics and revenue metrics

What This Endpoint Returns: Financial and operational analytics for a single subscription contract, calculated from all successful billing attempts throughout the subscription’s lifetime. Unlike realtime contract queries, this provides historical aggregated data.

Metrics Included:

Revenue Metrics:

• totalOrderAmount: Total revenue in decimal format (e.g., 299.95)
• totalOrderRevenue: Formatted currency string (e.g., “$299.95”)
• Calculated from all SUCCESS status billing attempts
• Includes taxes, shipping, and discounts
• Does NOT include failed or pending payments

Order Count:

• totalOrders: Count of successful billing attempts
• Represents number of orders generated by subscription
• Does NOT include failed billing attempts
• Starts at 0 for brand new subscriptions

Currency Formatting:

• Uses shop’s configured money_format
• Respects shop’s currency code (USD, EUR, GBP, etc.)
• Handles currency symbols and decimal places correctly
• Falls back to USD if currency unknown

Calculation Logic:

Data Source:

SELECT 
  COUNT(*) as totalOrders,
  SUM(order_amount) as totalOrderAmount
FROM subscription_billing_attempt
WHERE shop = ? 
  AND contract_id = ?
  AND status = 'SUCCESS'

What Gets Counted:

• ✅ Initial subscription order
• ✅ All successful recurring orders
• ✅ Manual billing attempts that succeeded
• ✅ Retry attempts that eventually succeeded
• ❌ Failed payment attempts
• ❌ Skipped billing cycles
• ❌ Cancelled/voided orders
• ❌ Pending/in-progress billing

Use Cases:

1. Customer Lifetime Value:

• Calculate total revenue from specific customer
• Measure subscription ROI
• Identify high-value subscriptions
• Track revenue growth over time

2. Subscription Performance:

• Analyze revenue per subscription
• Compare subscriptions by total value
• Identify most profitable subscription types
• Calculate average order value

3. Customer Portal:

• Display “You’ve saved $XXX” messaging
• Show “X orders delivered” stats
• Celebrate subscription milestones
• Build customer loyalty through transparency

4. Reporting & Analytics:

• Build subscription revenue dashboards
• Generate customer value reports
• Track subscription health metrics
• Forecast future revenue

5. Business Intelligence:

• Segment customers by subscription value
• Identify churn risk (low order count)
• Calculate retention rates
• Measure subscription program success

Response Format:

{
  "totalOrders": 12,
  "totalOrderAmount": 599.88,
  "totalOrderRevenue": "$599.88"
}

Response Fields:

• totalOrders (integer): Count of successful billing attempts
• totalOrderAmount (decimal): Numeric revenue total
• totalOrderRevenue (string): Formatted currency display

Example Scenarios:

Brand New Subscription:

{
  "totalOrders": 0,
  "totalOrderAmount": 0.00,
  "totalOrderRevenue": "$0.00"
}

After First Successful Order:

{
  "totalOrders": 1,
  "totalOrderAmount": 49.99,
  "totalOrderRevenue": "$49.99"
}

Established Subscription (EUR):

{
  "totalOrders": 24,
  "totalOrderAmount": 1199.76,
  "totalOrderRevenue": "€1.199,76"
}

Integration Examples:

Customer Portal - Loyalty Display:

const analytics = await fetch(
  `/api/external/v2/subscription-contract-details/analytics/${contractId}`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

const loyaltyMessage = `
  <div class="loyalty-badge">
    <h3>Thank you for your loyalty!</h3>
    <p>You've received ${analytics.totalOrders} orders</p>
    <p>Total value: ${analytics.totalOrderRevenue}</p>
  </div>
`;

Revenue Dashboard:

// Fetch analytics for multiple subscriptions
const contractIds = [123, 456, 789];
const analyticsPromises = contractIds.map(id => 
  getContractAnalytics(id)
);

const allAnalytics = await Promise.all(analyticsPromises);
const totalRevenue = allAnalytics.reduce(
  (sum, a) => sum + a.totalOrderAmount, 0
);

console.log(`Total subscription revenue: $${totalRevenue.toFixed(2)}`);

Important Considerations:

Data Accuracy:

• Based on Appstle’s billing attempt records
• May differ slightly from Shopify order totals
• Includes only what Appstle successfully billed
• Updated after each billing attempt completes

Currency Handling:

• Formatting uses shop’s money_format setting
• Different shops may have different decimal separators
• Currency symbol placement varies by locale
• Always use totalOrderAmount for calculations

Performance:

• Fast database aggregation query
• Typical response time: 100-300ms
• Indexed by shop and contract ID
• Suitable for real-time display

Best Practices:

1. Use for Display: Use totalOrderRevenue for customer-facing display
2. Calculate with Amount: Use totalOrderAmount for mathematical operations
3. Cache Strategically: Cache for dashboards, fetch real-time for critical displays
4. Handle Zero: Gracefully handle new subscriptions with 0 orders
5. Validate Contract: Ensure contract exists before querying analytics

Limitations:

What’s NOT Included:

• Future projected revenue
• Failed payment attempt counts
• Refunds or chargebacks
• Pending/processing orders
• Orders from other subscriptions

Related Calculations:

Average Order Value:

const aov = analytics.totalOrderAmount / analytics.totalOrders;
console.log(`Average order value: $${aov.toFixed(2)}`);

Customer Lifetime Value (projected):

const monthsActive = calculateMonthsActive(contract.createdAt);
const monthlyRevenue = analytics.totalOrderAmount / monthsActive;
const projectedLTV = monthlyRevenue * 12; // Annual LTV

Authentication: Requires valid X-API-Key header