Shopify App Billing Demystified: One-Time Payments, Free Plans & The Managed Pricing Puzzle

Hey there, fellow app developers and store owners! We've all been there, scratching our heads over Shopify's billing nuances. Recently, a super relevant discussion popped up in the Shopify Community that I just had to dive into. It's all about that tricky dance between one-time payments and trying to offer a free plan within your app, especially when you're using credits.

The original question came from @awaisshafi, who perfectly articulated a common dilemma: "Our app is free with optional credit purchases via appPurchaseOneTimeCreate. We cannot use Shopify App Pricing because it blocks appPurchaseOneTimeCreate — we get ‘Managed Pricing Apps cannot use the Billing API’. We also cannot create a $0/month recurring subscription via appSubscriptionCreate — we get ‘Price must be greater than zero’. How can we implement a free plan that shows correctly on the manage-app screen while keeping one-time credit purchases working? What is the recommended approach for this pricing model?"

Sound familiar? Let's break down what the community experts had to say and what the real-world solution looks like.

The Core Conflict: Managed Pricing vs. One-Time Credits

Right off the bat, @Vlad_Gerasimchuk hit the nail on the head: this isn't a mistake, it's a fundamental constraint. Shopify App Pricing (which used to be called Managed Pricing) is designed specifically for recurring subscriptions and usage-based charges. It simply doesn't support one-time purchases or prepaid models.

Here's the kicker: the moment your app opts into Shopify App Pricing, the legacy Billing API gets blocked. That's why your trusty appPurchaseOneTimeCreate call suddenly stops working and throws that "Managed Pricing Apps cannot use the Billing API" error. It's by design, not an oversight.

@lumine echoed this, explaining that these two errors are essentially the same rule from different angles. If you're on managed pricing, one-time purchases are out. If you're trying to create a $0 recurring subscription via the old Billing API, it fails because in that system, a free tier is the absence of a subscription, not a zero-priced one.

Prepaid vs. Post-Pay: Knowing Your Model

This distinction is crucial. @awaisshafi clarified their model perfectly: "bought up front — merchants pay for credits in advance via appPurchaseOneTimeCreate, then use them. We don’t use appUsageRecordCreate at all." This means they're firmly in the prepaid, one-time credit purchase camp.

@Vlad_Gerasimchuk rightly pointed out that this makes usage-based billing (which is post-pay metered, using appUsageRecordCreate) unsuitable. While @lumine did suggest a "usage-only subscription" using appUsagePricingDetails as a way to potentially get a plan card, they also highlighted the catch: it fundamentally changes your payment model to metered post-pay. If your users expect to buy 500 credits upfront and use them over time, this won't fit.

The Recommended Approach for Prepaid Credits & Free Plans

Given the constraints and the specific prepaid model, the community consensus points to a clear path:

1. Stick with "Manual Pricing" (Off Shopify App Pricing)

This is the most critical step. To keep your appPurchaseOneTimeCreate calls working, you simply cannot opt into Shopify App Pricing. Your app's billing will remain handled through the legacy Billing API.

2. Continue Using appPurchaseOneTimeCreate

This is your go-to for all credit purchases. It works reliably when your app is not on Shopify App Pricing.

3. Your "Free Plan" is the Absence of a Subscription

For merchants who haven't bought credits, your app is simply installed and usable. There's no need to try and create a $0 subscription; the system doesn't support it in a way that gives you a native plan card on the "Manage Apps" screen. Think of it this way: your "free plan" is just the default state of your app.

4. Manage Credit Display & Purchase Buttons Within Your App's UI

Since you won't get a native plan card for your free tier or one-time purchases via Shopify App Pricing, you'll need to handle the user experience for credits directly within your app. This means:

• Displaying the merchant's current credit balance.
• Providing clear buttons or links to "Buy More Credits" that trigger your appPurchaseOneTimeCreate calls.

This approach gives you full control over how you present your credit system to your users, even if it means a little extra UI work on your end.

A Crucial Warning If You're Switching Back

If you've previously experimented with Shopify App Pricing and are now moving back to the Manual Pricing model to enable your one-time credit purchases, @Vlad_Gerasimchuk shared a vital tip:

Some developers report still getting the "cannot use the Billing API" error even after toggling off App Pricing. Here's what to do:

1. Remove Existing App Pricing Plans: Don't just switch the mode. Go into your Partner Dashboard and actively remove any App Pricing plans you might have created. A lingering plan can keep your app flagged.
2. Allow Time for Propagation: Changes aren't always instant across all stores. Give it some time (a few minutes to an hour) for the system to fully update.
3. Test on a Dev Store: Always test your one-time charge functionality on a development store after making these changes to ensure everything is working as expected.

So, there you have it. The bottom line for now is that if your business model relies on prepaid, one-time credit purchases through appPurchaseOneTimeCreate, you'll need to stick with manual pricing and manage the display of your free tier and credit purchases within your app's own UI. While it means foregoing the native plan card on the Shopify "Manage Apps" screen, it's the only combination that currently supports this specific and very common pricing model. Shopify is always evolving, so perhaps native prepaid support will come to App Pricing down the line, but for now, this is the pragmatic and effective route to ensure your app's billing works seamlessly. If you're just getting started with building apps or even starting your own Shopify store, understanding these distinctions is key to a smooth operation!