Skip to main content
This page is the complete mechanics behind Replacement Upsell: how a replacement is processed, which scenarios are supported or silently blocked, the payment and discount rules, the Beta failsafe, and the full troubleshooting catalog. For how to build one, see the Replacement upsells guide.

​
How a replacement is processed

When a customer accepts a Replacement Upsell:
  1. The original one-time line item is refunded in Shopify.
  2. The replacement line item is added to the same order, either as a one-time purchase or a subscription (depending on what you configured).
  3. The customer pays for the replacement on the same order.
  4. Their statement shows two transactions: the refund of the original, and the charge for the replacement. The displayed Accept Offer button reflects the net difference between the two prices.
This is implemented using Shopify’s post-purchase API:
  • For a one-time replacement (different variant, quantity, or product), Aftersell sends an add_variant changeset.
  • For a subscription replacement, Aftersell sends an add_subscription changeset.
  • The original line item is removed via Shopify’s refund API.
Aftersell does not call your subscription app’s API directly for subscription replacements. The subscription is created by Shopify’s native Subscription API and your subscription app picks it up via its own Shopify integration.

​
Supported scenarios

Replacement Upsell supports four scenarios. In each case, the original line item must be a one-time purchase. The replacement can be either one-time or subscription.
  • One-time to one-time, same product, different variant. For example, swap the Twin size for the Queen size.
  • One-time to one-time, same product, different quantity. For example, swap a single bottle for a 3-pack of the same item. Enable Override quantity on the replacement to set the quantity that ships.
  • One-time to one-time, completely different product. For example, swap a starter bottle for a full-size version of a different SKU.
  • One-time to subscription. For example, swap the one-time bottle for a monthly subscription of the same bottle, or for a subscription version of a different product. This is the most common use case.

​
Blocked scenarios

These scenarios are blocked by Aftersell at offer-display time. The offer silently skips if the customer’s order matches any of them.
  • Subscription to one-time. Removing the subscription line item does not cancel the subscription contract in Recharge, Skio, or Loop. The customer would still be billed and also receive the replacement.
  • Subscription to a different subscription. Same root cause as above, plus Shopify’s “one subscription per order” rule blocks adding a new subscription to an order that already contains one.
  • Subscription to subscription variant or frequency swap. Same root cause.
If you need to change a customer’s existing subscription, use Subscription Upgrade instead. Subscription Upgrade modifies the existing contract in Recharge, Skio, or Loop directly, without trying to remove and re-add the subscription line.
Whenever a Replacement Upsell is skipped (a blocked scenario above, an unsupported payment gateway, or a discounted trigger line), Aftersell automatically tries to show the downsell offer in the same funnel instead. Set up a downsell as a fallback whenever you use Replacement Upsell so the shopper still sees an offer.

​
What the customer sees

Understanding the customer’s view prevents the most common support ticket: “Why was I double-charged?”

​
In the post-purchase offer

The Accept Offer button shows the net difference between the original and the replacement. For example, if the customer bought a $30 bottle and you offer a $45 3-pack, the Accept button reads “Add $15.00 to your order.” If the replacement is cheaper than the original, the button reads as a credit. The offer card shows the replacement product’s image, title, and price. The offer card uses the variant-specific image when one is tagged on the variant in Shopify. If the variant has no image tagged, the offer card falls back to the parent product’s first image. This means swapping between two variants of the same product may or may not change the image, depending on whether each variant has its own image set up in Shopify.

​
On the Shopify order after acceptance

The order ends up showing both:
  • The original line item with a refund applied to it.
  • The new line item for the replacement, charged at full price.
The order total reflects the net result, but the customer’s bank statement will show two transactions: one charge for the replacement and one refund for the original. This is how Aftersell processes Replacement Upsell acceptances at the payment level. The net amount matches the displayed Accept Offer button. To reduce confusion:
  • Include a line in the offer copy that explicitly describes the refund-and-replace mechanic. For example: “When you accept, we will refund the original item and charge for the replacement. You will see two line entries on your statement, the net is the upgrade price shown on this button.”
  • Enable Aftersell’s automatic refund-notification email for replacement upsells, which sends the customer a confirmation explaining the refund.

