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. <details> <summary>**Full behavior, validation rules, and side effects**</summary> **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 </details>

POST /api/external/v2/product-swaps

Create a new product swap automation

cURL

curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/product-swaps \
  --header 'Content-Type: application/json' \
  --data '
{
  "shop": "example-shop"
}
'

200

{
  "id": 10782,
  "shop": "example-shop",
  "sourceVariants": "[{\"id\":12345,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]",
  "destinationVariants": "[{\"id\":67890,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]",
  "updatedFirstOrder": false,
  "checkForEveryRecurringOrder": false,
  "name": "swap test",
  "changeNextOrderDateBy": null,
  "forBillingCycle": 2,
  "carryDiscountForward": false,
  "ruleSequence": 0,
  "stopSwapEmails": false,
  "discountCarryForward": "NONE"
}

Headers

X-API-Key · string

Body

application/json

ProductSwapDTO payload

shop · string · required

id · integer<int64>

sourceVariants · string

destinationVariants · string

updatedFirstOrder · boolean

checkForEveryRecurringOrder · boolean

name · string

changeNextOrderDateBy · integer<int32>

forBillingCycle · integer<int32>

carryDiscountForward · boolean

ruleSequence · integer<int32>

stopSwapEmails · boolean

discountCarryForward · enum<string>

Available options: NONE, EXISTING_PLAN, PRODUCT_PLAN, PRODUCT_THEN_EXISTING

Response

200

application/json

Product swap created successfully

shop · string · required

id · integer<int64>

sourceVariants · string

destinationVariants · string

updatedFirstOrder · boolean

checkForEveryRecurringOrder · boolean

name · string

changeNextOrderDateBy · integer<int32>

forBillingCycle · integer<int32>

carryDiscountForward · boolean

ruleSequence · integer<int32>

stopSwapEmails · boolean

discountCarryForward · enum<string>

Available options: NONE, EXISTING_PLAN, PRODUCT_PLAN, PRODUCT_THEN_EXISTING