Product Catalog

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<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:

Takes the current products in the subscription
Applies configured swap automations for the next 10 cycles
Calculates which products will be swapped based on:
- Billing cycle number
- Swap rule configurations (forBillingCycle, checkForEveryRecurringOrder)
- Rule sequence/priority
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

POST

subscriptions

api

product-swaps-by-variant-groups

{contractId}

Get product swap variant groups for a contract

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": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "swapId": 123,
      "title": "<string>",
      "variantId": 123,
      "variantTitle": "<string>"
    }
  ]
}
'

import requests

url = "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}"

payload = { "variantQuantityList": [
        {
            "image": "<string>",
            "productId": "<string>",
            "productTitle": "<string>",
            "quantity": 123,
            "swapId": 123,
            "title": "<string>",
            "variantId": 123,
            "variantTitle": "<string>"
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [
      {
        image: '<string>',
        productId: '<string>',
        productTitle: '<string>',
        quantity: 123,
        swapId: 123,
        title: '<string>',
        variantId: 123,
        variantTitle: '<string>'
      }
    ]
  })
};

fetch('https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [
      {
        image: '<string>',
        productId: '<string>',
        productTitle: '<string>',
        quantity: 123,
        swapId: 123,
        title: '<string>',
        variantId: 123,
        variantTitle: '<string>'
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variantQuantityList' => [
        [
                'image' => '<string>',
                'productId' => '<string>',
                'productTitle' => '<string>',
                'quantity' => 123,
                'swapId' => 123,
                'title' => '<string>',
                'variantId' => 123,
                'variantTitle' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}"

	payload := strings.NewReader("{\n  \"variantQuantityList\": [\n    {\n      \"image\": \"<string>\",\n      \"productId\": \"<string>\",\n      \"productTitle\": \"<string>\",\n      \"quantity\": 123,\n      \"swapId\": 123,\n      \"title\": \"<string>\",\n      \"variantId\": 123,\n      \"variantTitle\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variantQuantityList\": [\n    {\n      \"image\": \"<string>\",\n      \"productId\": \"<string>\",\n      \"productTitle\": \"<string>\",\n      \"quantity\": 123,\n      \"swapId\": 123,\n      \"title\": \"<string>\",\n      \"variantId\": 123,\n      \"variantTitle\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

[
  [
    {
      "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"
    }
  ]
]

{
  "detail": "Contract does not belong to this shop",
  "status": 400,
  "title": "Invalid contract",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "detail": "API key does not have permission to view product swaps",
  "status": 403,
  "title": "Insufficient permissions",
  "type": "https://example.com/errors/forbidden"
}

{
  "detail": "No product swap variant groups available for this contract",
  "status": 404,
  "title": "No swap groups found",
  "type": "https://example.com/errors/not-found"
}

Path Parameters

contractId

integer<int64>

required

Body

application/json

variantQuantityList

object[]

Show child attributes

Response

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.

Get product swap variant groups for a contract

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": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "swapId": 123,
      "title": "<string>",
      "variantId": 123,
      "variantTitle": "<string>"
    }
  ]
}
'

import requests

url = "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}"

payload = { "variantQuantityList": [
        {
            "image": "<string>",
            "productId": "<string>",
            "productTitle": "<string>",
            "quantity": 123,
            "swapId": 123,
            "title": "<string>",
            "variantId": 123,
            "variantTitle": "<string>"
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [
      {
        image: '<string>',
        productId: '<string>',
        productTitle: '<string>',
        quantity: 123,
        swapId: 123,
        title: '<string>',
        variantId: 123,
        variantTitle: '<string>'
      }
    ]
  })
};

fetch('https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [
      {
        image: '<string>',
        productId: '<string>',
        productTitle: '<string>',
        quantity: 123,
        swapId: 123,
        title: '<string>',
        variantId: 123,
        variantTitle: '<string>'
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variantQuantityList' => [
        [
                'image' => '<string>',
                'productId' => '<string>',
                'productTitle' => '<string>',
                'quantity' => 123,
                'swapId' => 123,
                'title' => '<string>',
                'variantId' => 123,
                'variantTitle' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}"

	payload := strings.NewReader("{\n  \"variantQuantityList\": [\n    {\n      \"image\": \"<string>\",\n      \"productId\": \"<string>\",\n      \"productTitle\": \"<string>\",\n      \"quantity\": 123,\n      \"swapId\": 123,\n      \"title\": \"<string>\",\n      \"variantId\": 123,\n      \"variantTitle\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variantQuantityList\": [\n    {\n      \"image\": \"<string>\",\n      \"productId\": \"<string>\",\n      \"productTitle\": \"<string>\",\n      \"quantity\": 123,\n      \"swapId\": 123,\n      \"title\": \"<string>\",\n      \"variantId\": 123,\n      \"variantTitle\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

[
  [
    {
      "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"
    }
  ]
]

{
  "detail": "Contract does not belong to this shop",
  "status": 400,
  "title": "Invalid contract",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "detail": "API key does not have permission to view product swaps",
  "status": 403,
  "title": "Insufficient permissions",
  "type": "https://example.com/errors/forbidden"
}

{
  "detail": "No product swap variant groups available for this contract",
  "status": 404,
  "title": "No swap groups found",
  "type": "https://example.com/errors/not-found"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Get product swap variant groups for a contract

Path Parameters

Body

Response