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.

Full behavior, validation rules, and side effects

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

POST /subscriptions/cp/api/subscription-contract-details/replace-variants-v3

Replace product variants in a subscription contract

cURL

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
}
'

200

Success Response

{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Body

application/json

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

shop · string · required

The Shop of the subscription contract to modify

Example:

"abcStore.myshopify.com"

contractId · integer<int64> · required

The ID of the subscription contract to modify

Example:

123456789

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]

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.

Show child attributes

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.

Show child attributes

Example:

{ "42549172066666": 1, "42549172077777": 2 }

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]

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 · enum<string>

Available options: CUSTOMER_PORTAL, MERCHANT_PORTAL, SHOPIFY_EVENT, SYSTEM_EVENT, MERCHANT_PORTAL_BULK_AUTOMATION, MERCHANT_EXTERNAL_API, SHOPIFY_FLOW

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"

stopSwapEmails · boolean · default: false

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

Example:

false

Response

200

application/json

Products successfully replaced

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes