Get product swap options for subscription items

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.

Full behavior, validation rules, and side effects

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

POST /api/external/v2/product-swaps-by-variant-groups

Get product swap options for subscription items

cURL

curl --request POST \
  --url https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "variantQuantityList": [
    {
      "variantId": 123456,
      "quantity": 2
    },
    {
      "variantId": 789012,
      "quantity": 1
    }
  ]
}
'

200

"<array>"

Headers

X-API-Key · string

API Key for authentication (Preferred method - use this instead of api_key parameter)

Query Parameters

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

Body

application/json

List of variants with quantities to find swap options for

variantQuantityList · object[]

Show child attributes

Response

200

application/json

Swap options successfully retrieved with up to 5 levels of suggestions