Replaces existing product variants with new ones in a subscription contract. This endpoint supports both regular subscription products and one-time products, allowing you to swap products, update quantities, and manage the product mix in a subscription.
Key Features:
Discount Carry Forward Options:
Important Notes:
Use Cases:
Authentication: Requires valid X-API-Key header
curl --request POST \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3 \
--header 'Content-Type: application/json' \
--data '
{
"shop": "abcStore.myshopify.com",
"contractId": 123456789
}
'{
"id": "gid://shopify/SubscriptionContract/123456789",
"status": "ACTIVE",
"nextBillingDate": "2024-02-15T00:00:00Z",
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/999999",
"quantity": 3,
"variantId": "gid://shopify/ProductVariant/888888",
"title": "Premium Coffee - Dark Roast",
"variantTitle": "1kg / Whole Bean",
"currentPrice": {
"amount": "35.99",
"currencyCode": "USD"
},
"pricingPolicy": {
"basePrice": {
"amount": "39.99",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"afterCycle": 1,
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 10
}
}
]
}
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/777777",
"quantity": 1,
"variantId": "gid://shopify/ProductVariant/666666",
"title": "Coffee Filters - Pack of 100",
"currentPrice": {
"amount": "9.99",
"currencyCode": "USD"
},
"customAttributes": [
{
"key": "_one_time_product",
"value": "true"
}
]
}
}
]
}
}Documentation Index
Fetch the complete documentation index at: https://appstleinc-aeca3e0a.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Product replacement configuration for subscription contracts. Allows replacing existing subscription products with new ones, managing quantities, and handling one-time purchases.
The Shop of the subscription contract to modify
"abcStore.myshopify.com"
The ID of the subscription contract to modify
123456789
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.
[42549172011164, 42549172022222]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.
Show child attributes
{ "42549172033333": 2, "42549172044444": 1 }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.
Show child attributes
{ "42549172066666": 1, "42549172077777": 2 }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.
[42549172055555, 42549172088888]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]
"gid://shopify/SubscriptionLine/987654321"
CUSTOMER_PORTAL, MERCHANT_PORTAL, SHOPIFY_EVENT, SYSTEM_EVENT, MERCHANT_PORTAL_BULK_AUTOMATION, MERCHANT_EXTERNAL_API, SHOPIFY_FLOW Determines how discounts are applied to new products when replacing variants. If not specified, uses the merchant's default setting.
NONE, EXISTING_PLAN, PRODUCT_PLAN, PRODUCT_THEN_EXISTING, PRODUCT_THEN_EXISTING, PRODUCT_PLAN, EXISTING_PLAN "PRODUCT_THEN_EXISTING"
If true, suppresses email notifications about the product swap. Default is false (emails will be sent).
false
Products successfully replaced
ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN Show child attributes
SUCCEEDED, FAILED, $UNKNOWN Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
curl --request POST \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3 \
--header 'Content-Type: application/json' \
--data '
{
"shop": "abcStore.myshopify.com",
"contractId": 123456789
}
'{
"id": "gid://shopify/SubscriptionContract/123456789",
"status": "ACTIVE",
"nextBillingDate": "2024-02-15T00:00:00Z",
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/999999",
"quantity": 3,
"variantId": "gid://shopify/ProductVariant/888888",
"title": "Premium Coffee - Dark Roast",
"variantTitle": "1kg / Whole Bean",
"currentPrice": {
"amount": "35.99",
"currencyCode": "USD"
},
"pricingPolicy": {
"basePrice": {
"amount": "39.99",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"afterCycle": 1,
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 10
}
}
]
}
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/777777",
"quantity": 1,
"variantId": "gid://shopify/ProductVariant/666666",
"title": "Coffee Filters - Pack of 100",
"currentPrice": {
"amount": "9.99",
"currencyCode": "USD"
},
"customAttributes": [
{
"key": "_one_time_product",
"value": "true"
}
]
}
}
]
}
}