App subscription behaviour + upgrade/downgrade after app reinstall

Partner Discussions
1

Hello!

I use the Billing API for creating app subscriptions. My app is in review currently, and this is what I got as an issue from the reviewer:

" 8. New . Your app must allow merchants to upgrade and downgrade their pricing plan without having to contact your support team or having to reinstall the app. This includes ensuring that the charges are successfully processed in the application charge history page in the merchant admin. We attempted to change between plans, but after clicking ‘Edit Subscription’ we cannot see the button or option on where we can change plans. "

This happened because the app was already uninstalled and reinstalled, which caused the subscription to cancel:

  1. App installed.
  2. Subscribed.
  3. App uninstalled. (subscription cancelled automatically).
  4. Reinstalled: app is usable until the end of the started billing period.

Merchant could not upgrade or downgrade plans, because the subscription is cancelled already.

Is this the correct behaviour? Should I be able to change plans for an already canceled subscription? Should I cancel the subscription programmatically if the user uninstalls the app, or will Shopify take care of it?

Thanks,
Ottó

2

@Otto_dr_Radics When a merchant uninstalls an app, Shopify immediately cancels the billing plan for that app. If the merchant reinstalls the app, we treat it as a fresh installation and ask the user to choose a pricing plan again during onboarding. In addition, we will integrate a self-service plan administration interface into the app, allowing merchants to upgrade or downgrade their plan without having to reinstall or contact support. If the merchant was previously on the Pro plan and chooses a lower-tier plan, we display a confirmation screen informing them of the benefits they would lose.

3

Thank you for the answer! According to the documentation, “Merchants can reinstall and use the app for the remainder of the billing period.” – how do you handle this with your current flow? E.g.:

  1. Jan. 1.: App installed, 1 year plan selected.
  2. Febr. 1.: App uninstalled, subscription cancelled, will expire on Dec 31.
  3. Febr. 2.: App reinstalled: merchant has an active subscription which expires on Dec 31.

How could I satisfy both of the following requirements:

A. “When an app is uninstalled, Shopify automatically cancels the subscription. A credit isn’t applied to cover the cost of the rest of the billing period. Merchants can reinstall and use the app for the remainder of the billing period.” (About subscription billing)
B. “Your app should provide the option for merchants to resubscribe to any plans after reinstalling the app. Even if the subscription is canceled, merchants must have the ability to resubscribe or change between pricing plans after reinstall.”

Because of A, the current subscription is canceled, it must be available for the remainder of the billing period, no credit should be issued. But because B, I could not cancel the subscription, because if I do it, merchant can’t switch between plans after reinstall.

:scream:

1 Like
4

Hey @Otto_dr_Radics,

Just to help clarify a few scenarios here:

  • For the scenario when a merchant wants to change a plan. The best approach here is to direct them to your billing page and create the new subscription when it’s selected. It’s only possible for a merchant to have a single charge, so once they pick a new plan and approve the charges, that will cancel the previous charge, and we will prorate the difference.
  • For the Scenario where a merchant uninstalls your app and then reinstalls, upon installation you should redirect to the billing page so the merchant can select a plan and ensure their subscription can continue (as the current plan will be cancelled at the end of the billing cycle if not)

For both of the requests above, you can use the replacementBehaviour when creating the subscription to control when the newly accepted charges will be applied: AppSubscriptionReplacementBehavior - GraphQL Admin

5

Hey @KyleG-Shopify!

Thank you for the quick response!

For the first scenario (plan switching), I think I already have a solution: I post a Grapql query, which returns a redirect URL, where I redirect the merchant so they can approve the subscription:

mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!, $test: Boolean!) {
  appSubscriptionCreate(name: $name, replacementBehavior:APPLY_IMMEDIATELY, returnUrl: $returnUrl, lineItems: $lineItems, test: $test) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
    }
    confirmationUrl
  }
}

For the second scenario (resubscribe when a subscription is already in place and cancelled), I could use the “same” query, and the rest will be handled by the Billing API? This sounds cool.

So in this scenario:

  1. Jan. 1.: App installed, 1 year plan selected.
  2. Febr. 1.: App uninstalled, subscription cancelled, will expire on Dec 31.
  3. Febr. 2.: App reinstalled: merchant has an active subscription which expires on Dec 31.

