Mantle Billing Migration: A Shopify Developer's Guide

Migrating from Mantle Billing to the Shopify Billing API is the one wind-down task that sits directly on your revenue, and the good news is it is smaller than it looks. Except for flex billing, Mantle is mainly a wrapper around Shopify’s Billing API: for non-flex plans your subscriptions already live on Shopify, and Mantle just relays the calls on your behalf. Migrating those is about taking over the calls yourself, not rebuilding anything. This guide covers what changes, the mutations you will call, the order of operations, and the one model - flex - where you are genuinely rebuilding logic. Your deadline is September 30, 2026.

Quick answer: For non-flex Mantle plans, your subscriptions already live on Shopify - Mantle only relays the Billing API calls. To migrate, take over those calls yourself (appSubscriptionCreate, appUsageRecordCreate, appSubscriptionCancel) and disconnect Mantle before September 30, 2026. Existing subscriptions keep billing with no re-approval. Flex billing is the one model you rebuild.

What you’ll learn in this article:

• Why Mantle Billing is mostly a wrapper around the Shopify Billing API
• What actually changes when you migrate, and what keeps running untouched
• The Billing API mutations you take over, mapped to what Mantle did
• How the migration differs by billing model (flat, freemium, usage, flex)
• The order of operations to disconnect Mantle safely before Sept 30, 2026
• How to rebuild flex billing yourself, including proration and caps
• Where Shopify App Pricing fits into the long-term picture
  

Start here: Mantle Billing is a wrapper around the Shopify Billing API

​Except for flex billing, Mantle is mainly a wrapper around Shopify’s Billing API. For non-flex plans, your subscriptions already live on Shopify. Mantle just relays the Billing API calls - create the subscription, report usage, cancel - on your behalf, and Shopify owns the subscription and runs the billing cycle. Migrating those is about taking over those calls yourself, not rebuilding anything.

Flex billing is the exception. The logic that decides when each billing cycle starts and ends, when a merchant moves up a tier, and how the next cycle is built is Mantle’s own, layered on top of the Billing API. Shopify has no concept of it, so flex is the one model where you are rebuilding logic, not just taking over calls (see the flex billing section below).

This is a high-level map, not a turnkey playbook, and the exact work depends on which billing models you use. The Billing API is now considered legacy, but it is available today and it is the dependable path before September 30, 2026. For Shopify’s long-term direction, see “What about App Pricing?” at the end.

💡 Shopify’s docs are the source of truth. These are the Billing API mutations you will be calling: appSubscriptionCreate (create a subscription), appUsageRecordCreate (report usage), appPurchaseOneTimeCreate (one-time charge), and appSubscriptionCancel (cancel a subscription).

​​What actually changes when you migrate off Mantle Billing

​Your existing subscriptions keep running. They live on Shopify, because Mantle created them through the Billing API, so they keep billing your merchants with no interruption and no re-approval. You do not recreate them; you just stop having Mantle manage them. Here is what moves to your side:

• Existing subscriptions keep running. This holds for non-flex plans. Flex is the exception: the subscription still bills, but everything Mantle automated around it (tier upgrades and cycle logic) stops.
• You take over new subscriptions. For new installs and plan changes, your app calls appSubscriptionCreate itself and the merchant approves through the confirmation URL it returns, instead of Mantle doing it.
• You report usage yourself. This is the real work. Today you send usage events to Mantle, and Mantle turns them into Shopify usage records (appUsageRecordCreate) against the subscription’s usage line. Once you disconnect, you send those usage records to Shopify directly. If you stop reporting usage, the base plan keeps billing but usage charges stop, so this is the urgent one for usage-based apps.
• You handle the lifecycle. Cancellations, upgrades and downgrades, and Shopify’s billing webhooks all move to your side.
• Flex billing has no Shopify equivalent. The automatic tier upgrades were Mantle’s logic. See the flex billing section.
  

​​The Billing API pieces you take over

​Here is a direct map of what Mantle did for you and the Billing API call that replaces it. This is the whole surface area for non-flex plans.

How the migration differs by billing model

​How much work this is depends entirely on which billing models you run. Find yours below.

• Flat recurring (the common case). Your subscriptions stay live on Shopify as-is. The work is taking over new installs and lifecycle changes with appSubscriptionCreate and the related mutations. Existing merchants do not re-approve anything. This is the lightest migration.
• Freemium. Same as above for the paid tiers. Free plans never had a Shopify charge, so there is nothing to take over there - just keep gating features in your app.
• Recurring plus usage. The subscription and its usage line stay on Shopify. The one thing you must take over before Mantle stops is reporting usage records (appUsageRecordCreate). Take the usage events you have been sending to Mantle and send them to Shopify yourself. Miss this and usage simply stops being billed.
• Flex billing. The auto-upgrade behavior was Mantle watching usage and moving merchants between plans. Existing merchants stay on whatever tier they are on, but the automatic upgrades stop until you rebuild them. Shopify has no equivalent, so you either rebuild that logic yourself or switch to regular tiers.
  

