Shopify App Billing Dilemma: Free Apps, One-Time Credits & the 'Managed Pricing' Trap

Hey there, fellow Shopify app developers and store owners!

Ever found yourself scratching your head trying to figure out the best way to price your app, especially when you want to offer a free tier alongside one-time purchases like credit packs? You're definitely not alone. We've seen this exact dilemma pop up in the Shopify Community forums, and it's a fantastic example of where the platform's billing systems can feel a bit like trying to fit a square peg in a round hole.

Recently, a developer named @awaisshafi kicked off a great discussion with a common challenge: their app is free, but offers optional credit purchases through appPurchaseOneTimeCreate. The problem? They couldn't use Shopify App Pricing (what used to be called Managed Pricing) because it blocked their one-time credit purchases, throwing an error: “Managed Pricing Apps cannot use the Billing API.” And trying to create a $0/month recurring subscription also failed with “Price must be greater than zero.” Sound familiar? It's a classic catch-22, and the community really dug into it.

The Core Conflict: Shopify App Pricing vs. the Billing API

As @Vlad_Gerasimchuk and @lumine pointed out so clearly in the thread, you're hitting a fundamental constraint, not a configuration mistake. Here's the deal:

1. Shopify App Pricing (the newer system): This is designed for recurring subscriptions and usage-based (post-pay metered) charges. It's fantastic for setting up your standard monthly plans or charging based on, say, the number of orders processed. But here's the kicker: it does NOT support one-time or prepaid charges. The moment you opt your app into App Pricing, the older, legacy Billing API (which includes appPurchaseOneTimeCreate) gets blocked. It's by design.
2. The Legacy Billing API: This is where appPurchaseOneTimeCreate lives. It allows you to process those one-time payments for things like credit packs, add-ons, or setup fees.
3. The $0 Subscription Hurdle: When you use the legacy Billing API, a “free plan” isn't a subscription priced at zero; it's simply the absence of a subscription. There's no actual subscription object for a $0 plan to be created, which means there's nothing for the Shopify “Manage Apps” screen to render as a “Free Plan” card.

So, you see the inherent conflict. If you want the shiny native “plan card” on the “Manage Apps” screen (which comes with Shopify App Pricing), you lose the ability to sell one-time credits. If you want to sell one-time credits, you can't use Shopify App Pricing and thus don't get that native plan card.

Your Options: Prepaid Credits vs. Native Plan Card

The community discussion highlighted two distinct paths, and your choice really depends on your core business model. For @awaisshafi, the critical detail was that their credits are “bought up front — merchants pay for credits in advance via appPurchaseOneTimeCreate, then use them.” This makes the decision much clearer.

Option 1: Embrace Prepaid Credits (Recommended for “Buy Up Front” Models)

If your app's main monetization is through merchants purchasing credits in advance and then consuming them, this is the path that actually works today.

• Stay on “Manual Pricing”: Do NOT opt into Shopify App Pricing. Keep your app's pricing mode set to manual.
• Use the Billing API: Continue to use appPurchaseOneTimeCreate whenever a merchant wants to buy a pack of credits.
• Manage In-App: Your “free plan” will simply be the state where a merchant hasn't bought credits yet. You'll need to display the merchant's current credit balance and a “buy more” button directly within your app's user interface. This gives you full control over the experience.
• What about the “Manage Apps” screen? It will show your app as installed and usable, but without a specific “plan card.” This is a trade-off, but it preserves your core business model.

Important Tip from Vlad: Switching Back to Manual Pricing

If you've previously experimented with Shopify App Pricing and are now switching back to Manual, a few developers have reported still getting the “cannot use the Billing API” error. Here's what Vlad suggests:

1. Remove Existing App Pricing Plans: Don't just switch the mode; make sure you've completely removed any App Pricing plans you might have created. A lingering plan can keep your app flagged.
2. Give it Time: Changes aren't always instant across all stores. Allow some time for the changes to propagate.
3. Test on a Dev Store: Always test your one-time charge functionality on a development store first to confirm it's working correctly.

Option 2: Use Usage-Based Billing (If Post-Pay Works for You)

@lumine brought up an interesting alternative: using a usage-only subscription if you really want a plan card on the “Manage Apps” screen and can adapt your billing. This involves staying off managed pricing but creating a subscription with only appUsagePricingDetails and no recurring pricing. Merchants would approve a cap, and you'd bill credits using appUsageRecordCreate post-pay.

• The Catch: This fundamentally changes your model from prepaid to post-pay metered. Merchants would consume credits first, and then be billed for that usage later, against a pre-approved cap. If your business relies on upfront payments for credits, this won't fit your needs. As @awaisshafi clarified, their model is strictly prepaid, making this option unsuitable for their specific case.

Wrapping It Up

For app developers like @awaisshafi who offer a free app with optional, prepaid one-time credit purchases, the consensus from the community is clear: stick with Manual Pricing and leverage the legacy Billing API's appPurchaseOneTimeCreate. While you won't get that native “plan card” on the Shopify “Manage Apps” screen, you maintain the ability to sell credits upfront, which is crucial for this business model. You'll simply manage the credit display and purchase flow entirely within your own app's UI.

It's a bit of a workaround, but it's the currently supported path to achieve this specific pricing structure on Shopify. Hopefully, as the platform evolves, we'll see more flexible billing options that natively support hybrid models like this, bridging the gap between one-time prepaid charges and the visibility of Shopify App Pricing. Until then, knowing these distinctions can save you a lot of development headaches!