Skip to main content
POST
Replace product variants in a subscription contract

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

carryForwardDiscount
enum<string>
deprecated

Ignored. The store's "Discount policy for added products" customer portal setting decides the discount on the new products.

Available options:
NONE,
EXISTING_PLAN,
PRODUCT_PLAN,
PRODUCT_THEN_EXISTING
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:
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:
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:
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:
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
revisionId
object
status
enum<string>
Available options:
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED,
$UNKNOWN
updatedAt
object