Managed App Pricing: reading the merchant's plan

Managed Pricing is a genuinely good trade — Shopify hosts the plan page, collects the money, and you delete your Billing API code. What nobody tells you up front is that nothing notifies your app when the plan changes. No webhook. You have to read it.

The three read paths, ranked

1. The redirect parameters (cheapest, and you should persist them)

When a merchant picks a plan on Shopify's hosted page, they're sent back to your app's return URL with the plan appended:

https://your-app.example.com/?shop=store.myshopify.com&plan_handle=pro

Persist plan_handle against the shop the moment you see it. Two notes: use plan_handle, not charge_id — the latter is on its way out. And this only tells you about the transition you just witnessed, so it is a cache, never the source of truth: a merchant who cancels from Shopify's own settings never passes through your app at all.

2. The Partner API Active Subscription query (canonical)

This is the authoritative read, and the only one that reliably reflects a cancellation or downgrade the merchant did without opening your app:

{
  app(id: $appId) {
    activeSubscription(shopId: $shopId) {
      items { handle price { amount currencyCode } }
    }
  }
}

The cost is real: it needs Partner API credentials and your organization ID, and it lives outside the per-shop session you already have in a request handler. Worth it for a nightly reconcile; too heavy for every page load.

3. The Admin API installation query (convenient, undocumented for this)

{
  currentAppInstallation {
    activeSubscriptions {
      name
      status
      lineItems {
        plan { pricingDetails { ... on AppRecurringPricing { price { amount currencyCode } } } }
      }
    }
  }
}

This works today and it works from the session you already have. Be aware you're leaning on behaviour Shopify documents for the Billing API and hasn't committed to for Managed Pricing. Treat it as the fast path, with path 1 as fallback and path 2 as the reconciler.

Gate on price, not on the plan's name

// what the merchant is actually on — drives the UI
const subscribedPro = await readPlan(admin);
// what they're allowed to do — grace keeps review and dev unblocked
const entitled = BILLING_ENFORCED ? subscribedPro : true;

Keep that BILLING_ENFORCED flag off until you have watched detection work against a real paid subscription in production. A billing gate that misfires during App Store review reads to the reviewer as a broken app.

Two things that are not what they look like

The reconcile that closes the loop

1. On every admin request, read path 3 and refresh the stored plan. Cheap, current, covers the vast majority of state changes.
2. On the redirect back from the plan page, write plan_handle. This is what carries you when the Admin read is unavailable.
3. On a schedule, walk your installed shops through path 2. This is the only step that catches a shop that hasn't opened your app since cancelling.
4. When all three disagree, err toward granting access. A merchant wrongly locked out of something they paid for writes a one-star review; a merchant who keeps a paid feature for an extra day costs you nothing.

Related: the real Built for Shopify requirements, and fixing "Translation missing" in an app block.