Get available billing intervals for selling plan(s)

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.

Full behavior, validation rules, and side effects

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

GET /api/external/v2/subscription-contract-details/billing-interval

Get available billing intervals for selling plan(s)

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/billing-interval

200

[
  {
    "frequencyCount": 123,
    "billingFrequencyCount": 123,
    "payAsYouGoPrepaidBillingFrequencyCount": 123,
    "frequencyName": "<string>",
    "frequencyDescription": "<string>",
    "discountOffer": 123,
    "discountOffer2": 123,
    "afterCycle1": 123,
    "afterCycle2": 123,
    "discountEnabled": true,
    "discountEnabled2": true,
    "discountEnabledMasked": true,
    "discountEnabled2Masked": true,
    "id": "<string>",
    "specificDayValue": 123,
    "specificMonthValue": 123,
    "specificDayEnabled": true,
    "maxCycles": 123,
    "minCycles": 123,
    "cutOff": 123,
    "prepaidFlag": "<string>",
    "idNew": "<string>",
    "freeTrialEnabled": true,
    "freeTrialCount": 123,
    "memberOnly": true,
    "nonMemberOnly": true,
    "memberInclusiveTags": "<string>",
    "memberExclusiveTags": "<string>",
    "formFieldJson": "<string>",
    "upcomingOrderEmailBuffer": 123,
    "frequencySequence": 123,
    "groupName": "<string>",
    "groupId": 123,
    "repeatingCycle": true,
    "repeatingNumberOfCycle": 123,
    "keepOriginalNextBillingDateAfterTrial": true,
    "defaultSelectedPlan": true,
    "frequencyNameTranslations": {},
    "appstleCycles": [
      {
        "afterCycle": 3,
        "discountType": "PERCENTAGE",
        "value": 10,
        "freeVariantId": 42549172011164,
        "freeProductHandle": "free-gift-product",
        "repeatingCycle": true,
        "repeatingNumberOfCycle": 6,
        "preventDuplicationFreeProduct": true
      }
    ]
  }
]

Headers

X-API-Key · string

Query Parameters

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

sellingPlanIds · string · required

Selling Plan ID

Response

200

application/json

Successfully retrieved billing intervals (may be empty array)

frequencyCount · integer<int32>

frequencyInterval · enum<string>

Available options: DAY, WEEK, MONTH, YEAR

billingFrequencyCount · integer<int32>

payAsYouGoPrepaidBillingFrequencyCount · integer<int32>

billingFrequencyInterval · enum<string>

Available options: DAY, WEEK, MONTH, YEAR

frequencyName · string

frequencyDescription · string

discountOffer · number<double>

discountOffer2 · number<double>

afterCycle1 · integer<int32>

afterCycle2 · integer<int32>

discountType · enum<string>

Available options: PERCENTAGE, FIXED, PRICE

discountType2 · enum<string>

Available options: PERCENTAGE, FIXED, PRICE

discountEnabled · boolean

discountEnabled2 · boolean

discountEnabledMasked · boolean

discountEnabled2Masked · boolean

id · string

frequencyType · enum<string>

Available options: ON_PURCHASE_DAY, ON_SPECIFIC_DAY

specificDayValue · integer<int32>

specificMonthValue · integer<int32>

specificDayEnabled · boolean

maxCycles · integer<int32>

minCycles · integer<int32>

cutOff · integer<int32>

prepaidFlag · string

idNew · string

planType · enum<string>

Available options: PAY_AS_YOU_GO, PREPAID, ADVANCED_PREPAID, PAY_AS_YOU_GO_PREPAID

deliveryPolicyPreAnchorBehavior · enum<string>

Available options: ASAP, NEXT, $UNKNOWN

freeTrialEnabled · boolean

freeTrialCount · integer<int32>

freeTrialInterval · enum<string>

Available options: DAY, WEEK, MONTH, YEAR

memberOnly · boolean

nonMemberOnly · boolean

memberInclusiveTags · string

memberExclusiveTags · string

formFieldJson · string

upcomingOrderEmailBuffer · integer<int32>

frequencySequence · integer<int32>

groupName · string

groupId · integer<int64>

repeatingCycle · boolean

repeatingNumberOfCycle · integer<int32>

keepOriginalNextBillingDateAfterTrial · boolean

defaultSelectedPlan · boolean

frequencyNameTranslations · object

Show child attributes

inventoryPolicyReserve · enum<string>

Available options: ON_FULFILLMENT, ON_SALE, $UNKNOWN

appstleCycles · object[]

Show child attributes