Product Swap Rules

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.

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:

Merchant configures swap rules defining which products can substitute others
Rules are organized by variant groups (e.g., coffee roasts, tea flavors)
Each rule specifies “from” variants and “to” variants
Rules can be limited to specific subscription frequencies or all orders
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

product-swaps-by-variant-groups

Get product swap options for subscription items

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

import requests

url = "https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups"

payload = { "variantQuantityList": [
        {
            "quantity": 2,
            "variantId": 123456
        },
        {
            "quantity": 1,
            "variantId": 789012
        }
    ] }
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: [{quantity: 2, variantId: 123456}, {quantity: 1, variantId: 789012}]
  })
};

fetch('https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [{quantity: 2, variantId: 123456}, {quantity: 1, variantId: 789012}]
  })
};

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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups",
  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' => [
        [
                'quantity' => 2,
                'variantId' => 123456
        ],
        [
                'quantity' => 1,
                'variantId' => 789012
        ]
    ]
  ]),
  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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups"

	payload := strings.NewReader("{\n  \"variantQuantityList\": [\n    {\n      \"quantity\": 2,\n      \"variantId\": 123456\n    },\n    {\n      \"quantity\": 1,\n      \"variantId\": 789012\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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups")

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      \"quantity\": 2,\n      \"variantId\": 123456\n    },\n    {\n      \"quantity\": 1,\n      \"variantId\": 789012\n    }\n  ]\n}"

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

"<array>"

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

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

Swap options successfully retrieved with up to 5 levels of suggestions

Get product swap options for subscription items

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

import requests

url = "https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups"

payload = { "variantQuantityList": [
        {
            "quantity": 2,
            "variantId": 123456
        },
        {
            "quantity": 1,
            "variantId": 789012
        }
    ] }
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: [{quantity: 2, variantId: 123456}, {quantity: 1, variantId: 789012}]
  })
};

fetch('https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantQuantityList: [{quantity: 2, variantId: 123456}, {quantity: 1, variantId: 789012}]
  })
};

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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups",
  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' => [
        [
                'quantity' => 2,
                'variantId' => 123456
        ],
        [
                'quantity' => 1,
                'variantId' => 789012
        ]
    ]
  ]),
  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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups"

	payload := strings.NewReader("{\n  \"variantQuantityList\": [\n    {\n      \"quantity\": 2,\n      \"variantId\": 123456\n    },\n    {\n      \"quantity\": 1,\n      \"variantId\": 789012\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://membership-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups")

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      \"quantity\": 2,\n      \"variantId\": 123456\n    },\n    {\n      \"quantity\": 1,\n      \"variantId\": 789012\n    }\n  ]\n}"

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

"<array>"

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

[
  [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
]

Get Started

Guides

Partner Integration

Webhooks

Admin API

Customer Portal API

Get product swap options for subscription items

Headers

Query Parameters

Body

Response