Shopify App Pricing activeSubscription questions

Shopify App Store
,
1

Hi, we’re a public app on Shopify App Pricing (enrolled before April 2026) and are moving our subscription checks to the Partner API’s activeSubscription and Historical Events. Three questions about production (non-development) stores:

  1. If a merchant whose paid monthly cycle is still running selects the same paid plan again, either after choosing our free plan or after uninstalling and reinstalling, is the new cycle charged in full? Are the unused days of the previous cycle credited back to them?
  2. When a merchant downgrades from a paid plan to our free plan (deferred to the end of the cycle), what does activeSubscription return during the remaining paid period: cancelAtEndOfCycle: true, a pendingUpdate with the free plan, or free-plan items that keep the paid cycle’s currentBillingCycle dates?
  3. What does activeSubscription return for a frozen subscription (store billing problem): null, or the unchanged subscription? Thanks!
2

Hi @Mircea_Piturca, for production stores:

  1. Re-selecting the same paid plan while its original billing cycle is still running starts a new billing cycle. The new cycle is charged in full, and a prorated credit for the unused portion of the previous cycle is applied to the merchant’s Shopify account.

  2. During a deferred paid-to-free change, activeSubscription continues to return the current paid plan in items, including its pricing, along with the existing currentBillingCycle dates. cancelAtEndOfCycle is false, while pendingUpdate.items describes the free plan that will take effect next. cancelAtEndOfCycle becomes true when renewal is turned off, such as after an uninstall or cancellation.

  3. A frozen subscription does not make activeSubscription return null; it continues to return the existing subscription details. Because the query has no subscription-status field, use Historical Events to detect SUBSCRIPTION_FROZEN and SUBSCRIPTION_UNFROZEN.

Hope that helps, let me know if you require any clarification.

3

Thank you for the prompt reply @Paige-Shopify . I appreciate it!

4

From my understanding, it behaves more like a new subscription cycle after the previous subscription has been cancelled, rather than preserving the unused days automatically. However, I wouldn’t assume the Shopify store-plan behavior is exactly the same here.

Shopify’s billing docs indicate that when an existing app subscription is cancelled and the merchant subscribes again, the new billing cycle can start as a new cycle. Shopify also supports prorated credits for unused time when cancellation is performed with proration enabled. Shopify

For a deferred downgrade, activeSubscription should still represent the currently active subscription, with cancelAtEndOfCycle: true and/or a pendingUpdate describing the plan that will apply at the next billing cycle. Shopify documents pendingUpdate specifically as changes that will be applied at the next billing cycle. Shopify

For frozen subscriptions, I’d be cautious about assuming activeSubscription returns null; the Partner API documentation says null is returned when there is no active managed-pricing contract, while freezing is represented through subscription events. This probably needs to be confirmed with an actual frozen-store test.