# Product Swap Rules

APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups

## Get product swap options for subscription items

 - [POST /api/external/v2/product-swaps-by-variant-groups](https://developers.membership.appstle.com/admin-api-swagger/product-swap-rules/getproductswapsbyvariantidv2.md): Retrieves available product swap/substitution options for specified variants based on configured swap rules. Returns multiple levels of swap suggestions allowing members to exchange products in their subscriptions.

Key Features:
- Variant-Based Swaps: Get swap options for specific product variants
- Multi-Level Suggestions: Returns up to 4 levels of swap alternatives
- Quantity Preservation: Maintains quantities when suggesting swaps
- Recurring Order Rules: Only returns swaps configured for every recurring order
- Group-Based Matching: Uses variant groups to find compatible swaps
- Product Enrichment: Includes product details (title, price, images)

How Swap Rules Work:
1. Merchant configures swap rules defining which products can substitute others
2. Rules are organized by variant groups (e.g., coffee roasts, tea flavors)
3. Each rule specifies "from" variants and "to" variants
4. Rules can be limited to specific subscription frequencies or all orders
5. Members can swap products within the allowed groups

Request Structure:
- Variant Quantity List: Array of variant IDs with quantities
- Each entry contains variant ID and quantity
- System finds swap options for all provided variants

Response Structure:
- Returns nested list of swap options (up to 5 levels)
- Level 0: Original variants (as provided in request)
- Levels 1-4: Progressive swap suggestions
- Each level contains variant IDs, quantities, titles, prices, images
- Variants appear with full Shopify product data

Use Cases:
- Display product swap options in customer portal
- Allow members to switch between flavor/size variants
- Build custom product selection interfaces
- Enable seasonal product swaps (summer/winter varieties)
- Offer alternative products when items are out of stock
- Let members customize subscriptions within allowed product groups

Example Scenario:
Member has "Dark Roast Coffee (12oz)" in subscription. API returns:
- Level 0: Dark Roast Coffee 12oz (original)
- Level 1: Medium Roast Coffee 12oz, Light Roast Coffee 12oz
- Level 2: Dark Roast Coffee 16oz, Decaf Dark Roast 12oz
- Level 3: Espresso Blend 12oz, French Roast 12oz
- Level 4: Additional variants based on swap rules

Authentication: Requires API key authentication via X-API-Key header or api_key parameter