​
In the subscription provider portal (when replacement is a subscription)

If the replacement is a subscription, the customer will see the new subscription in your subscription provider’s customer portal (Recharge, Skio, Loop, Appstle, Smartrr, Stay.ai). The portal is owned by your subscription provider, not by Aftersell. Make sure your subscription provider’s welcome email is configured to send within minutes of acceptance.

​
Compatible subscription platforms

When the replacement is a subscription, Replacement Upsell works with any subscription app that uses Shopify’s native Subscription API. Aftersell does not call provider APIs directly for this flow; the subscription is created by Shopify and your subscription app picks it up via its own Shopify integration. Compatible providers include Recharge, Skio, Loop, Stay.ai, Appstle, Smartrr, Bold Subscriptions (when running on Shopify’s native subscriptions API), and Shopify’s native selling plans. If your replacement target has a prepaid subscription plan configured (for example, every 3 months charged upfront), confirm with your subscription provider that prepaid is supported as a replacement destination. Prepaid handling varies by provider.

​
Payment method requirements

Aftersell explicitly blocks Replacement Upsell on some payment gateways because they cannot reliably support the refund-and-recharge pattern in the post-purchase window:
  • Authorize.net (authorize_net). Authorize.net requires transactions to settle before refunds can be issued, and settlement has a delay, so Aftersell cannot reliably refund the original and add the replacement on the same Shopify order. If Authorize.net is your payment processor, route those customers to Thank-You-page offers instead.
  • Manual payment gateways (manual). This covers cash on delivery, custom payment methods, draft-order checkouts, and any other manual payment processor that does not capture a vaulted authorization. Replacement Upsell needs an active vaulted payment to issue a follow-up charge, which manual gateways do not provide.
When the order’s payment gateway is one of these, Replacement Upsell silently skips the offer. The skip reason surfaces in the Aftersell order browser as “Payment gateway does not support replacement upsells.” For the broader list of payment methods that affect all Aftersell post-purchase offers (not just Replacement Upsell), see Payment Methods.

​
Discount handling

Replacement Upsell has specific behaviour around discounts that catches partners off guard.

​
Discounts on the original line do not carry to the replacement

When Aftersell refunds the original line item, any discount that was applied to it goes with it. The replacement line is charged at the full price (or at your replacement-offer discount, if you configured one), but the customer’s original discount does not transfer. If you want the customer to keep an equivalent discount, configure it on the replacement offer directly.

​
Allow replacement when target has a discount

By default, Replacement Upsell skips the offer if the trigger line carries an order-level discount. This is a protective default to avoid refund-amount mismatches. To allow the offer to fire even when the trigger has a discount, enable the Allow replacement when target has a discount toggle in the offer’s advanced settings. When enabled, the refund covers the discounted price (not the full price), and the replacement is charged according to your offer configuration.

​
First-cycle discount on subscription replacements

When the replacement is a subscription, the discount you configure on the offer applies to the first billing cycle only. Future recurring orders charge at the regular subscription price. The customer sees the recurring price under Recurring subtotal in the offer.

​
Per-variant funnels

A single Replacement Upsell offer targets one specific product and variant on each side. If your subscription plans differ per variant (different sizes, flavours, or prices), you cannot configure one offer that says “swap whichever variant the customer bought to its matching subscription variant.” Each variant pairing needs its own funnel. For example, if you sell a serum in three sizes (Small / Medium / Large) and want each one to swap to its subscription counterpart, you would build three funnels:
  • Funnel 1: trigger = Small one-time, replacement = Small subscription.
  • Funnel 2: trigger = Medium one-time, replacement = Medium subscription.
  • Funnel 3: trigger = Large one-time, replacement = Large subscription.
Aftersell does not currently include a built-in variant pairing feature, so each variant pair needs its own funnel.

​
Analytics and reporting

Refunds generated by a Replacement Upsell carry the note “AfterSell Post-Purchase Replacement Upsell” in Shopify, which makes replacement-related refunds easy to identify. Aftersell analytics do not subtract the refunded amount from the upsell value. Replacing a $100 product with a $200 product is reported as a $200 upsell, not a $100 net.

