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. <details> <summary>**Full behavior, validation rules, and side effects**</summary> **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 </details>

POST /subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}

Get product swap variant groups for a contract

cURL

curl --request POST \
  --url https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "variantQuantityList": [
    {
      "variantId": 123,
      "quantity": 123,
      "title": "<string>",
      "image": "<string>",
      "productTitle": "<string>",
      "productId": "<string>",
      "variantTitle": "<string>",
      "swapId": 123
    }
  ]
}
'

200

[
  [
    {
      "variantId": 12345,
      "quantity": 2,
      "title": "Medium Roast - 12oz",
      "image": "https://cdn.shopify.com/files/1/0000/0000/products/medium-roast.jpg",
      "productTitle": "House Blend Coffee",
      "productId": "gid://shopify/Product/98765",
      "variantTitle": "House Blend Coffee - Medium Roast - 12oz",
      "swapId": 1001
    },
    {
      "variantId": 12346,
      "quantity": 1,
      "title": "Light Roast - 8oz",
      "image": "https://cdn.shopify.com/files/1/0000/0000/products/light-roast.jpg",
      "productTitle": "Morning Blend Coffee",
      "productId": "gid://shopify/Product/98766",
      "variantTitle": "Morning Blend Coffee - Light Roast - 8oz",
      "swapId": 1001
    }
  ],
  [
    {
      "variantId": 67890,
      "quantity": 2,
      "title": "Dark Roast - 12oz",
      "image": "https://cdn.shopify.com/files/1/0000/0000/products/dark-roast.jpg",
      "productTitle": "Bold Blend Coffee",
      "productId": "gid://shopify/Product/88765",
      "variantTitle": "Bold Blend Coffee - Dark Roast - 12oz",
      "swapId": 1002
    }
  ]
]

Path Parameters

contractId · integer<int64> · required

Body

application/json

variantQuantityList · object[]

Show child attributes

Response

200

application/json

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.