Skip to main content

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.

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)
  • If you use Recharge or Skio, a selling-plan picker appears in the offer edit panel — select the specific selling plan you want to apply to the upgrade
  • (Optional) Enable Apply upgrade at end of current billing cycle (Skio only): when checked, the upgraded subscription takes effect on the customer’s existing next billing date rather than being re-anchored to today’s date. See Apply upgrade at end of current billing cycle below.
  • (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.

​
Use a selling plan to auto-fill frequency settings (beta)

Beta access: This feature is available on request for Recharge users. Contact support to enable it for your store.
When this feature is enabled, a Selling plan (optional) dropdown appears above the frequency fields. Selecting a plan from the dropdown automatically populates the delivery frequency, billing frequency, and recurring subscription discount from that plan, and those fields become read-only.
  • The first-order discount remains editable regardless of which plan is selected
  • Leaving the dropdown empty preserves the standard manual-entry flow
  • If you clear the plan selection, the frequency and discount fields reset to their defaults
This option is only available when using Recharge as your subscription provider.

​
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
  • Click Select replacement product and choose the product to swap to
  • If you use Recharge or Skio, a selling-plan picker appears in the offer edit panel — select the specific selling plan you want to apply to the upgrade
  • (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.

​
Apply upgrade at end of current billing cycle

When using Skio as your subscription provider and the upgrade type is Frequency only or Both, you can enable the Apply upgrade at end of current billing cycle checkbox in the subscription upgrade setup modal or the product-information-widget settings. When this option is enabled, the upgraded subscription takes effect on the customer’s existing next billing date instead of being re-anchored to the date the upgrade is accepted. This means the customer’s billing schedule stays intact — they are not charged sooner than expected, and their next renewal date does not change. When this option is disabled (the default), the new frequency is applied immediately and the next billing date is recalculated from the time of the upgrade. 💡 Tip: Enable this option when you want to avoid disrupting a customer’s existing billing schedule. It is especially useful for upgrades that change the billing interval, where re-anchoring could cause an unexpected early charge. ⚠️ Note: This option is only available when your subscription provider is Skio and the upgrade type is Frequency only or Both. It is not available for Replacement only upgrades.

​
Use a selling plan to auto-fill frequency settings (beta)

Beta access: This feature is available on request for Recharge users. Contact support to enable it for your store.
When this feature is enabled, a Selling plan (optional) dropdown appears above the frequency fields. Select a replacement product first, then choose a selling plan from that product. The plan automatically populates the delivery frequency, billing frequency, and recurring subscription discount, and those fields become read-only.
  • The first-order discount remains editable regardless of which plan is selected
  • Leaving the dropdown empty preserves the standard manual-entry flow
  • If you clear the plan selection, the frequency and discount fields reset to their defaults
This option is only available when using Recharge as your subscription provider.

​
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.