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.
• 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.

Anchor to New API overviewNew API overview

Three APIs support Shopify App Pricing:

{org_id} is the organization ID in your Partner Dashboard URL. {version} is a supported API version.

Anchor to Migration at a glanceMigration at a glance

Anchor to For apps already on Shopify App PricingFor apps already on Shopify App Pricing

Your plans, plan selection page, 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.
• Subscription changes: Shopify App Pricing doesn't send Billing API webhooks. Read the 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.

For authentication, rate limits, and the full schema, refer to the Partner API reference.

Anchor to For apps on manual pricing (Billing API)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.

Before you start, review Shopify App Pricing's limitations, and note your current plans, trials, welcome links, and usage charges.

Anchor to Step 1: Start plan setupStep 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.

Anchor to Step 2: Review your plansStep 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. 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.

Anchor to Step 3: Test your plansStep 3: Test your plans

On a development store in your Partner organization:

1. Open your app, and go to its 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 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.

Anchor to Step 4: Enable Shopify App PricingStep 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.

Anchor to Step 5: Move existing subscriptionsStep 5: Move existing subscriptions

Move subscriptions in the Partner Dashboard when their recurring price matches one public plan. Use Shopify CLI 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.
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.

Anchor to After you move subscriptionsAfter you move subscriptions

These details apply to moves made in the Partner Dashboard and with Shopify CLI.

Anchor to When the change takes effectWhen 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.

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 instead.

Anchor to Cancel a scheduled moveCancel 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 <file> --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.

Anchor to What your app seesWhat your app sees

When the change takes effect:

• The merchant's Billing API AppSubscription keeps its status, takes the moved subscription's recurring price and interval, loses its capped amount, and triggers an APP_SUBSCRIPTIONS_UPDATE webhook.
• The Active Subscription API keeps returning the subscription, now with the original AppSubscription ID in legacySubscriptionId.
• Report usage for the subscription with the App Events API.

Anchor to Next stepsNext steps

• Learn more about Shopify App Pricing.
• Set up usage-based pricing.
• Migrate subscriptions with Shopify CLI.