The Shopify Billing API
Charge merchants correctly.

1. What the Billing API is

The Shopify Billing API is how apps charge merchants for using them. Rather than integrating your own payment processor and collecting card details, you create charges through Shopify's API. Shopify then bills the merchant on their regular Shopify invoice — alongside their Shopify subscription and other app charges — and pays you out on a regular schedule.

This is a significant convenience: you don't manage payment processing, PCI compliance, international payment methods, failed-card retries at the processor level, or invoicing. Shopify handles all of it. Your job is to tell the Billing API what to charge and when, and to react to the resulting status via webhooks.

For the merchant, paying for your app feels native — it's just another line on their Shopify bill, approved through Shopify's own interface. That native, low-friction purchase experience is part of why the Shopify App Store converts well compared to standalone SaaS.

2. Why you must use it (not Stripe)

For apps on the public Shopify App Store, using the Billing API is mandatory. You cannot charge merchants with Stripe, PayPal, or any external processor for App Store app subscriptions. Shopify requires all such billing to flow through the Billing API, and review enforces this — an app that bills externally is rejected.

This trips up developers and generic AI tools coming from generic SaaS, where Stripe is the default. On Shopify, Stripe is the wrong choice for app billing. Generic AI builders generate Stripe integration because that's what their training data favors for SaaS — and the resulting app fails Shopify review for exactly this reason.

The revenue share

Shopify takes a share of revenue billed through the Billing API for App Store apps: 0% on your first $1,000,000 in lifetime app revenue, then 15% above that. This is the cost of the App Store's distribution and billing infrastructure. For apps distributed privately via custom distribution rather than the public App Store, there's no revenue share — you keep 100% while still using the Billing API to collect payment.

3. The charge types

The Billing API supports three models, each with its own GraphQL mutation:

The workhorse is appSubscriptionCreate, which creates a recurring (or usage-based) AppSubscription. A subscription contains one or more line items that define its pricing — a recurring fixed price, or a usage-based price with a capped amount, or both. This is how you model tiered plans and hybrid pricing.

Most apps use recurring subscriptions. One-time charges suit setup fees or lifetime deals. Usage-based suits apps where cost scales with volume (email, SMS). The models combine: a recurring base plan plus usage above an included allowance is a common, powerful structure.

4. The subscription flow step by step

Creating a charge isn't a single silent API call — it involves merchant approval. Here's the full flow:

• 1. Create the subscription. When a merchant chooses a plan, your backend calls appSubscriptionCreate with the plan's pricing, interval, any trial days, and a return URL. The mutation returns a confirmation URL.
• 2. Redirect the merchant. Send the merchant to the confirmation URL. Shopify shows them the charge details and asks them to approve or decline.
• 3. Merchant approves. On approval, Shopify redirects back to your return URL and the subscription moves toward active (after any trial period).
• 4. Handle the activation webhook. Shopify sends an app subscription update webhook confirming the status. Your app verifies the subscription is active before unlocking paid features.
• 5. Bill on the interval. Shopify charges the merchant each billing cycle automatically and continues sending status webhooks for changes (cancellation, etc.).

5. Free trials and annual billing

Free trials

When you create a recurring subscription, you can include a trial period (trial days). During the trial, the merchant isn't charged; billing begins automatically when the trial expires. If they cancel before the trial ends, they're never billed. This is handled by Shopify — you don't build trial timing logic yourself, you just specify the trial length. Free trials meaningfully increase conversion from install to paid, so most apps offer one (14 days is standard).

Annual billing

You can create subscriptions on a monthly or annual interval. Offering an annual plan at a discount (commonly ~2 months free) improves cash flow and dramatically reduces churn, since an annually-billed merchant is committed for the year. Shopify handles the annual billing cycle automatically. Offering both monthly and annual from launch is standard practice — see the pricing guide for how to structure this.

6. Usage-based billing

For apps where value scales with volume — emails sent, SMS messages, orders processed — usage-based billing charges merchants per unit consumed rather than a flat rate.

It works by creating a subscription with a usage-based line item that has a capped amount (the maximum a merchant can be charged in a billing period). As the merchant uses your app, you create usage records against the subscription, each adding a charge up to the cap. The cap protects merchants from surprise bills and is approved upfront, so you can charge usage without re-prompting for approval each time, as long as you stay under the cap.

Usage-based billing is more complex than flat recurring pricing — you track usage, create records, and handle approaching the cap — but it's the right model when your costs scale with usage. A common pattern is hybrid: a recurring base fee plus usage above an included allowance, giving you predictable base revenue and upside from heavy users.

7. Common Billing API mistakes

• Using Stripe instead of the Billing API: the single most common monetization mistake on Shopify. External billing fails App Store review. Always use the Billing API for App Store apps.
• Unlocking features before activation: granting paid access on subscription creation rather than after the merchant approves and the subscription is active.
• Not handling the status webhook: failing to react to subscription update webhooks means you miss cancellations and downgrades, leaving features unlocked for merchants who stopped paying.
• Listed pricing not matching API charges: your App Store listing prices must match what you actually create via the Billing API. Mismatches cause review issues and merchant confusion.
• No usage cap: usage-based charges without a sensible cap risk surprising merchants with large bills, hurting trust and retention.
• Mishandling plan changes: upgrades/downgrades require creating a new subscription and handling replacement of the old one cleanly. A broken upgrade flow loses you exactly the expansion revenue you want.

8. How AI builders wire up billing

The Billing API is one of the five requirements generic AI builders consistently get wrong. They generate Stripe integration — standard for generic SaaS — which doesn't work for Shopify App Store apps and fails review. Getting Shopify billing right means the correct mutation, the confirmation redirect, the activation webhook, and proper handling of trials, plan changes, and cancellations.

A Shopify-specific builder like Shopivibe generates the correct Billing API flow by default: appSubscriptionCreate with your plan structure, the confirmation URL redirect, the activation webhook handler, and trial support. When you describe a subscription app with tiered pricing, the right billing setup is generated — not Stripe, not a broken approximation.

You own the code and can adjust pricing, add usage-based components, or change tiers. But you start from a working, review-passing billing integration through Shopify's own system — which is the difference between an app that can actually charge merchants and one that fails review on monetization.

9. FAQ