Migrating to Mantle billing
Migrating to Mantle billing is simpler than you might think. Mantle doesn't replace Shopify's Billing API — it wraps it. Your merchants' existing subscriptions stay exactly where they are, in Shopify, and continue to work the same way they always have.
How Mantle billing works
When your app creates a subscription through Mantle, here's what actually happens:
- Your app calls Mantle's API (instead of Shopify's directly)
- Mantle calls Shopify's
appSubscriptionCreatemutation on your behalf - Shopify creates the subscription — just like it always does
- Your merchant approves the charge in Shopify — just like they always do
Subscriptions live in Shopify, not Mantle. Mantle keeps a synchronized copy for analytics, feature gating, and reporting — but Shopify is always the source of truth for billing.
This means:
- Charges are processed by Shopify
- Merchants approve subscriptions in Shopify
- Payouts come from Shopify
- All existing Shopify billing behavior stays the same
What happens to existing subscribers
Nothing. Your existing merchants keep their current subscriptions. There's no disruption, no re-authorization, and no changes to their billing.
When you connect your Shopify Partner account to Mantle:
- Mantle syncs your existing subscription data from Shopify automatically
- Your merchants' current plans, billing cycles, and charges are all preserved
- The next time a merchant changes their plan, it will go through Mantle's flow — but even then, Shopify still handles the actual billing
What actually changes
The only thing that changes is where your app makes API calls. Instead of calling Shopify's Billing API directly, your app calls Mantle's API — and Mantle handles the Shopify API calls for you.
For details on how to integrate, see the Mantle API documentation.
Things to think about
Plan setup
Before integrating, set up your plans in Mantle to match your existing pricing structure. Define your features, usage limits, and any discounts you offer. Mantle will map your existing Shopify subscriptions to these plans.
Usage-based billing
If your app uses usage-based billing, you'll switch from creating usage charges directly via the Shopify API to reporting usage through Mantle's API. Mantle handles creating the charges on Shopify for you.
The key is to swap your old billing code for Mantle's API in a single deployment, so there's no window where both systems could create the same charge. Since each merchant is on their own billing cycle, there's no special timing to wait for — just deploy the switch and it's a clean cutover. Any charges already written to Shopify will continue through their normal billing cycle, and Mantle will pick them up when they clear.
Hosted billing
If you want Mantle to handle the billing UI for your merchants, you can set up Hosted Billing — a fully managed plan selection and account management page with no frontend code required. This is optional — you can also build your own billing UI using Mantle's API.