Order of operations

​Work in this sequence so nothing lapses and the two systems never both charge the same cycle.

• Take over the subscribe flow. Have your app create new subscriptions directly with appSubscriptionCreate for new installs and plan changes.
• Take over usage reporting. For usage plans, start sending usage records to Shopify yourself (appUsageRecordCreate) before Mantle stops, so nothing lapses.
• Take over the lifecycle. Handle cancellations, plan changes, and Shopify’s billing webhooks on your side.
• Disconnect Mantle. Once your app is making the calls, you are no longer relying on Mantle. Do this before September 30, 2026. Your existing subscriptions keep billing throughout.
  

Flex billing: the one model you rebuild

​Flex billing - plans that upgrade automatically as a merchant’s usage grows - is something Mantle built on top of the Billing API. It is the one place Mantle runs its own logic: tracking usage within each cycle, deciding when a cycle begins and ends, and moving merchants up a tier when they cross a limit. Shopify has no concept of any of that, and Shopify App Pricing likely will not either. Existing merchants stay on their current tier, but the automatic upgrades stop once Mantle is out of the loop. So you have two choices:

1. Rebuild it yourself. Track usage on your side and run the tier logic in your own system, charging through a usage line so upgrades do not need the merchant to re-approve anything. This keeps the flex behavior but is the most work.
2. Switch to regular plans. Move to standard tiers, or a usage-based line with a cap, and drop the automatic upgrades. Less work, but merchants no longer change tiers on their own.
   

Either way, flex is not coming back as a managed feature, so it is worth deciding early which way you will go.

Building flex billing yourself

​This is how Mantle implements flex billing under the hood. It is all standard Billing API - the trick is in how the pieces are used - so you can rebuild it the same way.

​The shape on Shopify

​A flex subscription is an app subscription with a $0 recurring line plus a usage line with a capped amount. The merchant approves that once. Every real charge, including the tier fee itself, is a usage record (appUsageRecordCreate) against that usage line. Because the price is not in the recurring line, changing what you charge does not require the merchant to approve anything, as long as you stay under the cap.

The engine you build

​Three jobs your side owns:

• ​Meter usage. Track each merchant’s usage (orders, events, whatever your tiers key on) in your own database.
• Decide tiers. When a merchant crosses a threshold, flip their tier in your system. No Shopify call is needed at that moment - you just start charging the new tier’s fee.
• Charge on your cycle. On each merchant’s cycle boundary, post the tier fee as a usage record. Shopify settles usage charges on the subscription’s own 30-day cycle, so your records just need to land inside it.

​Upgrades and proration

​​The cap is the one re-approval point

​You can only post usage records up to the line’s capped amount. If a merchant grows past the cap, or a new tier’s fee will not fit in what is left, that is when you create a new subscription with a higher cap and send them through the confirmation URL. Pick generous caps up front to make this rare.

Keep an audit log

Migrating existing flex merchants over

• ​Export the current state. Which merchant is on which tier, where they are in their cycle, and each usage line’s cap and remaining balance. The subscriptions export covers the Mantle side, and the subscription and usage line IDs are queryable straight from Shopify’s API.
• Build and dry-run your engine. Run your metering alongside Mantle’s for a cycle before cutting over and compare the numbers. Billing bugs are the expensive kind.
• Cut over on cycle boundaries. For each merchant, let Mantle’s last charge complete, then your first usage record covers their next cycle. Cutting over mid-cycle means double-charging or gifting days; the boundary avoids both.
• Stop Mantle’s charging before September 30, 2026. Once you are posting your own usage records, disconnect billing in Mantle so the two systems never both charge the same cycle.

​What about Shopify App Pricing?

• ​It is only open to new apps today. Shopify is building tooling to migrate existing apps, but the timing is not confirmed, so do not rely on it being ready before September 30.
• Flex billing likely will not be supported there either. If you are on flex, App Pricing will not bring it back, so you will need one of the two flex approaches above regardless.

​​Frequently asked questions

​Do my existing Mantle subscriptions break when I migrate?

​​What is the one thing usage-based apps must not miss?

​​Should I just wait for Shopify App Pricing instead?

​​Migrate on the Billing API now, land on App Pricing later

​For most apps, migrating off Mantle Billing is taking over a handful of Billing API calls your subscriptions already depend on - not a rebuild. Take over the subscribe flow, take over usage reporting, move the lifecycle to your side, and disconnect Mantle before September 30, 2026. If you run flex billing, decide early whether to rebuild the engine or move to regular tiers, and cut existing flex merchants over on their cycle boundaries.

Billing is only one part of what Mantle gave you. Its App Store analytics and SASI are winding down too, so if you tracked reviews, ratings, competitor changelogs, and category benchmarks there, keep that visibility as you migrate.