​
The Beta failsafe

While Replacement Upsell is in Beta, Aftersell tracks errors on each offer and stops showing the offer to new customers once the error count crosses a threshold. This protects you from a widespread misconfiguration silently impacting many customers.
Replacement Upsell Beta failsafe in the Order Browser

​
Configuring the failsafe threshold

The failsafe threshold is configurable in Settings → Replacement Upsells. It counts replacement errors over a rolling 7-day window and pauses replacement upsells once your chosen threshold is reached within that window. You can pick from:
  • Stop on any issue in the past 7 days (recommended, and the default). The offer stops as soon as the first replacement fails within the rolling window.
  • Stop after 3 issues in the past 7 days.
  • Stop after 5 issues in the past 7 days.
  • Stop after 7 issues in the past 7 days (most permissive).
  • Custom reveals a number field where you can enter any whole number from 1 to 100. Use this if your store processes high order volumes and the presets trip too quickly.
Pick a higher threshold if you are confident in the offer’s configuration and want to absorb a few transient Shopify or subscription-provider errors without disabling the offer. Pick a lower threshold if customer-facing failures are high-cost for your store.

​
What trips the failsafe

Any exception in the replacement flow counts as an error within the rolling 7-day window. The most common causes:
  • Shopify rejects the changeset because the checkout has already completed.
  • The replacement product was deleted or unpublished between offer setup and the customer accepting.
  • The selling plan on a subscription replacement was deactivated.
  • A transient Shopify API or subscription-provider outage.

​
When the failsafe trips

When the error count within the rolling 7-day window reaches your threshold, the offer stops being shown to new customers. You’ll know in two places:
  • Home page banner. A warning banner titled “Replacement upsells are paused” appears on your Aftersell home page, with a Review failsafe button linking to Settings → Replacement Upsells.
  • Failsafe status card (Settings → Replacement Upsells). A status card shows a Failsafe tripped (amber) or Not tripped (green) badge, plus your current rolling count and threshold, for example “4 of 5 errors in the past 7 days”.
Because the failsafe uses a rolling 7-day window, it self-heals: once the error count drops below your threshold, replacement upsells resume automatically, no action required.

​
How to reset

You can reset the failsafe yourself from Settings → Replacement Upsells. Once you’ve resolved the underlying issue, click Reset failsafe and confirm in the modal. The rolling error count clears immediately and replacement upsells resume for new orders. (The button is disabled when your current error count is already zero.) Only reset after fixing the root cause, otherwise the failsafe will trip again once the threshold is reached. If you’re unsure what caused the errors, contact support via the in-app chat before resetting.

​
Troubleshooting

Replacement Upsell is a Beta feature that requires manual enablement by Aftersell support. Contact support via the in-app chat to request access. Once enabled, the Replace item in original order with upsell toggle will appear in the offer’s advanced settings.
Three causes:
  • Funnel trigger mismatch. Confirm the trigger product is the same product that is in the test order’s cart.
  • Order already contains a subscription. Replacement Upsell skips any order where the trigger line is a subscription. Use Subscription Upgrade instead in that case.
  • Original line has a discount. By default, Replacement Upsell skips lines with an order-level discount. Enable Allow replacement when target has a discount in the offer’s advanced settings.
A Replacement Upsell offer has three separate product selections in the editor, and they need to be configured consistently for the replacement to fire:
  1. Funnel trigger. Set at the funnel level. Determines which orders see the offer.
  2. Upsell product. Set in the offer’s Upsell Products section. The product that gets added to the order when the customer accepts.
  3. Edit product to replace. Set inside the Replace item in original order with upsell section, by clicking the Edit product to replace button. This is the exact product and variant in the customer’s cart that will be refunded and removed.
The most common configuration mistake: the product to replace does not match the variant that is actually in the customer’s cart. When that happens, Aftersell cannot find a matching line item to remove, and the replacement silently does not fire.To fix:
  • Open the Replacement Upsell offer.
  • Click Edit product to replace and confirm the selected product and variant exactly match the product+variant the customer should have purchased (per the funnel trigger).
  • If you are swapping between variants of the same product (Small → Large), the “product to replace” must point to the Small variant specifically. If you point it to Large or to any variant the customer did not buy, the offer will skip.
  • Save and test with a real low-price order that includes the exact variant you want to swap from.
