# 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.

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:
json
[
  {
    "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:
javascript
// 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 => 
  
    ${freq.frequencyName} - Save ${freq.pricingPolicy.adjustmentValue}%
  
).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

Endpoint: GET /api/external/v2/subscription-contract-details/billing-interval
Version: 0.0.1

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

  - `sellingPlanIds` (string, required)
    Selling Plan ID

## Header parameters:

  - `X-API-Key` (string)

## Response 200 fields (application/json):

  - `frequencyCount` (integer)

  - `frequencyInterval` (string)
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `billingFrequencyCount` (integer)

  - `payAsYouGoPrepaidBillingFrequencyCount` (integer)

  - `billingFrequencyInterval` (string)
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `frequencyName` (string)

  - `frequencyDescription` (string)

  - `discountOffer` (number)

  - `discountOffer2` (number)

  - `afterCycle1` (integer)

  - `afterCycle2` (integer)

  - `discountType` (string)
    Enum: "PERCENTAGE", "FIXED", "PRICE"

  - `discountType2` (string)
    Enum: "PERCENTAGE", "FIXED", "PRICE"

  - `discountEnabled` (boolean)

  - `discountEnabled2` (boolean)

  - `discountEnabledMasked` (boolean)

  - `discountEnabled2Masked` (boolean)

  - `id` (string)

  - `frequencyType` (string)
    Enum: "ON_PURCHASE_DAY", "ON_SPECIFIC_DAY"

  - `specificDayValue` (integer)

  - `specificMonthValue` (integer)

  - `specificDayEnabled` (boolean)

  - `maxCycles` (integer)

  - `minCycles` (integer)

  - `cutOff` (integer)

  - `prepaidFlag` (string)

  - `idNew` (string)

  - `planType` (string)
    Enum: "PAY_AS_YOU_GO", "PREPAID", "ADVANCED_PREPAID", "PAY_AS_YOU_GO_PREPAID"

  - `deliveryPolicyPreAnchorBehavior` (string)
    Enum: "ASAP", "NEXT", "$UNKNOWN"

  - `freeTrialEnabled` (boolean)

  - `freeTrialCount` (integer)

  - `freeTrialInterval` (string)
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `memberOnly` (boolean)

  - `nonMemberOnly` (boolean)

  - `memberInclusiveTags` (string)

  - `memberExclusiveTags` (string)

  - `formFieldJson` (string)

  - `upcomingOrderEmailBuffer` (integer)

  - `frequencySequence` (integer)

  - `groupName` (string)

  - `groupId` (integer)

  - `repeatingCycle` (boolean)

  - `repeatingNumberOfCycle` (integer)

  - `keepOriginalNextBillingDateAfterTrial` (boolean)

  - `defaultSelectedPlan` (boolean)

  - `inventoryPolicyReserve` (string)
    Enum: "ON_FULFILLMENT", "ON_SALE", "$UNKNOWN"

  - `appstleCycles` (array)

  - `appstleCycles.afterCycle` (integer)
    The billing cycle number after which this pricing applies
    Example: 3

  - `appstleCycles.discountType` (string)
    Type of discount to apply in pricing cycles
    Enum: "PERCENTAGE", "FIXED", "PRICE", "SHIPPING", "FREE_PRODUCT", "PERCENTAGE", "FIXED", "PRICE", "SHIPPING", "FREE_PRODUCT"

  - `appstleCycles.value` (number)
    Discount value. For PERCENTAGE: 0-100 (e.g., 10 for 10% off). For FIXED: amount to subtract from price. For PRICE: new fixed price. For SHIPPING: shipping discount amount. For FREE_PRODUCT: not used (set freeVariantId or freeProductHandle instead)
    Example: 10

  - `appstleCycles.freeVariantId` (integer)
    Variant ID of a free product to add when discountType is FREE_PRODUCT
    Example: 42549172011164

  - `appstleCycles.freeProductHandle` (string)
    Product handle of a free product to add when discountType is FREE_PRODUCT
    Example: "free-gift-product"

  - `appstleCycles.repeatingCycle` (boolean)
    Whether this pricing should repeat for subsequent cycles
    Example: true

  - `appstleCycles.repeatingNumberOfCycle` (integer)
    Number of cycles to repeat this pricing for when repeatingCycle is true
    Example: 6

  - `appstleCycles.preventDuplicationFreeProduct` (boolean)
    Prevent adding duplicate free products if already in cart
    Example: true


## Response 400 fields

## Response 401 fields