I could send the same query, but with an e.g. monthly plan:

  1. Febr. 2.: Merchant subscribes to a monthly plan.

In this case, the new subscription would start at the end of the current subscription, so the expiration date would be 12+1 months after the initial subscription?

6

Actually, for your second scenario, the monthly plan will be activated immediately. The expiration date will be one month after the start of the new monthly subscription.

7

@Eric_Han Thanks! So the 1 year subscription would be substituted by the 1 month subscription? Will Shopify automatically prorate the difference?

8

yeah. That’s exactly what you said. you can query the current plan and check the period

9

yeah. That’s exactly what you said

So Shopify will prorate the remaining time on the subscription, even after the previous subscription has already been cancelled?

you can query the current plan and check the period

And what could I do with it? Grant a trial period for the already paid period, if Shopify doesn’t prorate the previous subscription?

10

Not necessarily. If a merchant selects an annual plan initially and then switches to a monthly plan, if the currency of the plans are the same the monthly plan will start when the annual plan ends.

The above document I shared on replacement behaviour explains the standard behaviour for different scenarios like this.

11

I’ve encountered a similar situation regarding app subscription behavior after reinstallation. Specifically, when a merchant:

  1. Subscribes to a discounted annual plan.
  2. Later uninstalls the app, canceling the subscription.
  3. Reinstalls the app and selects a monthly plan.
  4. Shopify then issues a prorated refund for the unused portion of the annual plan and activates the monthly plan immediately.

This sequence seems to bypass the intended behavior of APPLY_ON_NEXT_BILLING_CYCLE, which typically maintains the current plan until the billing cycle ends during direct plan changes.

I previously raised this concern in another thread:

Has anyone found a way to handle this scenario effectively within Shopify’s billing framework?

12

Hey @abueler!
I recently looked in to something similar on this thread here. I know it’s not exact, but I did spend time looking in to the expected replacement behaviours.

There shouldn’t be any proration when APPLY_ON_NEXT_BILLING_CYCLE is applied. Can you share an example of where you have seen different? I’d be happy to look in to that.

13

Hi @KyleG-Shopify,

Thanks for the reply. I’ve encountered this issue multiple times now, where APPLY_ON_NEXT_BILLING_CYCLE doesn’t behave as expected and results in unintended proration and revenue loss.

It only happens when a merchant uninstalls and reinstalls the app before switching to a new plan - rather than doing a direct downgrade.

If you follow these steps, you should be able to reproduce it:
1. Subscribe to an annual plan
2. Uninstall the app to cancel the subscription
3. Reinstall the app and select a monthly plan
4. Although using APPLY_ON_NEXT_BILLING_CYCLE, the message in the subscription approval screen will not show:
“This subscription will replace your current subscription at the end of the current billing cycle.”
5. The new monthly plan becomes active immediately
6. Shopify issues a prorated refund for the unused portion of the annual plan

Let me know if you’d like specific store examples, happy to share privately.

14

Thanks, @KyleG-Shopify! STANDARD seems to be the best for my use case. Please, confirm, that:

  1. If the merchant switches between monthly plans, the change is immediate, and proration occurs.
  2. If the merchant switches between annual plans, the change is deferred until the next billing cycle.
  3. If the merchant changes from monthly to annual, the change is immediate, and proration occurs.
  4. If the merchant changes from annual to monthly, the change is deferred until the next billing cycle.

@abueler Thanks for pointing out the issue with APPLY_ON_NEXT_BILLING_CYCLE! Why/what edge case made you to choose this replacement behavior? Trying to sort out any oversight from my part, regarding the STANDARD replacement behavior.

15

Hey Otto,

You have that mostly correct:

  • For switching between monthly plans: Yes, the change would be immediate with proration.
  • For switching between annual plans: This depends on the value. If switching to a higher-value annual plan, the change is immediate. If switching to a lower-value annual plan (using the same currency), the change is deferred until the next billing cycle.
  • For changing from monthly to annual: Yes, the change would be immediate with proration.
  • For changing from annual to monthly: Yes, this would be deferred until the next billing cycle (assuming same currency).
16

Thanks for sharing that. I would like to see some examples so I can look in to that closer. I’ll send you a DM.

17

Thank you, this seems fine to me, I’ll settle with it.

1 Like