> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 => `
  <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



## OpenAPI

````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-contract-details/billing-interval
openapi: 3.0.1
info:
  description: >-
    Comprehensive API documentation for managing subscriptions, payments, and
    related operations. These APIs allow you to programmatically manage
    subscription lifecycles, handle payments, configure products, and integrate
    subscription functionality into your applications.
  title: Admin APIs
  version: 0.0.1
servers:
  - url: https://subscription-admin.appstle.com
security: []
tags:
  - description: >-
      Core APIs for managing the complete subscription lifecycle including
      creation, updates, pausing, resuming, and cancellation of subscriptions.
    name: Subscription Management
  - description: >-
      APIs for managing subscription payment methods, processing payments,
      handling payment retries, and updating billing information.
    name: Subscription Payments
  - description: >-
      APIs for managing subscription contracts including delivery schedules,
      pricing, order notes, billing cycles, and shipping addresses.
    name: Subscription Contracts
  - description: >-
      APIs for managing products within subscriptions including adding,
      removing, updating quantities, and swapping products.
    name: Subscription Products
  - description: >-
      APIs for handling billing operations, payment processing, and financial
      transactions related to subscriptions.
    name: Billing & Payments
  - description: >-
      APIs for managing discounts and promotional codes applied to
      subscriptions.
    name: Subscription Discounts
  - description: >-
      APIs for managing one-time add-on products that can be purchased alongside
      recurring subscription items.
    name: Subscription One-Time Products
  - description: >-
      APIs for managing subscription plans, pricing tiers, and plan
      configurations.
    name: Subscription Plans
  - description: >-
      APIs for managing customizable product boxes and bundles where customers
      can select multiple items.
    name: Build-a-Box & Bundles
  - description: >-
      APIs for managing the product catalog including product information,
      variants, and inventory.
    name: Product Catalog
  - description: >-
      APIs for managing operational settings, configurations, and administrative
      functions.
    name: Operations & Settings
  - description: >-
      APIs powering the customer-facing portal where subscribers can manage
      their own subscriptions.
    name: Customer Portal
  - description: APIs for managing customer information, profiles, and account details.
    name: Customers
  - description: >-
      APIs for retrieving aggregated subscription data, customer subscription
      history, and account-level subscription information.
    name: Subscription Data
  - description: >-
      APIs for managing delivery profiles, shipping rates, free shipping
      configuration, and delivery method options on subscriptions.
    name: Delivery & Shipping
  - description: >-
      APIs for managing storefront customization including custom CSS, theme
      settings, label translations, and merchant-defined widget configuration.
    name: Customization
  - description: >-
      APIs for configuring cancellation flows, retention offers, cancellation
      reason management, and win-back automation.
    name: Customer Retention
paths:
  /api/external/v2/subscription-contract-details/billing-interval:
    get:
      tags:
        - Subscription Management
        - Subscription Contracts
      summary: Get available billing intervals for selling plan(s)
      description: >-
        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 => `
          <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
      operationId: getSubscriptionContractBillingInterval
      parameters:
        - description: API Key (Deprecated - Use Header X-API-Key instead)
          in: query
          name: api_key
          required: false
          schema:
            type: string
        - in: header
          name: X-API-Key
          required: false
          schema:
            type: string
        - description: Selling Plan ID
          in: query
          name: sellingPlanIds
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FrequencyInfoDTO'
                type: array
          description: Successfully retrieved billing intervals (may be empty array)
        '400':
          content:
            application/json:
              example:
                detail: sellingPlanIds parameter is required
                status: 400
                title: Invalid parameters
                type: https://example.com/errors/bad-request
          description: Bad request - Missing or invalid selling plan IDs
        '401':
          content:
            application/json:
              example:
                detail: Valid X-API-Key header is required
                status: 401
                title: Authentication required
                type: https://example.com/errors/unauthorized
          description: Authentication required
