Get available billing intervals for selling plan(s)

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