Added a usage meter to an existing App Pricing plan. How do current subscribers get it?

Our app bills through Shopify App Pricing. We recently added a usage meter to a plan that merchants were already subscribed to: a graduated meter with the first units of each cycle free, then a small per-unit price above that.

Partner support confirmed what the docs say: editing a plan does not change existing subscription contracts. Each merchant on the old version of the plan keeps a contract with no meter item, so their usage can never be billed. Support said the merchant would “select the plan again” on the plan selection page to get the updated terms.

We tested that and it does not work, so I am looking for the supported path.

What we tested

On a development store, with a private copy of the plan on our development app:

  1. The store subscribed to the plan before the meter existed. The Partner API activeSubscription read showed one flat-rate item and no meter item.
  2. We added the meter to the plan in the Partner Dashboard. The plan selection page then showed the merchant’s plan as “Current” with the usage tiers listed on the card, but with no button. Nothing on the page lets the merchant approve the new terms of the plan they are already on. A second activeSubscription read was identical to the first: the contract was unchanged.
  3. The only way to get the meter onto the store was to select a different plan and then select this plan again. That created a new contract, which now carried the meter item, and it also started a new trial on the test store.
  4. Changing the meter’s per-unit price later changed the plan card and nothing on the contract.

So for every merchant who subscribed before the meter went on, the meter is invisible to billing until they go through a plan switch and back, with whatever proration, cycle reset and trial handling that implies.

Questions

  1. What is the supported way to put the current version of a plan, meter included, onto an existing App Pricing contract? Is there a way to ask a merchant to approve updated terms for the plan they are on, given the plan page marks it “Current” with no action?
  2. If we delete the plan and recreate it with the same name and handle, does the page then offer it to existing subscribers as a selectable plan? Does that affect the App Store listing or trigger a review? Is delete-and-recreate the intended way to handle a pricing or usage charge change on a plan with subscribers?
  3. When a merchant approves a fresh contract for the same plan mid-cycle, does Shopify prorate the recurring fee, does a new billing cycle start that day, and does the trial-day tracking prevent a second trial?
  4. The new subscription migration tooling (shopify app subscription-migrations) is documented for moving Billing API subscriptions onto App Pricing. Can it also take an App Pricing contract as a source, so an existing contract moves to the current plan terms at its next cycle without re-approval?

Has anyone shipped a meter or a price change on a plan with existing App Pricing subscribers? What did you do for the merchants who were already on it?

Hey Jeff, thanks for the questions:

  1. A subscription keeps the terms it was created with. Editing a plan, including adding a usage meter or changing a meter price, doesn’t change existing subscriptions. To get the meter, the merchant has to approve a new subscription. The plan selection page doesn’t let a merchant re-approve the plan they’re already on, so they need to select a different plan. Usage you send before the merchant approves can’t be billed, because the old subscription has no meter.

The simplest option is to create a new plan that includes the meter and ask existing subscribers to select it. We’re looking at ways to enable App Pricing plans to be migrated to other App Pricing plans in a more proactive way.

  1. Deleting a plan doesn’t move its subscribers. They stay on the terms of the deleted plan. A recreated plan is a new plan, even with the same name, so selecting it is a normal plan change. I wouldn’t use delete and recreate for this. A new plan next to the old one gives you the same result.

  2. When a merchant moves to a plan at the same or a higher price, the change is immediate. Shopify ends the old subscription, credits the unused part of the recurring fee, and starts a new billing cycle that day. Trials are tracked per app over a 180-day period. The merchant gets the plan’s trial days minus any trial days they used in the last 180 days. So a merchant can get some or all of a trial again.

  3. No. shopify app subscription-migrations only moves Billing API subscriptions onto App Pricing. It doesn’t accept an App Pricing subscription as a source, though we are looking at making that possible.

Sorry for any merchant friction you might have and am interested in your thoughts.

-Chris O

Thanks Chris, that matches what we heard from partner support.

For now we plan to move older subscribers onto a private plan at the same price that includes the meter, which they approve on the plan page.

Can you confirm that route works as we expect? The private plan has the same recurring price as the public plan, no trial days, and a graduated meter (the first tier of units at $0). When the merchant approves it mid-cycle, we expect:

  • the change to apply right away
  • the unused part of the old fee to be credited
  • a new billing cycle to start that day
  • the meter to be active from approval
  • the meter’s free tier to count from zero on the new subscription

Thanks again for the information. Looking forward to seeing how the App Pricing features evolve.