> For the complete documentation index, see [llms.txt](https://subscriptions-docs.tech-arms.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://subscriptions-docs.tech-arms.io/features/email-notifications/auto-product-swap.md).

# Auto Product Swap

Automatically replace products in your customers' subscriptions from a billing cycle you choose.

**Auto Product Swap** replaces products in running subscriptions with other products, starting from a billing cycle you choose. Use it to move subscribers to a new version of a product, rotate a seasonal item, or add a free product after a number of cycles.

Each swap rule contains:

* the **Original Product** variants to replace,
* the **New Product** variants to add instead,
* the billing cycle from which the swap applies,
* the price of the new products: their original price or free.

{% hint style="info" %}
A swap is permanent. Once a subscription is swapped, it keeps the new products for all future orders, even if you later deactivate or delete the rule.
{% endhint %}

## Create a swap rule

{% stepper %}
{% step %}

### Open Auto Product Swap

In the app menu, click **Settings**, then click the **Automation** card. In the window that opens, click **Auto Product Swap**.

Click **Create Product Swap**.

![The Auto Product Swap page with the Create Product Swap button highlighted](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FvVFbq3B57XO1l8C0FhTe%2Fauto-product-swap-list.png?alt=media)
{% endstep %}

{% step %}

### Fill in General Information

| Field                                | What it does                                                                                                                                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name of swap rule**                | A name to recognize the rule. Only you see it.                                                                                                                                                                                                                |
| **Priority**                         | The order in which rules run when more than one rule matches a subscription. Rules run from the lowest number up. If two rules have the same priority, the older rule runs first. The default is 0.                                                           |
| **When to activate**                 | **From** *N* **Cycle(s)**: the billing cycle from which the rule applies. The default is 1.                                                                                                                                                                   |
| **Configure subscription discounts** | **Don't apply any discount, new products will remain at the original price** (default): new products are charged at their current price in Shopify, without the subscription discount. **New products will be free**: new products are added at a price of 0. |

![The General Information card with When to activate and Configure subscription discounts highlighted](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FgnTEHFiw5JrihAM12How%2Fauto-product-swap-general-information.png?alt=media)
{% endstep %}

{% step %}

### Choose the products to swap

In **Products to Swap**:

1. Under **Original Product**, click **Add product** and select the variants to replace.
2. Under **New Product**, click **Add product** and select the variants to add.

You can select up to 5 variants on each side. Click **Edit** to change your selection later.

![The Products to Swap card with Original Product and New Product](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FaZ1ADqSNdHw6ZkNlOzDt%2Fauto-product-swap-products.png?alt=media)

{% hint style="warning" %}
When you select several **Original Product** variants, a subscription must contain **all** of them for the swap to apply. To swap each product on its own, create a separate rule for each one.
{% endhint %}
{% endstep %}

{% step %}

### Save

Click **Save** in the bar at the top of the page. The rule is **Active** as soon as it is saved. The **Summary** card on the right shows what the rule will do.
{% endstep %}
{% endstepper %}

## How the swap works

A rule applies to a subscription when:

* the rule is **Active**,
* the subscription contains every **Original Product** variant of the rule,
* the subscription has reached the cycle set in **When to activate**.

The app checks the rules when a subscription is created and after each successful renewal payment. When a rule applies, the app updates the subscription itself, so the change affects every order after it:

* every **Original Product** variant is removed,
* every **New Product** variant is added with a quantity of 1,
* the new products are priced as set in **Configure subscription discounts**.

| Situation                                                            | Swapped?                           |
| -------------------------------------------------------------------- | ---------------------------------- |
| The first order placed at checkout                                   | No                                 |
| A renewal payment fails                                              | No                                 |
| Subscriptions that were already running when you created the rule    | Yes, once they meet the conditions |
| The subscription contains only some of the Original Product variants | No                                 |

Customers are not notified of the swap. They see the new products in the customer portal and in their next orders.

## Manage swap rules

The **Auto Product Swap** list shows each rule's name, the number of original and new products, **Status** (**Active** or **Draft**), **Priority**, **Start Time** (for example, "From 1st cycle"), and creation date.

* **Edit** a rule by clicking it in the list.
* **Activate** or **Deactivate** a rule with the button at the top of its page. A **Draft** rule does not swap anything.
* **Delete** a rule with the delete icon in the list. This can't be undone.

Deactivating or deleting a rule only stops future swaps. Subscriptions that were already swapped keep the new products.

## Limits

* Up to 10 swap rules per store. When you reach 10, the **Create Product Swap** button is disabled.
* Up to 5 **Original Product** variants and 5 **New Product** variants per rule.
* New products are always added with a quantity of 1.
* If you see "This product is already used in another swap rule. Please select a different product.", choose a product that no other rule uses.

## Pricing plans

Auto Product Swap is a paid feature on some plans. If you see **Unlock Now** instead of **Create Product Swap**, contact us via live chat to unlock it.

## Good to know

* Select the exact variants you want to replace. If you add a whole product with several variants as the **Original Product**, a subscription must contain all of those variants, so the rule will rarely match.
* Make sure the **New Product** is in stock. If it is out of stock and **Allow Overselling** is turned off in **Settings > Renewal & Dunning**, the next renewal can fail.
* The swap removes the subscription discount from the new products. Choose **New products will be free** if you want to give them away.
* New products are priced in your store's default currency.
* On a [Build-A-Box](https://subscriptions-docs.tech-arms.io/features/build-a-box.md) subscription, a swapped item is replaced by a regular product line at its full price with a quantity of 1.
* To check a swap on a subscription, open it from **Subscriptions**. See [Subscription details](https://subscriptions-docs.tech-arms.io/features/subscriptions/contract-details.md).
* To tag orders and customers automatically, see [Auto Tag](https://subscriptions-docs.tech-arms.io/features/email-notifications/auto-tag.md).

*If you need help, feel free to reach out to us via in-app* [***Live chat***](https://go.crisp.chat/chat/embed/?website_id=c4ae10a3-f762-4968-b35a-c931caf62a96)***,*** [***Book a call***](https://calendly.com/ta-subscription-app-support/30min) *or at* [***support@tech-arms.io***](mailto:support@tech-arms.io)***.***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://subscriptions-docs.tech-arms.io/features/email-notifications/auto-product-swap.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
