> ## 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 product swap variant groups for a contract

> Retrieves product swap variant groups for the next 10 billing cycles of a specific subscription contract. This endpoint calculates and returns which products will be swapped to in future billing cycles based on configured swap automations.

**Response Structure:**
Returns a 2D array (`List<List<VariantQuantity>>`):
- **Outer array**: Represents the next 10 billing cycles
- **Inner arrays**: Contains the variant(s) that will be swapped to for that specific cycle
- **Index 0**: Variants for the next (upcoming) billing cycle
- **Index 1**: Variants for the cycle after that
- And so on for the next 10 cycles

**Variant Details:**
Each variant object includes:
- **variantId**: Shopify variant ID
- **quantity**: Number of units to swap
- **title**: Variant title (e.g., "Medium Roast - 12oz")
- **image**: Product/variant image URL
- **productTitle**: Full product name
- **productId**: Shopify product GID
- **variantTitle**: Full display name combining product and variant titles
- **swapId**: ID of the swap automation rule that triggered this swap

**How It Works:**
1. Takes the current products in the subscription
2. Applies configured swap automations for the next 10 cycles
3. Calculates which products will be swapped based on:
   - Billing cycle number
   - Swap rule configurations (forBillingCycle, checkForEveryRecurringOrder)
   - Rule sequence/priority
4. Returns the projected product lineup for each cycle

**Use Cases:**
- Preview upcoming product swaps in customer portals
- Show customers their subscription product timeline
- Build interactive swap calendars
- Display "what you'll receive" for future orders
- Debug and verify swap automation configurations

**Important Notes:**
- Returns 10 cycles even if no swaps are configured (returns current products)
- Multiple variants in an inner array means multiple products will be in that order
- Empty inner arrays indicate no products for that cycle (rare edge case)
- The swapId can be used to trace which automation rule triggered the swap

**Authentication:** Requires valid X-API-Key header



## OpenAPI

````yaml /subscription/admin-api-swagger.json post /api/external/v2/product-swaps-by-variant-groups/{contractId}
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/product-swaps-by-variant-groups/{contractId}:
    post:
      tags:
        - Product Catalog
      summary: Get product swap variant groups for a contract
      description: >-
        Retrieves product swap variant groups for the next 10 billing cycles of
        a specific subscription contract. This endpoint calculates and returns
        which products will be swapped to in future billing cycles based on
        configured swap automations.


        **Response Structure:**

        Returns a 2D array (`List<List<VariantQuantity>>`):

        - **Outer array**: Represents the next 10 billing cycles

        - **Inner arrays**: Contains the variant(s) that will be swapped to for
        that specific cycle

        - **Index 0**: Variants for the next (upcoming) billing cycle

        - **Index 1**: Variants for the cycle after that

        - And so on for the next 10 cycles


        **Variant Details:**

        Each variant object includes:

        - **variantId**: Shopify variant ID

        - **quantity**: Number of units to swap

        - **title**: Variant title (e.g., "Medium Roast - 12oz")

        - **image**: Product/variant image URL

        - **productTitle**: Full product name

        - **productId**: Shopify product GID

        - **variantTitle**: Full display name combining product and variant
        titles

        - **swapId**: ID of the swap automation rule that triggered this swap


        **How It Works:**

        1. Takes the current products in the subscription

        2. Applies configured swap automations for the next 10 cycles

        3. Calculates which products will be swapped based on:
           - Billing cycle number
           - Swap rule configurations (forBillingCycle, checkForEveryRecurringOrder)
           - Rule sequence/priority
        4. Returns the projected product lineup for each cycle


        **Use Cases:**

        - Preview upcoming product swaps in customer portals

        - Show customers their subscription product timeline

        - Build interactive swap calendars

        - Display "what you'll receive" for future orders

        - Debug and verify swap automation configurations


        **Important Notes:**

        - Returns 10 cycles even if no swaps are configured (returns current
        products)

        - Multiple variants in an inner array means multiple products will be in
        that order

        - Empty inner arrays indicate no products for that cycle (rare edge
        case)

        - The swapId can be used to trace which automation rule triggered the
        swap


        **Authentication:** Requires valid X-API-Key header
      operationId: getProductSwapsByVariantIdV2
      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
        - in: path
          name: contractId
          required: true
          schema:
            format: int64
            type: integer
      requestBody:
        content:
          application/json:
            examples:
              Request Example:
                description: Request Example
                value:
                  variantQuantityList:
                    - quantity: 2
                      swapId: 1001
                      variantId: 12345
                    - quantity: 2
                      swapId: 1002
                      variantId: 67890
            schema:
              $ref: '#/components/schemas/VariantQuantityInfo'
        description: VariantQuantityInfo payload
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: >-
                    Array of arrays - outer array represents billing cycles,
                    inner arrays contain variants for that cycle
                  value:
                    - - image: >-
                          https://cdn.shopify.com/files/1/0000/0000/products/medium-roast.jpg
                        productId: gid://shopify/Product/98765
                        productTitle: House Blend Coffee
                        quantity: 2
                        swapId: 1001
                        title: Medium Roast - 12oz
                        variantId: 12345
                        variantTitle: House Blend Coffee - Medium Roast - 12oz
                      - image: >-
                          https://cdn.shopify.com/files/1/0000/0000/products/light-roast.jpg
                        productId: gid://shopify/Product/98766
                        productTitle: Morning Blend Coffee
                        quantity: 1
                        swapId: 1001
                        title: Light Roast - 8oz
                        variantId: 12346
                        variantTitle: Morning Blend Coffee - Light Roast - 8oz
                    - - image: >-
                          https://cdn.shopify.com/files/1/0000/0000/products/dark-roast.jpg
                        productId: gid://shopify/Product/88765
                        productTitle: Bold Blend Coffee
                        quantity: 2
                        swapId: 1002
                        title: Dark Roast - 12oz
                        variantId: 67890
                        variantTitle: Bold Blend Coffee - Dark Roast - 12oz
          description: >-
            Product swap variant groups returned successfully - Returns
            swappable variants for the next 10 billing cycles. Each element in
            the outer array represents the variants that will be swapped to for
            a specific billing cycle.
        '400':
          content:
            application/json:
              example:
                detail: Contract does not belong to this shop
                status: 400
                title: Invalid contract
                type: https://example.com/errors/bad-request
          description: Invalid contract ID or contract doesn't belong to authenticated shop
        '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
        '403':
          content:
            application/json:
              example:
                detail: API key does not have permission to view product swaps
                status: 403
                title: Insufficient permissions
                type: https://example.com/errors/forbidden
          description: Insufficient permissions to view product swaps
        '404':
          content:
            application/json:
              example:
                detail: No product swap variant groups available for this contract
                status: 404
                title: No swap groups found
                type: https://example.com/errors/not-found
          description: Contract not found or no swap groups available
components:
  schemas:
    VariantQuantityInfo:
      properties:
        variantQuantityList:
          items:
            $ref: '#/components/schemas/VariantQuantity'
          type: array
      type: object
    VariantQuantity:
      properties:
        image:
          type: string
        productId:
          type: string
        productTitle:
          type: string
        quantity:
          format: int32
          type: integer
        swapId:
          format: int64
          type: integer
        title:
          type: string
        variantId:
          format: int64
          type: integer
        variantTitle:
          type: string
      type: object

````