> ## 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>`): - **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/storefront-api-swagger.json post /subscriptions/cp/api/product-swaps-by-variant-groups/{contractId} openapi: 3.0.1 info: description: >- Comprehensive API documentation for the customer-facing subscription portal. These APIs enable customers to manage their subscriptions, update billing information, modify delivery schedules, and access their account details through your storefront. **Important**: These APIs must be called from your shop's domain (e.g., https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error. title: Storefront APIs version: 0.0.1 servers: - url: https://www.myshop.com/apps security: [] tags: - description: >- Core customer portal APIs for managing customer account settings, authentication, and portal configurations. name: Customer Portal - description: >- APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations. name: Subscription Management - description: >- APIs for retrieving and updating subscription contract details — delivery schedules, line items, addresses, billing cycles. name: Subscription Contracts - description: >- APIs for retrieving available subscription plans and selling plan configurations exposed to customers. name: Subscription Plans - 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 retrieving aggregated subscription data and account-level subscription information for the signed-in customer. name: Subscription Data - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing payment methods, billing information, and processing subscription payments. name: Billing & Payments - description: >- APIs for retrieving product information, selling plans, variant data, and subscription-enabled products available to customers. name: Product Catalog - description: >- APIs for managing delivery schedules, shipping addresses, delivery methods, and tracking order status. name: Delivery & Shipping - description: >- APIs for handling subscription cancellations, retention activities, and customer feedback management. name: Customer Retention - description: >- APIs for integrating loyalty programs with subscriptions including points redemption and earning options. name: Loyalty Integration - description: >- APIs for accessing portal customization settings, translations, and theme configurations. name: Customization - description: >- APIs for retrieving promotional campaigns shown in the customer portal, tracking banner engagement, and redeeming campaign offers. name: Campaigns - description: >- APIs for local pickup and click-and-collect — listing pickup locations and resolving eligible pickup dates and time slots. name: Store Pickup paths: /subscriptions/cp/api/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>`): - **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: getProductSwapsByVariantId parameters: - in: path name: contractId required: true schema: format: int64 type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/VariantQuantityInfo' 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 ````