Migrating from Mantle billing to the Shopify Billing API

Start here

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 high-level, not a turnkey playbook, and the exact work depends on which billing models you use. The Billing API is now considered legacy but it's available today, and it's 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'll be calling:

• appSubscriptionCreate (create a subscription): https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate
• appUsageRecordCreate (report usage): https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate
• appPurchaseOneTimeCreate (one-time charge): https://shopify.dev/docs/api/admin-graphql/latest/mutations/appPurchaseOneTimeCreate
• appSubscriptionCancel (cancel a subscription): https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCancel

What actually changes

• Your existing subscriptions keep running. They live on Shopify (Mantle created them through the Billing API), so they keep billing your merchants with no interruption and no re-approval. You don't recreate them, you just stop having Mantle manage them. This holds for non-flex plans. Flex billing is the exception: the subscription still bills, but everything Mantle automated around it (the tier upgrades and the cycle logic) stops, so see the Flex billing section.
• You take over new subscriptions. For new installs and plan changes, your app calls appSubscriptionCreate itself (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.

By billing model

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 don't re-approve anything. Lightest migration.

Freemium. Same as above for the paid tiers. Free plans never had a Shopify charge, so there's 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've 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're 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. See Flex billing below.

Order of operations

1. Take over the subscribe flow. Have your app create new subscriptions directly with appSubscriptionCreate for new installs and plan changes.
2. Take over usage reporting. For usage plans, start sending usage records to Shopify yourself (appUsageRecordCreate) before Mantle stops, so nothing lapses.
3. Take over the lifecycle. Handle cancellations, plan changes, and Shopify's billing webhooks on your side.
4. 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.

Quick reference

The Billing API pieces you take over:

Flex billing

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 won't 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:

• Rebuild it yourself. Track usage on your side and run the tier logic in your own system, charging through a usage line so upgrades don't need the merchant to re-approve anything. This keeps the flex behavior but is the most work. The next section breaks down exactly how to build it.
• 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 isn't coming back as a managed feature, so it's worth deciding early which way you'll go.

Building flex billing yourself

This is how Mantle implements flex billing under the hood. It's 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 isn't in the recurring line, changing what you charge doesn't require the merchant to approve anything, as long as you stay under the cap.

The engine you build. Three jobs your side owns:

1. Meter usage. Track each merchant's usage (orders, events, whatever your tiers key on) in your own database.
2. 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.
3. 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. When a merchant moves up mid-cycle, charge the difference right away: compute the daily rate for the old and new tiers, multiply the difference by the days left in the cycle, and post that as a usage record. This is exactly what Mantle does today. For downgrades there's no such thing as a negative usage record, so track a credit on your side and net it off the next cycle's charge.

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 won't fit in what's left, that's 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. Record every tier change with the before and after plan, the proration amount, and timestamps. When a merchant questions a charge, this is the first thing you'll reach for. Mantle keeps these as flex billing events for the same reason.

Migrating existing flex merchants over

The good news: your flex merchants already sit on exactly this shape. The $0-plus-usage-line subscription Mantle created lives on Shopify and stays live. You take over posting usage records to it with your own app credentials, no re-approval and no new subscription, unless you want to raise caps.

1. 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.
2. 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.
3. 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.
4. Stop Mantle's charging before September 30, 2026. Once you're posting your own usage records, disconnect billing in Mantle so the two systems never both charge the same cycle.

What about App Pricing?

Shopify App Pricing is where app billing is headed long-term. Two things to know:

• It's only open to new apps today. Shopify is building tooling to migrate existing apps, but the timing isn't confirmed, so don't rely on it being ready before September 30.
• Flex billing likely won't be supported there either. If you're on flex, App Pricing won't bring it back, so you'll need one of the two flex approaches above regardless.

When Shopify's migration tooling is ready, App Pricing becomes the place to land. Until then, the Billing API is the path.