External APIs (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves all available billing frequency options configured for specific Shopify selling plan(s). Returns the complete set of billing intervals that customers can choose from, including frequency, interval type, and any associated discounts or pricing policies.

What This Endpoint Does: Queries the subscription group plans database to find all frequency configurations associated with given selling plan ID(s). This is essential for building subscription frequency selectors in customer portals or during subscription modifications.

Key Concepts:

Selling Plans:

• Shopify's mechanism for defining subscription options
• Each product variant can have multiple selling plans
• Selling plans define billing/delivery frequency
• Plans are grouped in subscription groups

Frequency Info:

• Specific billing interval configuration
• E.g., "Every 2 weeks", "Every month", "Every 3 months"
• Includes pricing policies and discounts
• Customers select from available frequencies

Request Parameters:

sellingPlanIds (required):

• Comma-separated list of Shopify selling plan IDs
• Example: "123456,123457,123458"
• Can query single or multiple plans
• Returns frequencies for ALL provided plans

Lookup Process:

1. Parse selling plan IDs from comma-separated string
2. Find subscription groups containing these plans
3. Extract frequency configurations from group JSON
4. Return all matching frequency options
5. Deduplicate if same frequency appears multiple times

Response Data Included:

For Each Frequency Option:

• id: Selling plan ID
• frequencyName: Display name (e.g., "Monthly")
• interval: WEEK, MONTH, or YEAR
• intervalCount: Number of intervals (e.g., 2 for bi-weekly)
• deliveryInterval: Same or different from billing
• deliveryIntervalCount: Delivery frequency
• pricingPolicy: Discount configuration
• billingPolicy: Min/max cycles, anchor settings

Pricing Policy Details:

• Discount type (percentage, fixed amount)
• Discount value
• After cycle discounts (e.g., "50% off first 3 months")
• Adjustment type

Use Cases:

1. Frequency Selection UI:

• Build dropdown/radio list of frequency options
• Show available intervals to customers
• Display pricing for each frequency
• Enable subscription frequency changes

2. Subscription Modification:

• Show current frequency and alternatives
• Allow customers to switch frequencies
• Validate new frequency selection
• Preview pricing changes

3. Product Page:

• Display subscription frequency options
• Show "Subscribe and save" pricing
• Calculate savings per frequency
• Build subscription purchase selectors

4. Customer Portal:

• "Change Frequency" functionality
• Show all available options
• Highlight current selection
• Display pricing differences

Response Format:

[
  {
    "id": "123456",
    "frequencyName": "Every 2 Weeks",
    "interval": "WEEK",
    "intervalCount": 2,
    "deliveryInterval": "WEEK",
    "deliveryIntervalCount": 2,
    "pricingPolicy": {
      "adjustmentType": "PERCENTAGE",
      "adjustmentValue": "10.0"
    }
  },
  {
    "id": "123457",
    "frequencyName": "Monthly",
    "interval": "MONTH",
    "intervalCount": 1,
    "deliveryInterval": "MONTH",
    "deliveryIntervalCount": 1,
    "pricingPolicy": {
      "adjustmentType": "PERCENTAGE",
      "adjustmentValue": "15.0"
    }
  }
]

Integration Example:

Customer Portal - Frequency Selector:

// Get selling plan from current subscription
const currentSellingPlanId = subscription.sellingPlanId;

// Fetch available frequencies
const frequencies = await fetch(
  `/api/external/v2/subscription-contract-details/billing-interval?sellingPlanIds=${currentSellingPlanId}`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

// Build selector
const selector = frequencies.map(freq => `
  <option value="${freq.id}" 
    ${freq.id === currentSellingPlanId ? 'selected' : ''}>
    ${freq.frequencyName} - Save ${freq.pricingPolicy.adjustmentValue}%
  </option>
`).join('');

document.querySelector('#frequency-select').innerHTML = selector;

Important Considerations:

Data Source:

• Queries Appstle database (NOT Shopify API)
• Based on subscription group configuration
• Fast response (< 100ms typically)
• Data synced when groups are updated

Multiple Selling Plans:

• Can query multiple plans at once
• Returns union of all frequencies
• Useful for products with multiple subscription options
• Results may contain duplicates if plans share frequencies

Empty Results:

• Returns empty array [] if no plans found
• Returns empty if selling plan ID invalid
• Not an error - handle gracefully

Best Practices:

1. Query Relevant Plans: Only query selling plans for current product/variant
2. Display Discounts: Show savings clearly in UI
3. Sort by Interval: Order options logically (weekly → monthly → yearly)
4. Highlight Current: Clearly mark customer's current frequency
5. Cache Results: Cache frequency data per selling plan

Authentication: Requires valid X-API-Key header

Retrieves comprehensive analytics for a specific subscription contract, including total revenue generated, number of successful orders, and formatted revenue display. This endpoint provides key performance metrics for understanding the financial impact of individual subscriptions.

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

Retrieves all valid delivery methods available for a specific subscription contract. Returns shipping profiles and delivery options based on the contract's delivery address and product characteristics.

Delivery Information Returned:

• Available shipping profiles
• Delivery methods for each profile
• Shipping rates and costs
• Delivery speed (standard, express, etc.)
• Method names and descriptions
• Eligibility based on address and products

Filtering Behavior: By default, returns only delivery methods valid for the contract:

• Matches delivery address country/region
• Compatible with subscription products
• Available for contract weight/dimensions

Include All Methods: Use header X-Include-All-Methods: true to return all delivery methods regardless of eligibility. Useful for admin UIs where you want to show all options.

Use Cases:

• Display delivery method selector in customer portal
• Allow customers to change shipping method
• Calculate shipping costs for subscription
• Validate delivery method during subscription updates
• Show upgrade options (standard to express)

Common Scenarios:

Customer Portal - Change Delivery Speed:

1. Call this endpoint with contractId
2. Display available methods to customer
3. Customer selects preferred method
4. Update subscription with new delivery method ID

Subscription Creation - Delivery Selection:

1. Get delivery options for draft contract
2. Present options during checkout/signup
3. Create subscription with selected method

Important Notes:

• Delivery options depend on current contract address
• Changing address may change available methods
• Costs may vary based on products in subscription
• Some methods may have minimum order requirements
• International shipping may have additional restrictions

Authentication: Requires X-API-Key header