> ## 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. # Create a new product swap automation > Creates a new product swap automation rule for the authenticated shop. Product swaps automatically replace products in subscription orders based on billing cycles or recurring schedules. **Required Fields:** - **shop**: Your Shopify shop domain - **sourceVariants**: JSON string of variants to swap FROM (format: [{"id":12345,"quantity":2}]) - **destinationVariants**: JSON string of variants to swap TO (format: [{"id":67890,"quantity":2}]) - **name**: Descriptive name for this swap rule **Optional Fields:** - **forBillingCycle**: Specific cycle number when swap occurs (e.g., 4 = swap at 4th order). Leave null for recurring swaps. - **checkForEveryRecurringOrder**: If true, applies swap to every order (overrides forBillingCycle) - **updatedFirstOrder**: If true, can affect the first subscription order - **changeNextOrderDateBy**: Days to adjust next order date after swap (positive or negative integer) - **discountCarryForward**: How to handle discounts - NONE, PERCENTAGE, FIXED_AMOUNT, or PRICE - **carryDiscountForward**: Legacy boolean field (deprecated, use discountCarryForward instead) - **stopSwapEmails**: If true, suppresses customer notification emails about the swap - **ruleSequence**: Priority order when multiple swaps apply (lower number = higher priority) **Variant JSON Format:** The API enriches your variant data with product details from Shopify. You only need to provide: ```json [{"id": 12345, "quantity": 2}] ``` The response will include enriched data: displayName, imageSrc, productTitle, etc. **Authentication:** Requires valid X-API-Key header ## OpenAPI ````yaml /subscription/admin-api-swagger.json post /api/external/v2/product-swaps 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/product-swaps: post: tags: - Product Catalog summary: Create a new product swap automation description: >- Creates a new product swap automation rule for the authenticated shop. Product swaps automatically replace products in subscription orders based on billing cycles or recurring schedules. **Required Fields:** - **shop**: Your Shopify shop domain - **sourceVariants**: JSON string of variants to swap FROM (format: [{"id":12345,"quantity":2}]) - **destinationVariants**: JSON string of variants to swap TO (format: [{"id":67890,"quantity":2}]) - **name**: Descriptive name for this swap rule **Optional Fields:** - **forBillingCycle**: Specific cycle number when swap occurs (e.g., 4 = swap at 4th order). Leave null for recurring swaps. - **checkForEveryRecurringOrder**: If true, applies swap to every order (overrides forBillingCycle) - **updatedFirstOrder**: If true, can affect the first subscription order - **changeNextOrderDateBy**: Days to adjust next order date after swap (positive or negative integer) - **discountCarryForward**: How to handle discounts - NONE, PERCENTAGE, FIXED_AMOUNT, or PRICE - **carryDiscountForward**: Legacy boolean field (deprecated, use discountCarryForward instead) - **stopSwapEmails**: If true, suppresses customer notification emails about the swap - **ruleSequence**: Priority order when multiple swaps apply (lower number = higher priority) **Variant JSON Format:** The API enriches your variant data with product details from Shopify. You only need to provide: ```json [{"id": 12345, "quantity": 2}] ``` The response will include enriched data: displayName, imageSrc, productTitle, etc. **Authentication:** Requires valid X-API-Key header operationId: createProductSwap parameters: - in: header name: X-API-Key required: false schema: type: string requestBody: content: application/json: examples: Request Example: description: Request Example value: carryDiscountForward: false checkForEveryRecurringOrder: false destinationVariants: '[{"id":67890,"quantity":2}]' discountCarryForward: NONE forBillingCycle: 2 name: swap test shop: example-shop sourceVariants: '[{"id":12345,"quantity":2}]' stopSwapEmails: false updatedFirstOrder: false schema: $ref: '#/components/schemas/ProductSwapDTO' description: ProductSwapDTO payload required: true responses: '200': content: application/json: examples: Success Response: description: Success Response value: carryDiscountForward: false changeNextOrderDateBy: null checkForEveryRecurringOrder: false destinationVariants: >- [{"id":67890,"displayName":"test-product","imageSrc":"https://test.com/image.png","quantity":2}] discountCarryForward: NONE forBillingCycle: 2 id: 10782 name: swap test ruleSequence: 0 shop: example-shop sourceVariants: >- [{"id":12345,"displayName":"test-product","imageSrc":"https://test.com/image.png","quantity":2}] stopSwapEmails: false updatedFirstOrder: false schema: $ref: '#/components/schemas/ProductSwapDTO' description: Product swap created successfully '400': content: application/json: examples: ID Exists: description: ID Exists value: detail: A new productSwap cannot already have an ID status: 400 title: A new productSwap cannot already have an ID type: https://example.com/errors/bad-request description: Invalid request or product swap already has an ID '401': content: application/json: example: detail: Valid X-API-Key header is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required '403': content: application/json: example: detail: API key does not have permission to create product swaps status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to create product swap '404': content: application/json: example: detail: Resource not found status: 404 title: Resource not found type: https://example.com/errors/not-found description: Resource not found '422': content: application/json: example: detail: Cannot create product swap due to business rule violation status: 422 title: Business rule violation type: https://example.com/errors/unprocessable-entity description: Unprocessable entity - business rule violation deprecated: true components: schemas: ProductSwapDTO: properties: carryDiscountForward: type: boolean changeNextOrderDateBy: format: int32 type: integer checkForEveryRecurringOrder: type: boolean destinationVariants: type: string discountCarryForward: enum: - NONE - EXISTING_PLAN - PRODUCT_PLAN - PRODUCT_THEN_EXISTING type: string forBillingCycle: format: int32 type: integer id: format: int64 type: integer name: type: string ruleSequence: format: int32 type: integer shop: type: string sourceVariants: type: string stopSwapEmails: type: boolean updatedFirstOrder: type: boolean required: - shop type: object ````