Skip to main content
This page collects the detailed rules behind the Subscription Upgrade setup wizard: how prices are derived, how the timing and discount options behave, the eligibility trigger, and why the offer product is a placeholder. For the step-by-step walkthrough, see Setting up subscription upgrades.

​
API key verification states

In Step 1, Test API key validates your token against your provider, checking that it authenticates, holds all required scopes, and belongs to your store. The result shows one of two states:
  • Green tick, “API key verified”. The token authenticated, all required scopes are present, and the token belongs to your store. Continue is enabled.
  • Red cancel icon. The check did not come back clean. The message beside the icon says which of two things happened: your provider rejected the token (revoked, or missing required scopes, and the message names the specific problem), or Aftersell could not complete the check (“Could not verify the API key. Please try again.”), which is a failed call rather than a bad token. Fix the token if it was rejected; otherwise just test again.
There is no third, softer state, and a could-not-verify result looks exactly like a rejection, so read the message rather than the icon. Continue stays disabled until the check comes back green. Editing the provider or the token clears the previous result, so re-test after any change. This gate exists to prevent subscription upgrade failures that would otherwise only surface after a customer has been charged.

​
The eligibility trigger: Variant on subscription

The wizard automatically wires a single trigger for you; you do not need to set it up by hand: All enabled triggers use AND logic: every condition must be met for the funnel to show. You can layer additional optional triggers on top in the funnel editor’s Triggers step (grouped under a collapsible Additional triggers section that shows a count and opens automatically when optional triggers are set).
Don’t replace this with a Product trigger plus a Subscription trigger. That older combination is two independent conditions, so an order containing your trigger product as a one-time purchase alongside an unrelated subscription item satisfies both: the funnel fires, and the upgrade then fails downstream because there is no matching subscription to change. Variant on subscription is a single condition that can’t come apart that way, and the wizard migrates older funnels off the combo automatically.
Without a product-specific trigger, a funnel may show to customers who don’t have the eligible subscription product in their order. That wastes impressions and produces a subscription modification that silently fails: the offer product is added to the order, but no subscription is changed in Recharge, Skio, or Loop.
If Show this funnel for all customers is enabled, it overrides all other triggers and the funnel fires for every checkout. This is not recommended for subscription upgrade funnels.

​
Which price the Recurring subtotal shows

The Recurring subtotal in the offer tells the customer what their next renewal will cost. Which product that price is taken from depends on the upgrade type: This is the most common source of confusion. A frequency-only upgrade keeps the same product by design, so its recurring subtotal can only ever show the trigger product’s price, whatever frequency you set. If you expected a different product’s price there, you most likely want Both, change frequency and replace subscription product instead. The quantity used is taken from Override subscription quantity, which appears only on the replacement types. On a frequency-only upgrade it is always 1.

​
Upgrade timing

By default an upgrade takes effect from the customer’s next billing cycle, keeping their existing renewal date. If the timing option is enabled for your store, a checkbox appears under the frequency fields:
My fulfillment provider ships the upgraded item on the current order
Ticking it starts the new billing interval immediately rather than at the next renewal, and it unlocks the One-time upgrade price field in Step 4.
Aftersell does not change the order the customer just placed. This setting only moves the billing interval. Tick it only if your fulfillment provider is set up to recognize the upgrade’s placeholder product and ship the upgraded item on the current order.
This checkbox is off by default and is not available on every store. It appears only on the Change delivery or billing frequency and Both, change frequency and replace subscription product upgrade types, and only once the option has been enabled for your store. Contact support through the in-app chat if you need it.

​
Recurring discount

An optional incentive applied to every future renewal of the upgraded subscription (not just the first cycle). Not available for the add-item type. How the field appears depends on whether the selected selling plan has stepped pricing policies:
  • When a selling plan with discount tiers is selected (for example, a Loop plan that applies $20 off on the first charge and $10 off from the second charge onward), the free-entry field is replaced by a list of radio buttons, one per tier. Each option shows the discount amount and the charge range it applies to (for example, “Charge 1” or “Charge 2 onward”). Select the tier to apply to every future renewal.
  • When no selling plan is selected, or the selected plan has no discount tiers, the standard free-entry field appears. Enter the amount and choose Percentage or Fixed amount.

​
One-time upgrade price, by upgrade type

The One-time upgrade price is what the customer pays on this Shopify order when they accept.
  • On the Change delivery or billing frequency and Both types it is locked at 0 by default, because your subscription provider charges at the end of the current billing cycle and the placeholder product appears on the Shopify order at $0.00. It becomes editable only when the upgrade-timing checkbox in Step 3 is ticked.
  • On Replace with a different subscription product and Add another subscribable item to subscription the timing checkbox does not apply, so the price field is always editable.
What to put in it depends on the upgrade type:
  • Frequency, replacement, or both: the price difference between the original and the upgraded subscription. The customer keeps their subscription and this charge covers the delta.
  • Add another subscribable item: the charge for the added item on this order. Nothing is being swapped, so there is no difference to compute: this is simply what the customer pays now for the new item, which then recurs with their subscription. See Adding an item to an existing subscription.
First-order discount. An optional discount applied only to this upgrade purchase, entered as a percentage (%) or a fixed amount. It sits beside One-time upgrade price and appears whenever that field is editable, on both the Create new and Pick existing tabs. On the add-item type the field still appears but is always saved as 0; add-item offers never carry a discount, so set the price you want on the offer product instead.

​
Why the offer product is a placeholder

The offer product is a visual placeholder only, not a real product the customer buys. Shopify does not allow a subscription product to be shown as a post-purchase upsell after an order that already contains a subscription, so Aftersell captures the price between upgrades with a non-subscription placeholder SKU instead.
  • The image, title, and price you set appear in the offer card.
  • On accept, the displayed price is charged on the Shopify order and Recharge, Skio, or Loop applies the actual upgrade to the subscription on its next cycle.
  • If you Pick existing instead of creating one, the product must support one-time purchase; subscription-only products are filtered out of the picker.