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
Headers
API Key
Query Parameters
API Key (Deprecated)
Body
Product replacement configuration for subscription contracts. Allows replacing existing subscription products with new ones, managing quantities, and handling one-time purchases.
The ID of the subscription contract to modify
123456789
The Shop of the subscription contract to modify
"abcStore.myshopify.com"
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.
42549172011164
Old-to-new child variant mappings applied to the parent bundle line's child products when babParentVariantId is set.
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).
false
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"
CUSTOMER_PORTAL, MERCHANT_PORTAL, SHOPIFY_EVENT, SYSTEM_EVENT, MERCHANT_PORTAL_BULK_AUTOMATION, SCHEDULED_BULK_AUTOMATION, MERCHANT_EXTERNAL_API, SHOPIFY_FLOW 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.
{ "42549172066666": 1, "42549172077777": 2 }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.
{ "42549172033333": 2, "42549172044444": 1 }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"
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]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]If true, suppresses email notifications about the product swap. Default is false (emails will be sent).
false
Response
Products successfully replaced
SUCCEEDED, FAILED, $UNKNOWN ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN