Migrate to Shopify App Pricing
Managed Pricing is now Shopify App Pricing. If your app used Managed Pricing, then existing subscriptions and billing continue without interruption. You don't need to take action to keep charges processing. However, if your app queries subscription data or handles charge approval redirects, then you need to update those integrations to use the new APIs and URL parameters described in this guide.
If your app uses manual pricing with the Billing API, then you can prepare and test Shopify App Pricing plans without switching billing systems. Switch only after you've reviewed and tested your plans. Preparing plans doesn't change your live manual plans or existing subscriptions.
The plan setup flow moves existing subscriptions that map to one of your new plans. For subscriptions that don't map directly to a new plan, such as usage-based subscriptions or ones whose price doesn't match a plan, Shopify is developing a Migration API. Until it's available, those subscriptions continue billing through the Billing API.
The plan setup flow moves existing subscriptions that map to one of your new plans. For subscriptions that don't map directly to a new plan, such as usage-based subscriptions or ones whose price doesn't match a plan, Shopify is developing a Migration API. Until it's available, those subscriptions continue billing through the Billing API.
Anchor to New API overviewNew API overview
Three APIs support Shopify App Pricing. Access the Active Subscription and Historical Events APIs through the Partner API with Partner API credentials. Access the App Events API with separate credentials from the Dev Dashboard.
| API | Purpose | Authentication | URL |
|---|---|---|---|
| Active Subscription API | Query an app user's current plan, billing cycle, and subscription items | Partner API client credentials | partners.shopify.com/{org_id}/api/{version}/graphql.json |
| Historical Events API | Query a full timeline of installs, charges, earnings, and subscription changes | Partner API client credentials | partners.shopify.com/{org_id}/api/{version}/graphql.json |
| App Events API | Create usage events for billing meters and custom tracking | Dev Dashboard client credentials (JWT) | api.shopify.com/app/{version}/events |
For Partner API URLs, {org_id} is the organization ID shown in your Partner Dashboard URL. In both URL formats, {version} is a supported API version.
Anchor to Migration at a glanceMigration at a glance
If your app used any of Shopify's billing APIs before May 2026, this migration applies to you.
Your migration path depends on which billing system you use today and what you bill for. Find your row in the following table, then follow the linked instructions.
| Current billing system | Code changes | Plan and pricing changes |
|---|---|---|
| Managed Pricing | Switch to the new APIs | None |
| Shopify App Pricing | Make sure that you're using the new APIs | None |
| Billing API: one-time charges only | Add the new APIs, and keep Billing API checks for existing purchases | Create a usage-only subscription with usage items. The next purchase uses this subscription. |
| Billing API: one-time and monthly charges | Add the new APIs, and keep Billing API checks for existing purchases and subscriptions | Create a combined Shopify App Pricing plan with a monthly price and a usage meter. Send each one-time charge as an App Event for that meter. |
| Billing API: simple monthly or yearly charges | Add the new APIs, and keep Billing API checks for existing subscriptions | Review the draft plans that Shopify creates from eligible manual plans and each plan's plan_handle, the identifier passed to your app in redirect URLs. |
| Billing API: usage-based charges | Add the new APIs, and keep Billing API checks and usage records for existing subscriptions | Define events and meters, and set usage prices for each plan. |
If your app uses the Billing API, then complete Steps 1 to 3 in For apps on manual pricing to create, edit, and test a separate set of Shopify App Pricing plans. Complete Step 4 only when you're ready to enable the new plans.
Anchor to For apps already on Shopify App PricingFor apps already on Shopify App Pricing
If you're already using Shopify App Pricing, formerly known as Managed Pricing, then update how your app retrieves subscription data. Query the Partner API instead of the GraphQL Admin API.
Anchor to What's changingWhat's changing
- Subscription queries: Query the Partner API to retrieve subscription status, plan details, and billing information. Refer to query subscription data for the Partner API queries.
- Billing checks: Update code that uses the GraphQL Admin API to check subscription status, such as
billing.check()orcurrentAppInstallationqueries, to use the Partner API equivalents. - Subscription notifications: Shopify App Pricing doesn't send Billing API webhooks for subscription changes. Read the redirect parameters after an app user selects a plan, and query the Partner API for changes that happen outside a redirect.
- Return URL parameters: The return URL includes additional URL parameters after an app user approves a charge. Refer to URL redirect parameters for the parameters that your app should read.
Anchor to What isn't changingWhat isn't changing
- Plan selection integration: The URL and redirect flow to Shopify's hosted plan selection page works the same way. Your redirection URL configuration and redirect flow don't change.
- Plans and pricing configuration: You don't need to change plans that you've already configured in the Partner Dashboard.
- App user experience: Existing app users don't experience an interruption or need to take action.
Anchor to What you should do nowWhat you should do now
- Review where your app queries the GraphQL Admin API for subscription or billing data.
- Identify all code paths that depend on subscription status checks.
- Update your subscription status and history queries to use the Partner API.
For more detail about the Partner API, including authentication, rate limits, error handling, and the full GraphQL schema reference, refer to the Partner API technical reference.
Anchor to For apps on manual pricing (Billing API)For apps on manual pricing (Billing API)
Use the plan setup flow to prepare, edit, and test Shopify App Pricing plans before you enable Shopify App Pricing. The flow begins when you click Get started in Step 1 and creates a separate set of plans.
After you enable Shopify App Pricing, the Active Subscription API returns only Shopify App Pricing contracts. Continue querying currentAppInstallation in the GraphQL Admin API for existing Billing API subscriptions and purchases. If the Active Subscription API returns null, then don't treat the app user as unpaid until currentAppInstallation also confirms that they don't have a Billing API subscription or purchase that grants access.
After you enable Shopify App Pricing, the Active Subscription API returns only Shopify App Pricing contracts. Continue querying currentAppInstallation in the GraphQL Admin API for existing Billing API subscriptions and purchases. If the Active Subscription API returns null, then don't treat the app user as unpaid until currentAppInstallation also confirms that they don't have a Billing API subscription or purchase that grants access.
Anchor to RequirementsRequirements
Before you start, complete the following tasks:
- Review Shopify App Pricing and its limitations.
- Document your current billing configuration, including plan details, pricing tiers, trials, welcome links, and usage-based charges.
- If your app uses usage-based billing, then define your events and meters, and update your app to send usage data through the App Events API. Keep sending Billing API usage records until no Billing API subscriptions remain.
Anchor to Step 1: Start plan setupStep 1: Start plan setup
- From your Partner Dashboard, click Apps > All Apps, and select your app.
- Click Distribution.
- Beside Shopify App Store listing, click Manage listing.
- Under Published languages, click Edit for the locale that you want to update.
- Under Pricing content, click Manage.
- In the Update to App Pricing section, click Get started.
If your app doesn't have Shopify App Pricing plans, then Shopify generates draft plans from eligible manual plans. Shopify runs automatic plan generation only the first time that you start plan setup. If you delete every generated plan, then click Generate plans to generate them again.
Anchor to Step 2: Review and edit your plansStep 2: Review and edit your plans
Review every generated plan before you enable Shopify App Pricing. Shopify doesn't verify that the generated prices or plan configuration match your intended pricing model.
- Confirm each plan's
plan_handle, billing interval, recurring price, free trial, welcome link, features, and store targets. - Edit each plan marked Action needed, and complete its missing configuration.
- Configure events, meters, and usage prices for usage-based plans. The plan setup flow doesn't copy usage configuration from manual plans.
- Add, edit, or delete public and private plans as needed. You can prepare up to eight public plans and 15 private plans.
Shopify might not generate every manual plan. For example, Shopify skips one-time plans and plans above the Shopify App Pricing plan limits. If Shopify skips a plan or can't generate it, then add the eligible missing plan manually.
Preparing draft plans doesn't change the plans that live stores see or how Shopify bills existing subscriptions.
Anchor to Step 3: Test your plansStep 3: Test your plans
You can test draft Shopify App Pricing plans on a development store that belongs to the same Partner organization as your app. Test the complete billing flow before you enable Shopify App Pricing:
- Install or open your app on the development store.
- Redirect to the app's hosted plan selection page.
- Select a draft plan, and complete the approval and redirect flow.
- Verify the plan selection, billing interval, price, trial, welcome link, and
plan_handleURL parameter. - Query the Active Subscription API to verify the subscription state.
- For usage-based plans, send App Events and verify that the correct meters record usage.
Repeat the test for each billing model and plan that you intend to publish.
Anchor to Step 4: Enable Shopify App PricingStep 4: Enable Shopify App Pricing
Before you switch, make sure that you've completed the following tasks:
- Create at least one valid Shopify App Pricing plan.
- Resolve every Action needed status.
- Reduce your plans to the supported limits of eight public plans and 15 private plans.
- Include no more than one free public plan without usage charges.
- Test the subscription flow on a development store.
- If your app uses usage-based billing, then verify both the Billing API and App Events integrations.
Check I've verified my app is ready to switch to Shopify App Pricing, and then click Enable Shopify App Pricing.
After you enable Shopify App Pricing, new subscriptions use your published Shopify App Pricing plans. Existing subscriptions continue billing through the Billing API. Query both billing systems when you determine whether an app user has paid. Keep the Billing API integration running until existing subscriptions end or you migrate them with the Migration API, and for as long as your app needs to recognize existing one-time purchases.
Anchor to Next stepsNext steps
- Learn more about Shopify App Pricing features.
- Set up usage-based pricing with Shopify App Pricing.
- Configure welcome links for your plans.