Skip to main content
POST
/
subscriptions
/
cp
/
api
/
subscription-contract-details
/
replace-variants-v3
Replace product variants in a subscription contract
curl --request POST \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3 \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractId": 123456789,
  "shop": "abcStore.myshopify.com"
}
'
import requests

url = "https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3"

payload = {
"contractId": 123456789,
"shop": "abcStore.myshopify.com"
}
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({contractId: 123456789, shop: 'abcStore.myshopify.com'})
};

fetch('https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3', 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/subscription-contract-details/replace-variants-v3';
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({contractId: 123456789, shop: 'abcStore.myshopify.com'})
};

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/subscription-contract-details/replace-variants-v3",
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([
'contractId' => 123456789,
'shop' => 'abcStore.myshopify.com'
]),
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/subscription-contract-details/replace-variants-v3"

payload := strings.NewReader("{\n \"contractId\": 123456789,\n \"shop\": \"abcStore.myshopify.com\"\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/subscription-contract-details/replace-variants-v3")

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 \"contractId\": 123456789,\n \"shop\": \"abcStore.myshopify.com\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "35.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/999999",
          "pricingPolicy": {
            "basePrice": {
              "amount": "39.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                },
                "afterCycle": 1
              }
            ]
          },
          "quantity": 3,
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/888888",
          "variantTitle": "1kg / Whole Bean"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "9.99",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_one_time_product",
              "value": "true"
            }
          ],
          "id": "gid://shopify/SubscriptionLine/777777",
          "quantity": 1,
          "title": "Coffee Filters - Pack of 100",
          "variantId": "gid://shopify/ProductVariant/666666"
        }
      }
    ]
  },
  "nextBillingDate": "2024-02-15T00:00:00Z",
  "status": "ACTIVE"
}

Body

application/json

Product replacement configuration for subscription contracts. Allows replacing existing subscription products with new ones, managing quantities, and handling one-time purchases.

contractId
integer<int64>
required

The ID of the subscription contract to modify

Example:

123456789

shop
string
required

The Shop of the subscription contract to modify

Example:

"abcStore.myshopify.com"

babParentVariantId
integer<int64>

When set, this is treated as a fixed-price Build-a-Box child swap: the numeric variant ID of the parent bundle line whose child products will be replaced. When present, babReplaceSubVariantDetails is applied instead of the line-item variant swap.

Example:

42549172011164

babReplaceSubVariantDetails
object[]

Old-to-new child variant mappings applied to the parent bundle line's child products when babParentVariantId is set.

babRequireAllSourceVariants
boolean
default:false

When true and babParentVariantId is set, a bundle line is only updated when every oldVariantId from babReplaceSubVariantDetails is present in the box. Default is false (each old-to-new mapping applies independently).

Example:

false

carryForwardDiscount
enum<string>

Determines how discounts are applied to new products when replacing variants. If not specified, uses the merchant's default setting.

Available options:
NONE,
EXISTING_PLAN,
PRODUCT_PLAN,
PRODUCT_THEN_EXISTING,
PRODUCT_THEN_EXISTING,
PRODUCT_PLAN,
EXISTING_PLAN
Example:

"PRODUCT_THEN_EXISTING"

eventSource
enum<string>
Available options:
CUSTOMER_PORTAL,
MERCHANT_PORTAL,
SHOPIFY_EVENT,
SYSTEM_EVENT,
MERCHANT_PORTAL_BULK_AUTOMATION,
SCHEDULED_BULK_AUTOMATION,
MERCHANT_EXTERNAL_API,
SHOPIFY_FLOW
newOneTimeVariants
object

Map of one-time product variant IDs to add with their quantities. These products will be charged only once with the next order and won't recur. Useful for add-ons, samples, or limited-time offers.

Example:
{ "42549172066666": 1, "42549172077777": 2 }
newVariants
object

Map of new variant IDs to their quantities. Key is the numeric Shopify variant ID, value is the desired quantity. If a variant already exists in the subscription and the system is configured to update existing quantities, the quantity will be added to the existing quantity.

Example:
{ "42549172033333": 2, "42549172044444": 1 }
oldLineId
string

Specific subscription line ID to replace. Use this for targeted replacement of a single line item. When provided, oldVariants should be empty. Format: gid://shopify/SubscriptionLine/[ID]

Example:

"gid://shopify/SubscriptionLine/987654321"

oldOneTimeVariants
integer<int64>[]

List of one-time product variant IDs to remove from the subscription. Only removes one-time products that haven't been fulfilled yet.

List of one-time product variant IDs to remove from the subscription. Only removes one-time products that haven't been fulfilled yet.

Example:
[42549172055555, 42549172088888]
oldVariants
integer<int64>[]

List of variant IDs to remove from the subscription. These are numeric Shopify variant IDs. Either provide oldVariants OR oldLineId, not both.

List of variant IDs to remove from the subscription. These are numeric Shopify variant IDs. Either provide oldVariants OR oldLineId, not both.

Example:
[42549172011164, 42549172022222]
stopSwapEmails
boolean
default:false

If true, suppresses email notifications about the product swap. Default is false (emails will be sent).

Example:

false

Response

Products successfully replaced

billingAttempts
object
billingPolicy
object
createdAt
object
customAttributes
object[]
customer
object
customerPaymentMethod
object
deliveryMethod
object
deliveryPolicy
object
deliveryPrice
object
discounts
object
get__typename
string
id
string
lastPaymentStatus
enum<string>
Available options:
SUCCEEDED,
FAILED,
$UNKNOWN
lines
object
nextBillingDate
object
note
string
originOrder
object
status
enum<string>
Available options:
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED,
$UNKNOWN
updatedAt
object