> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to setup a replacement upsell for subscriptions

> Step-by-step guide to replacing a one-time purchase with a subscription in post-purchase offers.

Replacement upsells allow you to replace a one-time product purchase with a subscription version of the same product during the post-purchase experience. This lets customers start a subscription after checkout without re-entering payment or shipping details.

You can configure subscription upgrades in three ways:

* **Frequency only** - Update the billing and delivery frequency of an existing subscription
* **Replacement only** - Swap to a different product while keeping the same frequency
* **Both** - Change the frequency and replace the product in a single action

## Prerequisites

Before setting up a replacement upsell, ensure:

* Your product has selling plans configured in Shopify
* Your subscription app uses Shopify's Subscription API (e.g., ReCharge, Appstle, Smartrr, Skio)
* The product you want to replace is available as both a one-time purchase and subscription

⚠️ **Important**: Due to Shopify limitations, you cannot add a subscription to an order that already contains a subscription. Replacement upsells only work when the original order contains no subscription items.

## Step 1: Identify the product to replace

Determine which one-time purchase product you want to offer as a subscription replacement. This should be a product that:

* Customers frequently purchase as a one-time item
* Makes sense as a recurring subscription (e.g., supplements, coffee, pet food)
* Has selling plans already configured in Shopify

## Step 2: Create a new post-purchase funnel

1. Open the Aftersell app from your Shopify Admin
2. Navigate to **Post-Purchase** in the left sidebar
3. Click **Create Funnel** or select an existing funnel to edit

## Step 3: Configure your trigger

Set up a trigger that fires when the one-time purchase product is in the order:

1. Click **Add Trigger** or edit an existing trigger
2. Select **Product** as the trigger type
3. Choose **Contains** as the condition
4. Select the one-time purchase product you want to replace
5. Click **Save**

💡 **Tip**: You can also use other trigger conditions like cart value, customer tags, or order properties to target specific customers for subscription replacement offers.

## Step 4: Create the replacement offer

1. Click **Add Offer** or edit an existing offer in your funnel
2. In the offer editor, click **Upsell Products**
3. Search for and select the **same product** that was purchased as a one-time item
4. Configure the subscription settings:
   * Select **Subscription Only** to force the replacement to be a subscription
   * Choose the selling plan you want to offer (e.g., "Deliver every 30 days")
   * The subscription pricing and cadence will be pulled from your Shopify selling plans

## Subscription upgrade types

When configuring subscription upgrades in your post-purchase offers, you can choose from three upgrade types:

### Frequency only

Updates the billing and delivery frequency of an existing subscription without changing the product. Use this when customers want to receive their subscription more or less frequently.

**Configuration:**

* Select **Frequency only** as the upgrade type
* Set the **Time unit** (day, week, month, or year)
* Set the **Delivery frequency** (how often the product is delivered)
* Set the **Billing frequency** (how often the customer is charged)
* (Optional) Add a **Subscription Discount**:
  * Enter the discount value
  * Select **Percentage** or **Fixed Amount** as the discount type
  * The discount applies only to the first billing cycle

💡 **Tip**: Billing frequency must be equal to or greater than delivery frequency. For example, you can deliver every 2 months and bill every 6 months (prepaid), but you cannot deliver every 6 months and bill every 2 months.

### Replacement only

Swaps the subscription to a different product while keeping the same billing and delivery frequency. Use this when customers want to switch to a different product variant or a completely different product.

**Configuration:**

* Select **Replacement only** as the upgrade type
* Click **Select replacement product** and choose the product to swap to
* The new product will use the same frequency settings as the original subscription
* (Optional) Add a **Subscription Discount**:
  * Enter the discount value
  * Select **Percentage** or **Fixed Amount** as the discount type
  * The discount applies only to the first billing cycle

### Both – change frequency and replace product

Changes both the product and the billing/delivery frequencies in a single action. Use this when customers want to switch to a different product AND adjust how often they receive it.

**Configuration:**

