--- title: Migrate to Shopify App Pricing description: >- Learn how to migrate apps from Managed Pricing or the Billing API to Shopify App Pricing. source_url: html: >- https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migrating-to-shopify-app-pricing md: >- https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migrating-to-shopify-app-pricing.md --- # Migrate to Shopify App Pricing Use this guide to move an app that bills merchants with the Billing API to Shopify App Pricing. With Shopify App Pricing, Shopify hosts plan selection, charge approval, metering, and invoicing for you. You prepare and test your new plans first, and then move existing subscriptions without interrupting their charges. Your steps depend on how your app bills today: * **Billing API (legacy)**: Prepare and test Shopify App Pricing plans, switch billing systems, and then move your existing subscriptions. Refer to [For apps on manual pricing](#for-apps-on-manual-pricing-billing-api). * **Managed Pricing apps**: Managed Pricing is now Shopify App Pricing. Billing continues without interruption, but you need to update how your app reads subscription data. Refer to [For apps already on Shopify App Pricing](#for-apps-already-on-shopify-app-pricing). *** ## New API overview Three APIs support Shopify App Pricing: | API | Purpose | Authentication | URL | | - | - | - | - | | [Active Subscription API](https://shopify.dev/docs/api/partner/active-subscription) | Query an app user's current plan, billing cycle, and subscription items | [Partner API client credentials](https://shopify.dev/docs/api/partner#authentication) | `partners.shopify.com/{org_id}/api/{version}/graphql.json` | | [Historical Events API](https://shopify.dev/docs/api/partner/historical-events) | Query a timeline of installs, charges, earnings, and subscription changes | [Partner API client credentials](https://shopify.dev/docs/api/partner#authentication) | `partners.shopify.com/{org_id}/api/{version}/graphql.json` | | [App Events API](https://shopify.dev/docs/api/app-events) | Send usage events for billing meters and custom tracking | [Dev Dashboard client credentials](https://shopify.dev/docs/api/app-events#authentication) (JWT) | `api.shopify.com/app/{version}/events` | `{org_id}` is the organization ID in your Partner Dashboard URL. `{version}` is a [supported API version](https://shopify.dev/docs/api/usage/versioning). *** ## Migration at a glance | If your app uses | Code changes | Plan changes | Existing subscriptions | | - | - | - | - | | [Managed Pricing or Shopify App Pricing](#for-apps-already-on-shopify-app-pricing) | Use the Partner API for subscription data | None | None | | [Billing API: monthly or yearly charges](#for-apps-on-manual-pricing-billing-api) | Add the new APIs | Review the draft plans that Shopify generates | Move them in the [Partner Dashboard](#step-5-move-existing-subscriptions) or with [Shopify CLI](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api) | | [Billing API: usage-based charges](#for-apps-on-manual-pricing-billing-api) | Add the new APIs and the [App Events API](https://shopify.dev/docs/api/app-events) | [Set up events, meters, and usage prices](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges) | Move them with [Shopify CLI](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api) | | [Billing API: one-time charges](#for-apps-on-manual-pricing-billing-api) | Add the new APIs | Model each charge as usage in a [usage-only](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges) or [combined](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/combined-subscription-and-usage) plan | Existing one-time purchases stay on the Billing API | *** ## For apps already on Shopify App Pricing Your plans, plan selection page, [redirection URL](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#redirection-url), and existing subscriptions don't change. Update the following parts of your app: * **Subscription checks**: Replace GraphQL Admin API checks, such as `billing.check()` and `currentAppInstallation`, with [Partner API queries](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#query-subscription-data). * **Subscription changes**: Shopify App Pricing doesn't send Billing API webhooks. Read the [URL redirect parameters](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#url-redirect-parameters) after an app user selects a plan, and query the Partner API for changes that happen outside a redirect. If your app still has Billing API subscriptions from before it switched, then move them as described in [Step 5](#step-5-move-existing-subscriptions). For authentication, rate limits, and the full schema, refer to the [Partner API reference](https://shopify.dev/docs/api/partner). *** ## For apps on manual pricing (Billing API) You prepare and test Shopify App Pricing plans before you switch. Preparing plans doesn't change your live plans or existing subscriptions. **Subscription checks during migration:** The [Active Subscription API](https://shopify.dev/docs/api/partner/active-subscription) returns both Billing API and Shopify App Pricing subscriptions, so you can use it to check subscription status before and after you switch. One-time purchases aren't subscriptions. If existing one-time purchases grant access, then keep checking them with [`currentAppInstallation`](https://shopify.dev/docs/api/admin-graphql/latest/queries/currentAppInstallation). Before you start, review Shopify App Pricing's [limitations](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#limitations), and note your current plans, trials, [welcome links](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#redirection-url), and usage charges. ### Step 1: Start plan setup 1. From your Partner Dashboard, click **App distribution** > **All apps**, and select your app. 2. Click **Distribution**. 3. Beside **Shopify App Store listing**, click **Manage listing**. 4. Under **Published languages**, click **Edit** for a locale. 5. Under **Pricing content**, click **Manage**. 6. In the **Update to App Pricing** section, click **Get started**. Shopify generates draft plans from your eligible manual plans the first time you start. To regenerate them after deleting every plan, click **Generate plans**. ### Step 2: Review your plans Shopify doesn't verify that generated plans match your pricing, so review each one: * Confirm the `plan_handle`, billing interval, price, free trial, welcome link, features, and store targets. * Complete every plan marked **Action needed**. * Add usage configuration to usage-based plans. It isn't copied from manual plans. * Add any plans that Shopify skipped, such as plans above the [plan limits](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/plans). You can have up to eight public plans and unlimited private plans. To move subscriptions in the Partner Dashboard later, keep exactly one public plan for each recurring price, currency, and billing interval that existing subscriptions pay. ### Step 3: Test your plans On a [development store](https://shopify.dev/docs/apps/build/stores/development-stores) in your Partner organization: 1. Open your app, and go to its [plan selection page](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#plan-selection-page). 2. Subscribe to a draft plan, and complete the approval and redirect. 3. Verify the price, interval, trial, welcome link, and `plan_handle` URL parameter. 4. Query the [Active Subscription API](https://shopify.dev/docs/api/partner/active-subscription) to confirm the subscription. 5. For usage-based plans, send App Events and confirm that the right meters record usage. Repeat for each plan that you'll publish. ### Step 4: Enable Shopify App Pricing Before you switch, confirm the following: * Every plan's **Action needed** status is resolved. * You have no more than eight public plans, and no more than one free public plan without usage charges. * You've tested each plan on a development store. * If you use usage-based billing, then both your Billing API and App Events integrations work. Check **I've verified my app is ready to switch to Shopify App Pricing**, and then click **Enable Shopify App Pricing**. New subscriptions now use your Shopify App Pricing plans. Existing subscriptions keep billing through the Billing API until you move them. Keep your Billing API integration, including usage records, running until none remain. ### Step 5: Move existing subscriptions Move subscriptions in the Partner Dashboard when their recurring price matches one public plan. Use [Shopify CLI](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api) for everything else: usage-based subscriptions, price adjustments, and moves to private plans. 1. Go to **Pricing content** for your app, as in [Step 1](#step-1-start-plan-setup). 2. In the **Review and assign new plans** section, review each row. A row groups subscriptions with the same charge name, price, currency, and interval, and shows the plan they'll move to. To get the row's merchant list by email, request its CSV. 3. Uncheck any rows that you want to keep on the Billing API. 4. Click **Move selected to Shopify app pricing**, review the summary, and then click **Move selected**. Shopify flags billing-term changes so that it can notify merchants, but you're responsible for making sure that each plan assignment is correct. A subscription with an active discount can't move until the discount ends. *** ## After you move subscriptions These details apply to moves made in the Partner Dashboard and with Shopify CLI. ### When the change takes effect A move is scheduled, not immediate. Each subscription changes to its new plan at the start of its next billing cycle, or at its next renewal for annual plans. If the move changes billing terms, or you send an opt-out notice, then the merchant gets at least 30 days before the change. When the next billing cycle or renewal is less than 30 days away, the subscription stays on its current terms for one more billing period, which is another year for annual plans. Keep your Billing API integration running until the change takes effect. To check each store's status and effective date, use the `list` command in [Shopify CLI](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api). If the move changes billing terms, such as the recurring fee, usage charges, or spending limit, then Shopify emails the store owner when the move is scheduled. The email compares the current and new terms and gives the date of the change. Otherwise, Shopify doesn't email the merchant unless you request a notice with Shopify CLI. A merchant who doesn't want the change can cancel their app subscription before it takes effect, which also cancels the move. With Shopify CLI, you can send an [opt-out notice](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api#opt-out-notifications) instead. ### Cancel a scheduled move Before a change takes effect, you can cancel it with Shopify CLI, including moves made in the Partner Dashboard: 1. Run `shopify app subscription-migrations list --status SCHEDULED > scheduled.csv`. 2. Create a CSV with only a `shop_id` column for the stores that you want to keep on the Billing API. 3. Run `shopify app subscription-migrations unschedule --input --watch`. If a canceled subscription can move in the Partner Dashboard, then it reappears there so that you can move it later. Move the rest with Shopify CLI. Shopify doesn't email merchants about the cancellation, so tell anyone who already received a notice. After a subscription changes to its new plan, you can't undo the move. ### What your app sees When the change takes effect: * The merchant's Billing API [`AppSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscription) keeps its status, takes the moved subscription's recurring price and interval, loses its capped amount, and triggers an [`APP_SUBSCRIPTIONS_UPDATE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#enums-APP_SUBSCRIPTIONS_UPDATE) webhook. * The [Active Subscription API](https://shopify.dev/docs/api/partner/active-subscription) keeps returning the subscription, now with the original `AppSubscription` ID in `legacySubscriptionId`. * Report usage for the subscription with the [App Events API](https://shopify.dev/docs/api/app-events). *** ## Next steps * Learn more about [Shopify App Pricing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing). * Set up [usage-based pricing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges). * [Migrate subscriptions with Shopify CLI](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/migration-api). ***