# Replace product variants in a subscription contract 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: - Bulk Replace: Replace multiple products at once by providing lists of old and new variants - Line-Specific Replace: Target a specific line item using oldLineId for precise replacement - Quantity Management: Set new quantities for replaced products - One-Time Products: Add or remove one-time purchase products independently - Discount Preservation: Configurable discount carry-forward logic Discount Carry Forward Options: - PRODUCT_THEN_EXISTING: First tries to apply the new product's selling plan discount, then falls back to existing discount - PRODUCT_PLAN: Always uses the new product's selling plan discount - EXISTING_PLAN: Maintains the existing product's discount structure Important Notes: - At least one regular subscription product must remain in the contract - One-time products and free products don't count towards the minimum product requirement - The system automatically handles pricing adjustments based on billing/delivery intervals - Shipping prices are automatically recalculated after changes Use Cases: - Product upgrades/downgrades (e.g., switching coffee blend or size) - Quantity adjustments during product swap - Adding limited-time or seasonal products as one-time purchases - Bulk product replacements for subscription migrations Authentication: Requires valid X-API-Key header Endpoint: POST /subscriptions/cp/api/subscription-contract-details/replace-variants-v3 Version: 0.0.1 ## Request fields (application/json): - `shop` (string, required) The Shop of the subscription contract to modify Example: "abcStore.myshopify.com" - `contractId` (integer, required) The ID of the subscription contract to modify Example: 123456789 - `oldVariants` (array) 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] - `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} - `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} - `oldOneTimeVariants` (array) 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] - `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" - `eventSource` (string) Enum: "CUSTOMER_PORTAL", "MERCHANT_PORTAL", "SHOPIFY_EVENT", "SYSTEM_EVENT", "MERCHANT_PORTAL_BULK_AUTOMATION", "MERCHANT_EXTERNAL_API", "SHOPIFY_FLOW" - `carryForwardDiscount` (string) Determines how discounts are applied to new products when replacing variants. If not specified, uses the merchant's default setting. Enum: "NONE", "EXISTING_PLAN", "PRODUCT_PLAN", "PRODUCT_THEN_EXISTING", "PRODUCT_THEN_EXISTING", "PRODUCT_PLAN", "EXISTING_PLAN" - `stopSwapEmails` (boolean) If true, suppresses email notifications about the product swap. Default is false (emails will be sent). ## Response 200 fields (application/json): - `get__typename` (string) - `id` (string) - `createdAt` (object) - `updatedAt` (object) - `nextBillingDate` (object) - `status` (string) Enum: "ACTIVE", "PAUSED", "CANCELLED", "EXPIRED", "FAILED", "$UNKNOWN" - `deliveryPrice` (object) - `deliveryPrice.amount` (object) - `deliveryPrice.currencyCode` (string) Enum: "USD", "EUR", "GBP", "CAD", "AFN", "ALL", "DZD", "AOA", "ARS", "AMD", "AWG", "AUD", "BBD", "AZN", "BDT", "BSD", "BHD", "BIF", "BYN", "BZD", "BMD", "BTN", "BAM", "BRL", "BOB", "BWP", "BND", "BGN", "MMK", "KHR", "CVE", "KYD", "XAF", "CLP", "CNY", "COP", "KMF", "CDF", "CRC", "HRK", "CZK", "DKK", "DJF", "DOP", "XCD", "EGP", "ERN", "ETB", "FKP", "XPF", "FJD", "GIP", "GMD", "GHS", "GTQ", "GYD", "GEL", "GNF", "HTG", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "ILS", "IRR", "IQD", "JMD", "JPY", "JEP", "JOD", "KZT", "KES", "KID", "KWD", "KGS", "LAK", "LVL", "LBP", "LSL", "LRD", "LYD", "LTL", "MGA", "MKD", "MOP", "MWK", "MVR", "MRU", "MXN", "MYR", "MUR", "MDL", "MAD", "MNT", "MZN", "NAD", "NPR", "ANG", "NZD", "NIO", "NGN", "NOK", "OMR", "PAB", "PKR", "PGK", "PYG", "PEN", "PHP", "PLN", "QAR", "RON", "RUB", "RWF", "WST", "SHP", "SAR", "RSD", "SCR", "SLL", "SGD", "SDG", "SOS", "SYP", "ZAR", "KRW", "SSP", "SBD", "LKR", "SRD", "SZL", "SEK", "CHF", "TWD", "THB", "TJS", "TZS", "TOP", "TTD", "TND", "TRY", "TMT", "UGX", "UAH", "AED", "UYU", "UZS", "VUV", "VES", "VND", "XOF", "YER", "ZMW", "USDC", "BYR", "STD", "STN", "VED", "VEF", "XXX", "$UNKNOWN" - `lastPaymentStatus` (string) Enum: "SUCCEEDED", "FAILED", "$UNKNOWN" - `billingPolicy` (object) - `billingPolicy.interval` (string) Enum: "DAY", "WEEK", "MONTH", "YEAR", "$UNKNOWN" - `billingPolicy.intervalCount` (integer) - `billingPolicy.anchors` (array) - `billingPolicy.anchors.cutoffDay` (integer) - `billingPolicy.anchors.day` (integer) - `billingPolicy.anchors.month` (integer) - `billingPolicy.anchors.type` (string) Enum: "WEEKDAY", "MONTHDAY", "YEARDAY", "$UNKNOWN" - `billingPolicy.maxCycles` (integer) - `billingPolicy.minCycles` (integer) - `deliveryPolicy` (object) - `lines` (object) - `lines.nodes` (array) - `lines.nodes.sellingPlanId` (string) - `lines.nodes.sellingPlanName` (string) - `lines.nodes.productId` (string) - `lines.nodes.sku` (string) - `lines.nodes.title` (string) - `lines.nodes.variantId` (string) - `lines.nodes.quantity` (integer) - `lines.nodes.customAttributes` (array) - `lines.nodes.customAttributes.key` (string) - `lines.nodes.customAttributes.value` (string) - `lines.nodes.lineDiscountedPrice` (object) - `lines.nodes.variantImage` (object) - `lines.nodes.variantImage.transformedSrc` (object) - `lines.nodes.variantTitle` (string) - `lines.nodes.currentPrice` (object) - `lines.nodes.discountAllocations` (array) - `lines.nodes.discountAllocations.discount` (object) - `lines.nodes.pricingPolicy` (object) - `lines.nodes.pricingPolicy.basePrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts` (array) - `lines.nodes.pricingPolicy.cycleDiscounts.afterCycle` (integer) - `lines.nodes.pricingPolicy.cycleDiscounts.computedPrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentType` (string) Enum: "PERCENTAGE", "FIXED_AMOUNT", "PRICE", "$UNKNOWN" - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentValue` (object) - `lines.nodes.taxable` (boolean) - `lines.pageInfo` (object) - `lines.pageInfo.hasPreviousPage` (boolean) - `lines.pageInfo.hasNextPage` (boolean) - `lines.pageInfo.startCursor` (string) - `lines.pageInfo.endCursor` (string) - `customerPaymentMethod` (object) - `customerPaymentMethod.instrument` (object) - `customerPaymentMethod.revokedAt` (object) - `customerPaymentMethod.revokedReason` (string) Enum: "AUTHORIZE_NET_GATEWAY_NOT_ENABLED", "AUTHORIZE_NET_RETURNED_NO_PAYMENT_METHOD", "FAILED_TO_UPDATE_CREDIT_CARD", "STRIPE_API_AUTHENTICATION_ERROR", "STRIPE_API_INVALID_REQUEST_ERROR", "STRIPE_GATEWAY_NOT_ENABLED", "STRIPE_RETURNED_NO_PAYMENT_METHOD", "STRIPE_PAYMENT_METHOD_NOT_CARD", "BRAINTREE_API_AUTHENTICATION_ERROR", "BRAINTREE_GATEWAY_NOT_ENABLED", "BRAINTREE_RETURNED_NO_PAYMENT_METHOD", "BRAINTREE_PAYMENT_METHOD_NOT_CARD", "PAYMENT_METHOD_VERIFICATION_FAILED", "THREE_D_SECURE_FLOW_IN_VERIFICATION_NOT_IMPLEMENTED", "MANUALLY_REVOKED", "FAILED_TO_RETRIEVE_BILLING_ADDRESS", "MERGED", "CUSTOMER_REDACTED", "TOO_MANY_CONSECUTIVE_FAILURES", "CVV_ATTEMPTS_LIMIT_EXCEEDED", "$UNKNOWN" - `deliveryMethod` (object) - `originOrder` (object) - `originOrder.name` (string) - `originOrder.fulfillmentOrders` (object) - `customer` (object) - `customer.displayName` (string) - `customer.firstName` (string) - `customer.lastName` (string) - `customer.email` (string) - `customer.phone` (string) - `discounts` (object) - `note` (string) - `billingAttempts` (object) ## Response 401 fields (*/*): - `get__typename` (string) - `id` (string) - `createdAt` (object) - `updatedAt` (object) - `nextBillingDate` (object) - `status` (string) Enum: "ACTIVE", "PAUSED", "CANCELLED", "EXPIRED", "FAILED", "$UNKNOWN" - `deliveryPrice` (object) - `deliveryPrice.amount` (object) - `deliveryPrice.currencyCode` (string) Enum: "USD", "EUR", "GBP", "CAD", "AFN", "ALL", "DZD", "AOA", "ARS", "AMD", "AWG", "AUD", "BBD", "AZN", "BDT", "BSD", "BHD", "BIF", "BYN", "BZD", "BMD", "BTN", "BAM", "BRL", "BOB", "BWP", "BND", "BGN", "MMK", "KHR", "CVE", "KYD", "XAF", "CLP", "CNY", "COP", "KMF", "CDF", "CRC", "HRK", "CZK", "DKK", "DJF", "DOP", "XCD", "EGP", "ERN", "ETB", "FKP", "XPF", "FJD", "GIP", "GMD", "GHS", "GTQ", "GYD", "GEL", "GNF", "HTG", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "ILS", "IRR", "IQD", "JMD", "JPY", "JEP", "JOD", "KZT", "KES", "KID", "KWD", "KGS", "LAK", "LVL", "LBP", "LSL", "LRD", "LYD", "LTL", "MGA", "MKD", "MOP", "MWK", "MVR", "MRU", "MXN", "MYR", "MUR", "MDL", "MAD", "MNT", "MZN", "NAD", "NPR", "ANG", "NZD", "NIO", "NGN", "NOK", "OMR", "PAB", "PKR", "PGK", "PYG", "PEN", "PHP", "PLN", "QAR", "RON", "RUB", "RWF", "WST", "SHP", "SAR", "RSD", "SCR", "SLL", "SGD", "SDG", "SOS", "SYP", "ZAR", "KRW", "SSP", "SBD", "LKR", "SRD", "SZL", "SEK", "CHF", "TWD", "THB", "TJS", "TZS", "TOP", "TTD", "TND", "TRY", "TMT", "UGX", "UAH", "AED", "UYU", "UZS", "VUV", "VES", "VND", "XOF", "YER", "ZMW", "USDC", "BYR", "STD", "STN", "VED", "VEF", "XXX", "$UNKNOWN" - `lastPaymentStatus` (string) Enum: "SUCCEEDED", "FAILED", "$UNKNOWN" - `billingPolicy` (object) - `billingPolicy.interval` (string) Enum: "DAY", "WEEK", "MONTH", "YEAR", "$UNKNOWN" - `billingPolicy.intervalCount` (integer) - `billingPolicy.anchors` (array) - `billingPolicy.anchors.cutoffDay` (integer) - `billingPolicy.anchors.day` (integer) - `billingPolicy.anchors.month` (integer) - `billingPolicy.anchors.type` (string) Enum: "WEEKDAY", "MONTHDAY", "YEARDAY", "$UNKNOWN" - `billingPolicy.maxCycles` (integer) - `billingPolicy.minCycles` (integer) - `deliveryPolicy` (object) - `lines` (object) - `lines.nodes` (array) - `lines.nodes.sellingPlanId` (string) - `lines.nodes.sellingPlanName` (string) - `lines.nodes.productId` (string) - `lines.nodes.sku` (string) - `lines.nodes.title` (string) - `lines.nodes.variantId` (string) - `lines.nodes.quantity` (integer) - `lines.nodes.customAttributes` (array) - `lines.nodes.customAttributes.key` (string) - `lines.nodes.customAttributes.value` (string) - `lines.nodes.lineDiscountedPrice` (object) - `lines.nodes.variantImage` (object) - `lines.nodes.variantImage.transformedSrc` (object) - `lines.nodes.variantTitle` (string) - `lines.nodes.currentPrice` (object) - `lines.nodes.discountAllocations` (array) - `lines.nodes.discountAllocations.discount` (object) - `lines.nodes.pricingPolicy` (object) - `lines.nodes.pricingPolicy.basePrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts` (array) - `lines.nodes.pricingPolicy.cycleDiscounts.afterCycle` (integer) - `lines.nodes.pricingPolicy.cycleDiscounts.computedPrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentType` (string) Enum: "PERCENTAGE", "FIXED_AMOUNT", "PRICE", "$UNKNOWN" - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentValue` (object) - `lines.nodes.taxable` (boolean) - `lines.pageInfo` (object) - `lines.pageInfo.hasPreviousPage` (boolean) - `lines.pageInfo.hasNextPage` (boolean) - `lines.pageInfo.startCursor` (string) - `lines.pageInfo.endCursor` (string) - `customerPaymentMethod` (object) - `customerPaymentMethod.instrument` (object) - `customerPaymentMethod.revokedAt` (object) - `customerPaymentMethod.revokedReason` (string) Enum: "AUTHORIZE_NET_GATEWAY_NOT_ENABLED", "AUTHORIZE_NET_RETURNED_NO_PAYMENT_METHOD", "FAILED_TO_UPDATE_CREDIT_CARD", "STRIPE_API_AUTHENTICATION_ERROR", "STRIPE_API_INVALID_REQUEST_ERROR", "STRIPE_GATEWAY_NOT_ENABLED", "STRIPE_RETURNED_NO_PAYMENT_METHOD", "STRIPE_PAYMENT_METHOD_NOT_CARD", "BRAINTREE_API_AUTHENTICATION_ERROR", "BRAINTREE_GATEWAY_NOT_ENABLED", "BRAINTREE_RETURNED_NO_PAYMENT_METHOD", "BRAINTREE_PAYMENT_METHOD_NOT_CARD", "PAYMENT_METHOD_VERIFICATION_FAILED", "THREE_D_SECURE_FLOW_IN_VERIFICATION_NOT_IMPLEMENTED", "MANUALLY_REVOKED", "FAILED_TO_RETRIEVE_BILLING_ADDRESS", "MERGED", "CUSTOMER_REDACTED", "TOO_MANY_CONSECUTIVE_FAILURES", "CVV_ATTEMPTS_LIMIT_EXCEEDED", "$UNKNOWN" - `deliveryMethod` (object) - `originOrder` (object) - `originOrder.name` (string) - `originOrder.fulfillmentOrders` (object) - `customer` (object) - `customer.displayName` (string) - `customer.firstName` (string) - `customer.lastName` (string) - `customer.email` (string) - `customer.phone` (string) - `discounts` (object) - `note` (string) - `billingAttempts` (object) ## Response 403 fields (*/*): - `get__typename` (string) - `id` (string) - `createdAt` (object) - `updatedAt` (object) - `nextBillingDate` (object) - `status` (string) Enum: "ACTIVE", "PAUSED", "CANCELLED", "EXPIRED", "FAILED", "$UNKNOWN" - `deliveryPrice` (object) - `deliveryPrice.amount` (object) - `deliveryPrice.currencyCode` (string) Enum: "USD", "EUR", "GBP", "CAD", "AFN", "ALL", "DZD", "AOA", "ARS", "AMD", "AWG", "AUD", "BBD", "AZN", "BDT", "BSD", "BHD", "BIF", "BYN", "BZD", "BMD", "BTN", "BAM", "BRL", "BOB", "BWP", "BND", "BGN", "MMK", "KHR", "CVE", "KYD", "XAF", "CLP", "CNY", "COP", "KMF", "CDF", "CRC", "HRK", "CZK", "DKK", "DJF", "DOP", "XCD", "EGP", "ERN", "ETB", "FKP", "XPF", "FJD", "GIP", "GMD", "GHS", "GTQ", "GYD", "GEL", "GNF", "HTG", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "ILS", "IRR", "IQD", "JMD", "JPY", "JEP", "JOD", "KZT", "KES", "KID", "KWD", "KGS", "LAK", "LVL", "LBP", "LSL", "LRD", "LYD", "LTL", "MGA", "MKD", "MOP", "MWK", "MVR", "MRU", "MXN", "MYR", "MUR", "MDL", "MAD", "MNT", "MZN", "NAD", "NPR", "ANG", "NZD", "NIO", "NGN", "NOK", "OMR", "PAB", "PKR", "PGK", "PYG", "PEN", "PHP", "PLN", "QAR", "RON", "RUB", "RWF", "WST", "SHP", "SAR", "RSD", "SCR", "SLL", "SGD", "SDG", "SOS", "SYP", "ZAR", "KRW", "SSP", "SBD", "LKR", "SRD", "SZL", "SEK", "CHF", "TWD", "THB", "TJS", "TZS", "TOP", "TTD", "TND", "TRY", "TMT", "UGX", "UAH", "AED", "UYU", "UZS", "VUV", "VES", "VND", "XOF", "YER", "ZMW", "USDC", "BYR", "STD", "STN", "VED", "VEF", "XXX", "$UNKNOWN" - `lastPaymentStatus` (string) Enum: "SUCCEEDED", "FAILED", "$UNKNOWN" - `billingPolicy` (object) - `billingPolicy.interval` (string) Enum: "DAY", "WEEK", "MONTH", "YEAR", "$UNKNOWN" - `billingPolicy.intervalCount` (integer) - `billingPolicy.anchors` (array) - `billingPolicy.anchors.cutoffDay` (integer) - `billingPolicy.anchors.day` (integer) - `billingPolicy.anchors.month` (integer) - `billingPolicy.anchors.type` (string) Enum: "WEEKDAY", "MONTHDAY", "YEARDAY", "$UNKNOWN" - `billingPolicy.maxCycles` (integer) - `billingPolicy.minCycles` (integer) - `deliveryPolicy` (object) - `lines` (object) - `lines.nodes` (array) - `lines.nodes.sellingPlanId` (string) - `lines.nodes.sellingPlanName` (string) - `lines.nodes.productId` (string) - `lines.nodes.sku` (string) - `lines.nodes.title` (string) - `lines.nodes.variantId` (string) - `lines.nodes.quantity` (integer) - `lines.nodes.customAttributes` (array) - `lines.nodes.customAttributes.key` (string) - `lines.nodes.customAttributes.value` (string) - `lines.nodes.lineDiscountedPrice` (object) - `lines.nodes.variantImage` (object) - `lines.nodes.variantImage.transformedSrc` (object) - `lines.nodes.variantTitle` (string) - `lines.nodes.currentPrice` (object) - `lines.nodes.discountAllocations` (array) - `lines.nodes.discountAllocations.discount` (object) - `lines.nodes.pricingPolicy` (object) - `lines.nodes.pricingPolicy.basePrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts` (array) - `lines.nodes.pricingPolicy.cycleDiscounts.afterCycle` (integer) - `lines.nodes.pricingPolicy.cycleDiscounts.computedPrice` (object) - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentType` (string) Enum: "PERCENTAGE", "FIXED_AMOUNT", "PRICE", "$UNKNOWN" - `lines.nodes.pricingPolicy.cycleDiscounts.adjustmentValue` (object) - `lines.nodes.taxable` (boolean) - `lines.pageInfo` (object) - `lines.pageInfo.hasPreviousPage` (boolean) - `lines.pageInfo.hasNextPage` (boolean) - `lines.pageInfo.startCursor` (string) - `lines.pageInfo.endCursor` (string) - `customerPaymentMethod` (object) - `customerPaymentMethod.instrument` (object) - `customerPaymentMethod.revokedAt` (object) - `customerPaymentMethod.revokedReason` (string) Enum: "AUTHORIZE_NET_GATEWAY_NOT_ENABLED", "AUTHORIZE_NET_RETURNED_NO_PAYMENT_METHOD", "FAILED_TO_UPDATE_CREDIT_CARD", "STRIPE_API_AUTHENTICATION_ERROR", "STRIPE_API_INVALID_REQUEST_ERROR", "STRIPE_GATEWAY_NOT_ENABLED", "STRIPE_RETURNED_NO_PAYMENT_METHOD", "STRIPE_PAYMENT_METHOD_NOT_CARD", "BRAINTREE_API_AUTHENTICATION_ERROR", "BRAINTREE_GATEWAY_NOT_ENABLED", "BRAINTREE_RETURNED_NO_PAYMENT_METHOD", "BRAINTREE_PAYMENT_METHOD_NOT_CARD", "PAYMENT_METHOD_VERIFICATION_FAILED", "THREE_D_SECURE_FLOW_IN_VERIFICATION_NOT_IMPLEMENTED", "MANUALLY_REVOKED", "FAILED_TO_RETRIEVE_BILLING_ADDRESS", "MERGED", "CUSTOMER_REDACTED", "TOO_MANY_CONSECUTIVE_FAILURES", "CVV_ATTEMPTS_LIMIT_EXCEEDED", "$UNKNOWN" - `deliveryMethod` (object) - `originOrder` (object) - `originOrder.name` (string) - `originOrder.fulfillmentOrders` (object) - `customer` (object) - `customer.displayName` (string) - `customer.firstName` (string) - `customer.lastName` (string) - `customer.email` (string) - `customer.phone` (string) - `discounts` (object) - `note` (string) - `billingAttempts` (object) ## Response 400 fields