> ## 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 all product swaps for a shop

> Retrieves all configured product swap automations for the authenticated shop. Product swaps allow automatic replacement of products in subscription orders based on billing cycles or recurring schedules.

**What are Product Swaps?**
Product swaps enable merchants to automatically replace products in subscription orders at specific billing cycles. This is useful for seasonal products, progression paths (e.g., beginner → intermediate → advanced), or variety subscriptions.

**Key Features:**
- View all configured swap automations
- See source and destination product mappings
- Check which billing cycles trigger swaps
- Identify recurring vs one-time swaps
- Review discount carry-forward settings

**Swap Configuration Types:**
- **One-Time Swap**: Occurs at a specific billing cycle
- **Recurring Swap**: Occurs at every order
- **Conditional Swap**: Based on billing cycle number

**Use Cases:**
- Seasonal product rotations (summer → fall → winter products)
- Subscription progression (trial → full product)
- Variety boxes with automatic product rotation
- Product lifecycle management in subscriptions
- A/B testing different products in subscriptions

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



## OpenAPI

````yaml /subscription/admin-api-swagger.json get /api/external/v2/product-swaps
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:
    get:
      tags:
        - Product Catalog
      summary: Get all product swaps for a shop
      description: >-
        Retrieves all configured product swap automations for the authenticated
        shop. Product swaps allow automatic replacement of products in
        subscription orders based on billing cycles or recurring schedules.


        **What are Product Swaps?**

        Product swaps enable merchants to automatically replace products in
        subscription orders at specific billing cycles. This is useful for
        seasonal products, progression paths (e.g., beginner → intermediate →
        advanced), or variety subscriptions.


        **Key Features:**

        - View all configured swap automations

        - See source and destination product mappings

        - Check which billing cycles trigger swaps

        - Identify recurring vs one-time swaps

        - Review discount carry-forward settings


        **Swap Configuration Types:**

        - **One-Time Swap**: Occurs at a specific billing cycle

        - **Recurring Swap**: Occurs at every order

        - **Conditional Swap**: Based on billing cycle number


        **Use Cases:**

        - Seasonal product rotations (summer → fall → winter products)

        - Subscription progression (trial → full product)

        - Variety boxes with automatic product rotation

        - Product lifecycle management in subscriptions

        - A/B testing different products in subscriptions


        **Authentication:** Requires valid X-API-Key header
      operationId: getAllProductSwaps
      parameters:
        - in: header
          name: X-API-Key
          required: false
          schema:
            type: string
        - in: query
          name: ruleName
          required: false
          schema:
            type: string
        - in: query
          name: sourceVariants
          required: false
          schema:
            type: string
        - in: query
          name: destinationVariants
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    - active: true
                      carryDiscountForward: true
                      checkForEveryRecurringOrder: false
                      createdAt: '2024-01-15T10:30:00Z'
                      destinationVariants: >-
                        [{"id":67890,"displayName":"Fall Blend
                        Coffee","imageSrc":"https://cdn.shopify.com/image2.jpg","quantity":2}]
                      discountCarryForward: PERCENTAGE
                      forBillingCycle: 4
                      id: 10782
                      name: Seasonal Coffee Rotation
                      shop: example-shop.myshopify.com
                      sourceVariants: >-
                        [{"id":12345,"displayName":"Summer Blend
                        Coffee","imageSrc":"https://cdn.shopify.com/image1.jpg","quantity":2}]
                      stopSwapEmails: false
                      updatedFirstOrder: false
                    - active: true
                      carryDiscountForward: false
                      checkForEveryRecurringOrder: true
                      destinationVariants: >-
                        [{"id":33333,"displayName":"Advanced
                        Kit","imageSrc":"https://cdn.shopify.com/kit2.jpg","quantity":1}]
                      discountCarryForward: NONE
                      forBillingCycle: null
                      id: 10783
                      name: Monthly Variety Swap
                      shop: example-shop.myshopify.com
                      sourceVariants: >-
                        [{"id":22222,"displayName":"Beginner
                        Kit","imageSrc":"https://cdn.shopify.com/kit1.jpg","quantity":1}]
                      stopSwapEmails: true
                      updatedFirstOrder: false
              schema:
                $ref: '#/components/schemas/ProductSwapDTO'
          description: Successfully retrieved product swaps
        '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
components:
  schemas:
    ProductSwapDTO:
      properties:
        carryDiscountForward:
          type: boolean
        changeNextOrderDateBy:
          format: int32
          type: integer
        checkForEveryRecurringOrder:
          type: boolean
        destinationVariants:
          type: string
        discountCarryForward:
          enum:
            - NONE
            - EXISTING_PLAN
            - PRODUCT_PLAN
            - PRODUCT_THEN_EXISTING
          type: string
        forBillingCycle:
          format: int32
          type: integer
        id:
          format: int64
          type: integer
        name:
          type: string
        ruleSequence:
          format: int32
          type: integer
        shop:
          type: string
        sourceVariants:
          type: string
        stopSwapEmails:
          type: boolean
        updatedFirstOrder:
          type: boolean
      required:
        - shop
      type: object

````