This is the expected behaviour. The original line is refunded and the replacement is charged, so the customer’s bank statement shows two transactions even though the net amount is the displayed offer price. To reduce confusion:
  • Add a sentence to the offer copy explaining the refund-and-replace mechanic.
  • Enable Aftersell’s automatic refund-notification email for replacement upsells.
  • Train your support team to explain the two-line-entry pattern when a customer reaches out.
Some payment gateways (including Authorize.net and others that batch-settle transactions on a delay) do not permit refunds until the original transaction has settled. Because a Replacement Upsell charges the replacement and refunds the original immediately after checkout, the refund step can fail with the error “Partial refunds are not allowed until the transaction is settled. Please try again later.” Aftersell does not automatically retry the refund after settlement, so you will need to issue the refund manually from the Shopify order once the original transaction settles (typically within 24 hours, depending on your gateway’s settlement schedule). To avoid this scenario, Replacement Upsell is skipped entirely for known unsupported gateways. If you keep seeing it on a supported gateway, contact support so we can investigate.
When Aftersell refunds the original line item, any discount applied to it goes with the refund. The replacement line is charged separately. If you want the customer to retain the discount, configure it on the replacement offer directly using the offer’s discount field.
No. If the original line item in the order is already a subscription, Replacement Upsell will not fire. This is because removing the subscription line item does not cancel the subscription contract in your subscription app; the customer would still be billed and also receive the replacement. To modify an existing subscription (change frequency, swap product, or both), use Subscription Upgrade instead.
Replacement Upsell tracks errors per offer over a rolling 7-day window and stops showing the offer once the error count crosses your configured threshold in Settings → Replacement Upsells (default: stop on any issue in the past 7 days). When the failsafe trips, a “Replacement upsells are paused” banner appears on your Aftersell home page with a Review failsafe link to Settings → Replacement Upsells, where a status card shows your current error count and whether the failsafe is tripped.If errors are no longer occurring, the offer resumes automatically once the rolling 7-day count drops below the threshold. To resume immediately after fixing the issue, click Reset failsafe on that settings page. If you’re unsure of the root cause, contact support via the in-app chat.
The offer card uses the variant-specific image when one is tagged on the variant in Shopify. If the variant has no image tagged, the offer card falls back to the parent product’s first image. If you are swapping between variants of the same product and the image is not changing, confirm that each variant has its own image set up in Shopify.
Build one funnel per variant. Each funnel has a product+variant trigger and a corresponding replacement product+variant. Aftersell does not currently include a built-in variant pairing feature.
Same failure mode as Subscription Upsell: most often a selling plan was deactivated between the offer rendering and the customer accepting. Shopify accepts the changeset but no subscription is enrolled downstream. Confirm the selling plan is still active in Shopify and assigned to the replacement product. Check your subscription app’s order import or webhook logs for the affected order. If the subscription is missing, your subscription app’s support team can usually manually enroll the customer.
Aftersell does not manage subscription cancellation. Cancellation of future cycles happens in your subscription provider’s customer portal or by the customer themselves. The Shopify refund mechanism for the first cycle works the same as any other line item.
This is expected. Authorize.net is explicitly blocked from Replacement Upsell in Aftersell’s code because it requires transactions to settle before refunds can be issued, and settlement has a delay that breaks the refund-and-recharge pattern Replacement Upsell relies on. Run Thank-You-page offers for Authorize.net customers as an alternative. You can confirm this is the cause by opening the order in the Aftersell order browser; the skip reason will read “Payment gateway does not support replacement upsells.”
Manual payment gateways (cash on delivery, custom payment methods, draft-order checkouts) are explicitly blocked from Replacement Upsell because they do not vault a card for follow-up charges. The order browser will show “Payment gateway does not support replacement upsells” as the skip reason. For broader payment-method limitations on post-purchase offers, see Payment Methods.