components:
  schemas:
    FrequencyInfoDTO:
      properties:
        afterCycle1:
          format: int32
          type: integer
        afterCycle2:
          format: int32
          type: integer
        appstleCycles:
          items:
            $ref: '#/components/schemas/AppstleCycle'
          type: array
        billingFrequencyCount:
          format: int32
          type: integer
        billingFrequencyInterval:
          enum:
            - DAY
            - WEEK
            - MONTH
            - YEAR
          type: string
        cutOff:
          format: int32
          type: integer
        defaultSelectedPlan:
          type: boolean
        deliveryPolicyPreAnchorBehavior:
          enum:
            - ASAP
            - NEXT
            - $UNKNOWN
          type: string
        discountEnabled:
          type: boolean
        discountEnabled2:
          type: boolean
        discountEnabled2Masked:
          type: boolean
        discountEnabledMasked:
          type: boolean
        discountOffer:
          format: double
          type: number
        discountOffer2:
          format: double
          type: number
        discountType:
          enum:
            - PERCENTAGE
            - FIXED
            - PRICE
          type: string
        discountType2:
          enum:
            - PERCENTAGE
            - FIXED
            - PRICE
          type: string
        fixedBillingDates:
          items:
            $ref: '#/components/schemas/FixedBillingDate'
          type: array
        formFieldJson:
          type: string
        freeTrialCount:
          format: int32
          type: integer
        freeTrialEnabled:
          type: boolean
        freeTrialInterval:
          enum:
            - DAY
            - WEEK
            - MONTH
            - YEAR
          type: string
        frequencyCount:
          format: int32
          type: integer
        frequencyDescription:
          type: string
        frequencyInterval:
          enum:
            - DAY
            - WEEK
            - MONTH
            - YEAR
          type: string
        frequencyName:
          type: string
        frequencyNameTranslations:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          type: object
        frequencySequence:
          format: int32
          type: integer
        frequencyType:
          enum:
            - ON_PURCHASE_DAY
            - ON_SPECIFIC_DAY
            - ON_FIXED_DATES
          type: string
        groupId:
          format: int64
          type: integer
        groupName:
          type: string
        id:
          type: string
        idNew:
          type: string
        inventoryPolicyReserve:
          enum:
            - ON_FULFILLMENT
            - ON_SALE
            - $UNKNOWN
          type: string
        keepOriginalNextBillingDateAfterTrial:
          type: boolean
        maxCycles:
          format: int32
          type: integer
        memberExclusiveTags:
          type: string
        memberInclusiveTags:
          type: string
        memberOnly:
          type: boolean
        minCycles:
          format: int32
          type: integer
        nonMemberOnly:
          type: boolean
        payAsYouGoPrepaidBillingFrequencyCount:
          format: int32
          type: integer
        planType:
          enum:
            - PAY_AS_YOU_GO
            - PREPAID
            - ADVANCED_PREPAID
            - PAY_AS_YOU_GO_PREPAID
          type: string
        prepaidFlag:
          type: string
        repeatingCycle:
          type: boolean
        repeatingNumberOfCycle:
          format: int32
          type: integer
        specificDayEnabled:
          type: boolean
        specificDayValue:
          format: int32
          type: integer
        specificMonthValue:
          format: int32
          type: integer
        upcomingOrderEmailBuffer:
          format: int32
          type: integer
      type: object
    AppstleCycle:
      description: Custom pricing cycle configuration for subscription line items
      properties:
        afterCycle:
          description: The billing cycle number after which this pricing applies
          example: 3
          format: int32
          minimum: 1
          type: integer
        discountType:
          description: Type of discount to apply in pricing cycles
          enum:
            - PERCENTAGE
            - FIXED
            - PRICE
            - SHIPPING
            - FREE_PRODUCT
            - PERCENTAGE
            - FIXED
            - PRICE
            - SHIPPING
            - FREE_PRODUCT
          example: PERCENTAGE
          type: string
        freeProductHandle:
          description: >-
            Product handle of a free product to add when discountType is
            FREE_PRODUCT
          example: free-gift-product
          type: string
        freeProductTitle:
          description: Display title of the free product when discountType is FREE_PRODUCT
          example: Ceramic Mug
          type: string
        freeVariantId:
          description: >-
            Variant ID of a free product to add when discountType is
            FREE_PRODUCT
          example: 42549172011164
          format: int64
          type: integer
        preventDuplicationFreeProduct:
          description: Prevent adding duplicate free products if already in cart
          example: true
          type: boolean
        repeatingCycle:
          description: Whether this pricing should repeat for subsequent cycles
          example: true
          type: boolean
        repeatingNumberOfCycle:
          description: >-
            Number of cycles to repeat this pricing for when repeatingCycle is
            true
          example: 6
          format: int32
          minimum: 1
          type: integer
        value:
          description: >-
            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
          format: double
          type: number
      type: object
    FixedBillingDate:
      properties:
        day:
          format: int32
          type: integer
        month:
          format: int32
          type: integer
      type: object

````