* Select **Both – change frequency and replace product** as the upgrade type
* Set the frequency settings (time unit, delivery frequency, billing frequency)
* Click **Select replacement product** and choose the product to swap to
* (Optional) Add a **Subscription Discount**:
  * Enter the discount value
  * Select **Percentage** or **Fixed Amount** as the discount type
  * The discount applies only to the first billing cycle

⚠️ **Important**: When using the "Both" option, you must configure both frequency settings and select a replacement product. The offer will not work if either is missing.

## Step 5: Customize your offer messaging

Make it clear to customers that they're replacing their one-time purchase with a subscription:

1. Edit the offer title to something like: "Switch to subscription and save"
2. Update the description to highlight benefits:
   * "Never run out - get automatic deliveries"
   * "Save 15% on every order"
   * "Cancel anytime, no commitment"
3. Customize the accept button text (e.g., "Switch to Subscription")

## Step 6: Configure funnel settings

⚠️ **Critical**: To avoid issues with multiple subscription offers:

1. Ensure only **one subscription replacement offer** can trigger per order
2. If you have multiple offers in your funnel, place the subscription replacement offer first
3. Consider using conditional logic to prevent other subscription offers from showing after a replacement is accepted

## Step 7: Test your replacement upsell

Before going live, test the replacement flow:

1. Enable **Preview Mode** in the Aftersell app
2. Place a test order with the one-time purchase product
3. Complete checkout and verify the replacement offer appears
4. Accept the offer and confirm:
   * The one-time product is replaced with the subscription
   * The subscription is created in your subscription app
   * The order reflects the subscription item

## Step 8: Activate your funnel

Once testing is complete:

1. Disable Preview Mode
2. Set your funnel status to **Active**
3. Monitor performance in the Analytics tab

## How replacement upsells work

When a customer accepts a replacement upsell:

* The original one-time purchase product is **removed** from the order
* The subscription version of the product is **added** to the order
* A subscription is created using the selected selling plan
* The customer is charged for the first subscription cycle
* Future recurring orders are created automatically by your subscription app

## Important notes

* **One subscription per order**: If a customer accepts a subscription replacement, subsequent offers in the funnel will no longer include subscription options
* **First cycle discounts**: If you apply a discount to the replacement offer, it only applies to the first subscription cycle. Recurring orders will not include the discount
* **Fulfillment**: The subscription item follows your standard fulfillment process for the first order
* **Subscription management**: Customers can manage their subscription (pause, skip, cancel) through your subscription app's customer portal

## Troubleshooting

### Replacement offer not showing

* Verify the trigger is configured correctly
* Ensure the original order contains no subscription items
* Check that the product has selling plans enabled in Shopify

### Subscription not created after acceptance

* Confirm your subscription app uses Shopify's Subscription API
* Check that the selling plan is active and properly configured
* Review the order in Shopify Admin to verify the subscription item was added

### Customer charged incorrectly

* Verify the selling plan pricing in Shopify matches your expectations
* Check if any discounts are applied and understand they only affect the first cycle
* Review the "Recurring subtotal" shown in the offer to see future charges

## Subscription replacement in the editor (checklist)

Use this as a final pass in the offer editor—this is the subscription-specific layer on top of a standard replacement upsell:

* **Trigger** must fire only on orders that contain your target product as a **one-time** line item (orders that already include subscription items cannot use this flow).
* In **Upsell Products**, confirm you selected the **same product** as the purchased line item and set **Subscription Only** with the **selling plan** you want; cadence and base pricing come from Shopify.
* Pick the **upgrade type** (frequency only, replacement only, or both) to match your scenario; if you use **Both**, complete frequency fields **and** select a replacement product, or the offer will not work.
* Any **subscription discount** you add applies to the **first billing cycle only**—verify it matches what you intend before activation.
* **Preview** the offer, then place a test order with a one-time purchase of that product to validate the full flow.

## Related articles

* [Subscriptions in post-purchase offers](/aftersell/subscriptions_in_post_purchase_offers)
* [Replacement upsells](/aftersell/replacement_upsells)
* [Post-purchase triggers](/aftersell/post_purchase_triggers)
* [Quickstart guide to Aftersell](/aftersell/quickstart_guide_to_aftersell)