> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace products in subscriptions in bulk > Replaces old product variants with new product variants across multiple subscription contracts in bulk. This powerful operation allows merchants to update products in active subscriptions when products are discontinued, reformulated, or repackaged. **What is Product Replacement?** Product replacement updates the products in active subscriptions by swapping out old variant IDs with new variant IDs. This is commonly needed when: - Products are discontinued and replaced with new versions - Product packaging changes (size, quantity) - Product reformulations or recipe updates - SKU consolidation or reorganization - Seasonal product variations - Price structure changes **Key Features:** - **Bulk Operation**: Update thousands of subscriptions simultaneously - **Multi-Variant Support**: Replace multiple old variants with new ones in single request - **Flexible Mapping**: One-to-one, many-to-one, or one-to-many variant replacements - **Selective or Universal**: Target specific subscriptions or all subscriptions - **Asynchronous Processing**: Large batches processed in background - **Price Preservation Options**: Maintain existing subscription pricing or update to new prices - **Activity Logging**: All replacements are logged for audit trail **Operation Modes:** 1. **Specific Subscriptions**: Provide subscription contract IDs to update only those subscriptions 2. **All Subscriptions**: Set allSubscriptions=true to replace products in ALL active subscriptions containing the old variants **How It Works:** 1. Identify old variant IDs that need to be replaced 2. Identify new variant IDs that will replace them 3. Optionally specify which subscriptions to update (or use allSubscriptions=true) 4. Submit the bulk replacement request 5. System validates all variant IDs exist and are accessible 6. Bulk automation task is created and queued 7. Each subscription is updated with new variants 8. Customers receive updated subscription details 9. Next orders will include the new products **Variant ID Mapping:** The replacement supports flexible mapping between old and new variants: **One-to-One Replacement:** ```json { "oldVariantIds": [111111], "newVariantIds": [222222] } ``` Old variant 111111 is replaced with new variant 222222 **Multiple Variants Replacement:** ```json { "oldVariantIds": [111111, 333333, 555555], "newVariantIds": [222222, 444444, 666666] } ``` Each old variant is replaced with its corresponding new variant (by position) **Request Structure:** ```json { "subscriptionIds": [ "gid://shopify/SubscriptionContract/123456", "gid://shopify/SubscriptionContract/123457" ] } ``` **Query Parameters:** - `api_key` (required): Your API authentication key - `allSubscriptions` (optional): Set to true to update all subscriptions, false/omit to update only specified IDs - `newVariantIds` (required): Comma-separated list of new variant IDs (e.g., 222222,444444,666666) - `oldVariantIds` (required): Comma-separated list of old variant IDs to replace (e.g., 111111,333333,555555) **Use Cases:** **1. Product Discontinuation:** When a product is being discontinued: - Identify replacement product - Map old variant IDs to new variant IDs - Update all subscriptions containing the old product - Notify customers of the change **2. Packaging Updates:** When product packaging changes (e.g., 10oz to 12oz): - Create new variant for new package size - Replace old variant across subscriptions - Adjust pricing if needed **3. Product Reformulation:** When product recipes or formulas change: - Create new product variant for reformulated version - Bulk replace old formula with new formula - Maintain customer subscription frequency and pricing **4. SKU Consolidation:** When consolidating multiple variants into a single SKU: - Map multiple old variant IDs to single new variant ID - Update all affected subscriptions - Simplify inventory management **5. Seasonal Product Rotation:** For seasonal subscription boxes: - Replace summer variants with fall variants - Update all active seasonal subscriptions - Maintain subscription continuity **Important Considerations:** - **Pricing Impact**: New variants may have different prices - verify pricing strategy - **Inventory Levels**: Ensure adequate inventory for new variants - **Customer Communication**: Consider notifying customers before replacement - **Variant Compatibility**: New variants should be appropriate replacements - **One Operation at a Time**: Only one bulk operation can run per shop simultaneously - **Irreversible**: Product replacements cannot be automatically undone (must be manually reversed) - **Subscription Contract IDs**: Must use Shopify GraphQL ID format **Processing Time:** - Small batches (<100 subscriptions): Seconds to minutes - Medium batches (100-1000): Minutes - Large batches (>1000): Minutes to hours - Processing time depends on number of subscriptions and line items **Best Practices:** 1. **Test First**: Test with a small subset of subscriptions before bulk operation 2. **Verify Variants**: Confirm all variant IDs are correct and products are active 3. **Check Inventory**: Ensure sufficient stock of new variants 4. **Customer Communication**: Notify affected customers about product changes 5. **Price Review**: Review and confirm pricing for new variants 6. **Backup Data**: Export subscription data before making bulk changes 7. **Monitor Progress**: Track bulk operation status to completion 8. **Audit Trail**: Document reason for replacement for future reference **Error Scenarios:** - Another bulk operation running: 400 error - Invalid variant IDs: Operation may fail or skip invalid variants - Mismatched array lengths: Ensure oldVariantIds and newVariantIds have same count - Product not found: Variants must exist in your Shopify store - Unauthorized access: Can only modify subscriptions belonging to your shop **Customer Impact:** - Next subscription order will contain new products - Previous orders are not affected - Subscription price may change if new variant has different price - Customer portal reflects the new product immediately - Subscription frequency and schedule remain unchanged **Authentication:** Requires valid api_key parameter (X-API-Key header support coming soon) ## OpenAPI ````yaml /subscription/admin-api-swagger.json post /api/external/v2/bulk-automations/replace-product openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/bulk-automations/replace-product: post: tags: - Operations & Settings summary: Replace products in subscriptions in bulk description: >- Replaces old product variants with new product variants across multiple subscription contracts in bulk. This powerful operation allows merchants to update products in active subscriptions when products are discontinued, reformulated, or repackaged. **What is Product Replacement?** Product replacement updates the products in active subscriptions by swapping out old variant IDs with new variant IDs. This is commonly needed when: - Products are discontinued and replaced with new versions - Product packaging changes (size, quantity) - Product reformulations or recipe updates - SKU consolidation or reorganization - Seasonal product variations - Price structure changes **Key Features:** - **Bulk Operation**: Update thousands of subscriptions simultaneously - **Multi-Variant Support**: Replace multiple old variants with new ones in single request - **Flexible Mapping**: One-to-one, many-to-one, or one-to-many variant replacements - **Selective or Universal**: Target specific subscriptions or all subscriptions - **Asynchronous Processing**: Large batches processed in background - **Price Preservation Options**: Maintain existing subscription pricing or update to new prices - **Activity Logging**: All replacements are logged for audit trail **Operation Modes:** 1. **Specific Subscriptions**: Provide subscription contract IDs to update only those subscriptions 2. **All Subscriptions**: Set allSubscriptions=true to replace products in ALL active subscriptions containing the old variants **How It Works:** 1. Identify old variant IDs that need to be replaced 2. Identify new variant IDs that will replace them 3. Optionally specify which subscriptions to update (or use allSubscriptions=true) 4. Submit the bulk replacement request 5. System validates all variant IDs exist and are accessible 6. Bulk automation task is created and queued 7. Each subscription is updated with new variants 8. Customers receive updated subscription details 9. Next orders will include the new products **Variant ID Mapping:** The replacement supports flexible mapping between old and new variants: **One-to-One Replacement:** ```json { "oldVariantIds": [111111], "newVariantIds": [222222] } ``` Old variant 111111 is replaced with new variant 222222 **Multiple Variants Replacement:** ```json { "oldVariantIds": [111111, 333333, 555555], "newVariantIds": [222222, 444444, 666666] } ``` Each old variant is replaced with its corresponding new variant (by position) **Request Structure:** ```json { "subscriptionIds": [ "gid://shopify/SubscriptionContract/123456", "gid://shopify/SubscriptionContract/123457" ] } ``` **Query Parameters:** - `api_key` (required): Your API authentication key - `allSubscriptions` (optional): Set to true to update all subscriptions, false/omit to update only specified IDs - `newVariantIds` (required): Comma-separated list of new variant IDs (e.g., 222222,444444,666666) - `oldVariantIds` (required): Comma-separated list of old variant IDs to replace (e.g., 111111,333333,555555) **Use Cases:** **1. Product Discontinuation:** When a product is being discontinued: - Identify replacement product - Map old variant IDs to new variant IDs - Update all subscriptions containing the old product - Notify customers of the change **2. Packaging Updates:** When product packaging changes (e.g., 10oz to 12oz): - Create new variant for new package size - Replace old variant across subscriptions - Adjust pricing if needed **3. Product Reformulation:** When product recipes or formulas change: - Create new product variant for reformulated version - Bulk replace old formula with new formula - Maintain customer subscription frequency and pricing **4. SKU Consolidation:** When consolidating multiple variants into a single SKU: - Map multiple old variant IDs to single new variant ID - Update all affected subscriptions - Simplify inventory management **5. Seasonal Product Rotation:** For seasonal subscription boxes: - Replace summer variants with fall variants - Update all active seasonal subscriptions - Maintain subscription continuity **Important Considerations:** - **Pricing Impact**: New variants may have different prices - verify pricing strategy - **Inventory Levels**: Ensure adequate inventory for new variants - **Customer Communication**: Consider notifying customers before replacement - **Variant Compatibility**: New variants should be appropriate replacements - **One Operation at a Time**: Only one bulk operation can run per shop simultaneously - **Irreversible**: Product replacements cannot be automatically undone (must be manually reversed) - **Subscription Contract IDs**: Must use Shopify GraphQL ID format **Processing Time:** - Small batches (<100 subscriptions): Seconds to minutes - Medium batches (100-1000): Minutes - Large batches (>1000): Minutes to hours - Processing time depends on number of subscriptions and line items **Best Practices:** 1. **Test First**: Test with a small subset of subscriptions before bulk operation 2. **Verify Variants**: Confirm all variant IDs are correct and products are active 3. **Check Inventory**: Ensure sufficient stock of new variants 4. **Customer Communication**: Notify affected customers about product changes 5. **Price Review**: Review and confirm pricing for new variants 6. **Backup Data**: Export subscription data before making bulk changes 7. **Monitor Progress**: Track bulk operation status to completion 8. **Audit Trail**: Document reason for replacement for future reference **Error Scenarios:** - Another bulk operation running: 400 error - Invalid variant IDs: Operation may fail or skip invalid variants - Mismatched array lengths: Ensure oldVariantIds and newVariantIds have same count - Product not found: Variants must exist in your Shopify store - Unauthorized access: Can only modify subscriptions belonging to your shop **Customer Impact:** - Next subscription order will contain new products - Previous orders are not affected - Subscription price may change if new variant has different price - Customer portal reflects the new product immediately - Subscription frequency and schedule remain unchanged **Authentication:** Requires valid api_key parameter (X-API-Key header support coming soon) operationId: replaceProductV2 parameters: - description: Your API Key in: query name: api_key required: true schema: type: string - description: allSubscriptions in: query name: allSubscriptions required: false schema: type: boolean - description: New Variant Ids in: query name: newVariantIds required: true schema: items: format: int64 type: integer type: array - description: Old Variant Ids in: query name: oldVariantIds required: true schema: items: format: int64 type: integer type: array requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionContractIdsWrapper' required: true responses: '204': content: application/json: examples: Success Response: description: Success Response value: {} description: >- Bulk product replacement operation successfully queued and initiated. Subscriptions will be updated asynchronously. '400': content: application/json: examples: Mismatched Variant Arrays: description: Mismatched Variant Arrays value: detail: >- oldVariantIds and newVariantIds must have the same number of elements status: 400 title: Invalid variant mapping type: https://example.com/errors/bad-request Missing Variant IDs: description: Missing Variant IDs value: detail: >- Both oldVariantIds and newVariantIds parameters are required status: 400 title: Missing required parameters type: https://example.com/errors/bad-request Operation Already Running: description: Operation Already Running value: detail: >- UserGeneratedError: Bulk request for current shop is already in progress entityName: bulkAutomation status: 400 title: Bulk operation in progress type: https://example.com/errors/bad-request description: >- Bad request - bulk operation already in progress, invalid parameters, or missing required fields '401': content: application/json: example: detail: Valid api_key parameter is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required - Missing or invalid API key '403': content: application/json: example: detail: >- API key does not have permission to modify subscription products status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to perform bulk product replacement '404': content: application/json: example: detail: One or more specified variant IDs do not exist in your store status: 404 title: Variant not found type: https://example.com/errors/not-found description: One or more variant IDs not found '422': content: application/json: example: detail: New variant is not compatible with subscription configuration status: 422 title: Invalid variant replacement type: https://example.com/errors/unprocessable-entity description: >- Unprocessable entity - Invalid variant IDs or business logic validation failure '500': content: application/json: example: detail: >- An unexpected error occurred while initiating the bulk replacement operation status: 500 title: Internal server error type: https://example.com/errors/internal-server-error description: Internal server error during bulk operation initialization components: schemas: SubscriptionContractIdsWrapper: properties: subscriptionIds: type: string type: object ````