Navigating Shopify App Billing: The Developer's Guide to Free Tiers and One-Time Credit Purchases

Introduction: The Developer's Dilemma – Free Apps and One-Time Credits

As a Shopify app developer, you've likely grappled with the intricacies of pricing models. Offering a free tier to attract users while also providing optional one-time purchases, like credit packs, seems like a straightforward business model. Yet, as many discover, integrating these two elements within Shopify's billing ecosystem can feel like navigating a maze.

This exact challenge recently surfaced in the Shopify Community forums, where a developer, @awaisshafi, articulated a common pain point: their app is free, but relies on optional credit purchases via appPurchaseOneTimeCreate. The core issue? Shopify App Pricing (formerly Managed Pricing) blocked their one-time purchases with the error “Managed Pricing Apps cannot use the Billing API.” Simultaneously, attempting to create a $0/month recurring subscription was rejected with “Price must be greater than zero.” This isn't just a configuration hiccup; it's a fundamental conflict within Shopify's billing architecture.

Understanding Shopify's Dual Billing Systems

To truly grasp the problem, it's crucial to understand the two distinct billing systems Shopify offers for app developers:

Shopify App Pricing (Formerly Managed Pricing)

This is Shopify's newer, streamlined billing system designed primarily for apps offering:

• Recurring Subscriptions: Think monthly or annual plans with a fixed fee.
• Usage-Based Charges: Where merchants pay based on their consumption (e.g., number of orders processed, API calls). This is a post-pay metered system, meaning usage is tracked, and then billed at the end of a cycle.

The Catch: While Shopify App Pricing offers a clean, native experience for merchants on their “Manage Apps” screen, displaying clear plan cards, it comes with a significant limitation: it does NOT support one-time or prepaid charges. The moment your app opts into App Pricing, the legacy Billing API (which handles one-time purchases) is intentionally blocked. This is why you encounter the “Managed Pricing Apps cannot use the Billing API” error.

The Legacy Billing API

This older system is where you'd traditionally handle:

• One-Time Purchases: Such as the appPurchaseOneTimeCreate mutation, perfect for selling credit packs, themes, or one-off services.
• Older Recurring Charges: Before App Pricing, this API also handled recurring subscriptions.

The Catch: The legacy Billing API doesn't natively support the concept of a “free plan” that appears as a distinct card on the merchant's “Manage Apps” screen. Trying to create a $0 recurring subscription via appSubscriptionCreate will fail because, from the API's perspective, a free tier is simply the *absence* of a subscription, not a subscription priced at zero. Furthermore, the legacy Billing API is mutually exclusive with Shopify App Pricing for new charges.

The Core Conflict Unpacked: Why You Can't Have Both (Natively)

As @Vlad_Gerasimchuk and @lumine eloquently explained in the forum thread, these two errors aren't bugs; they're direct consequences of Shopify's design philosophy for its billing systems. You're hitting a fundamental constraint: Shopify App Pricing gives you the native plan card display but kills your one-time credit purchases, while manual pricing (via the legacy Billing API) keeps your prepaid credits working but doesn't offer the native App Pricing plan card for a free tier.

The Recommended Path: Embracing Manual Pricing for Prepaid Credits

For apps like @awaisshafi's, where the core monetization strategy involves prepaid, one-time credit purchases, the most viable and recommended approach is to stay off Shopify App Pricing entirely and rely on the legacy Billing API.

Implementation Strategy:

• Handle One-Time Purchases: Continue to use appPurchaseOneTimeCreate for all credit pack sales. This ensures merchants pay upfront, and you maintain control over the credit system.
• Managing the “Free Plan”: Your free plan is simply the state where a merchant has installed your app but hasn't purchased any credits yet. There's no need to create a formal $0 subscription.
• In-App UI for Credits: Since there won't be a native Shopify plan card for your free tier or credit purchases, you'll need to manage and display the merchant's credit balance, purchase options, and any associated usage within your app's own user interface. This gives you complete control over the user experience for credit management.

Actionable Advice for Switching or Troubleshooting:

If you've previously experimented with Shopify App Pricing and are now switching back to manual billing, heed this warning:

• Remove App Pricing Plans: It's not enough to simply toggle a setting. Ensure you remove any lingering App Pricing plans you might have created. A residual plan can keep your app flagged, preventing the legacy Billing API from working.
• Allow Propagation Time: Changes to billing settings aren't always instantaneous across all stores. Give it some time (e.g., a few hours) for the changes to propagate through Shopify's system.
• Test on a Development Store: Always test your one-time charge functionality thoroughly on a development store before rolling out changes to live merchant stores.

By following this approach, you accept the trade-off of not having a native Shopify plan card for your free tier, but you gain the crucial functionality of handling prepaid, one-time credit purchases effectively.

Why Usage-Based Billing Isn't a Direct Alternative for Prepaid Credits

It's important not to confuse prepaid credits with usage-based billing. While appUsageRecordCreate allows you to bill merchants based on their app usage, this is a *post-pay metered* system. Merchants approve a capped amount upfront, but payment occurs at the end of a billing cycle, based on actual consumption. This fundamentally differs from prepaid credits, where merchants pay for a specific quantity of credits *in advance* to use later. If your business model requires upfront payment for credits, usage-based billing won't fit your needs.

Looking Ahead: The Future of Shopify App Billing

While the current systems present this challenge, the Shopify platform is constantly evolving. Developers hope that Shopify App Pricing will eventually incorporate native support for prepaid, one-time purchases, offering a more unified and flexible billing experience. Until then, understanding these constraints and implementing the recommended workarounds is key to a successful app.

Conclusion: Strategic Billing for Your Shopify App

For Shopify app developers offering a free tier alongside optional, prepaid one-time credit purchases, the path is clear: leverage the legacy Billing API for your appPurchaseOneTimeCreate mutations. While this means managing your free plan and credit displays within your app's UI, it's the only current method that allows both functionalities to coexist harmoniously. By understanding these nuances, you can make informed decisions about your app's billing strategy, ensuring a smooth experience for both you and your merchants.

At Shopping Cart Mover, we specialize in understanding the intricate details of e-commerce platforms and integrations. Whether you're navigating complex app development challenges or planning a seamless store migration, our expertise ensures your business thrives.