Shopify Billing API in 2026: App Pricing, Usage Charges and What Changed

Shopify marked the Billing API as legacy in May 2026. Here's how App Pricing, usage meters and the App Events API work now, and which route to pick.

30 September 2026 · Deixtra

If you built a Shopify app a couple of years ago, you probably remember the routine: call appSubscriptionCreate, redirect the merchant to a confirmation page, wait for a webhook, flip a flag in your database. That routine still works for existing apps. But since May 2026 it is no longer the way Shopify wants you to charge merchants, and if you're starting a new app, following an old tutorial will point you at the wrong thing.

This guide explains what the Shopify Billing API is today, what replaced it as the default, how usage-based charging now works, and how to decide which route fits your app. It's based on Shopify's own developer documentation, which we read line by line before writing this. We've linked every source at the bottom so you can check us.

What is the Shopify Billing API, and is it still the right choice in 2026?

The Shopify Billing API is the set of GraphQL Admin API mutations that let a public or custom app charge merchants through their Shopify invoice, so you never touch card details or run your own payment gateway. It is still live, but Shopify now labels it legacy. For new public apps, the recommended route is Shopify App Pricing, where you define plans in the Partner Dashboard and Shopify runs the charging itself.

The rebrand and the change came in a developer changelog dated 12 May 2026. Three things landed together:

Managed Pricing was renamed Shopify App Pricing and became the default for new apps.
Usage-based billing arrived through the new App Events API.
Two new read APIs, Active Subscription and Historical, replaced the old habit of polling charges and listening for subscription webhooks.

So the honest answer to "should I use the Billing API?" is: only if you already do, or if your pricing does something App Pricing can't yet express. Otherwise, don't start there.

What are the two ways to bill merchants now?

Shopify's billing documentation splits it into two paths, and the whole decision comes down to who owns the billing logic.

Approach	Who runs billing	Best for
Shopify App Pricing	Shopify. You define plans in the Partner Dashboard.	New public apps, standard subscriptions, usage-based pricing, hybrids
Manual pricing (Billing API)	You. Your code creates and manages charges.	Existing apps, unusual pricing rules, custom apps that need bespoke logic

One rule to remember: once an app opts into Shopify App Pricing, you can't also create new recurring charges with appSubscriptionCreate. Shopify's docs say plainly not to call that mutation, or your framework's billing.request helper, to charge merchants under the new system. Pick a lane per app.

How does Shopify App Pricing work?

You configure it in the Partner Dashboard, not in code. Open your app under App distribution, go to Manage listing, and under Pricing content choose Shopify App Pricing. From there you set your default billing frequency (monthly or yearly) and build your plans.

Each plan can be one of three models:

Recurring: a flat monthly or yearly fee, with an optional discount for paying annually.
Usage-based: merchants pay for what they actually consume.
Combined: a base subscription plus usage on top, which is how most SaaS pricing looks in practice.

Free trials work on all three. Shopify also handles upgrades, downgrades, proration and chargebacks, which used to be the messy part of doing this yourself. The merchant chooses a plan, gets sent to the Shopify admin to approve, and the charge shows up on their normal Shopify bill. Merchants also get a billing card in the admin that shows their plan, status, usage charges and any upcoming price change, so they're less likely to email you asking why they were charged.

Limits you should know before designing your plans

Up to 8 public plans per app. Private plans are unlimited per app, but a single store can hold at most 8 of them.
Up to 5 active usage meters per plan and up to 6 pricing tiers per meter.
Usage charges bill monthly only. You can't attach them to a yearly-only plan.
Usage caps aren't supported yet. The old cappedAmount safety net has no direct equivalent.

That last one matters more than it sounds. If your product could generate a runaway bill (think SMS or AI calls), you'll need to enforce a limit inside your own app.

How does usage-based billing work with the App Events API?

Usage billing now runs on meters and events. You define a meter in the Partner Dashboard, give it an event handle like sms_sent, and choose a pricing structure. Your app then sends an event every time the merchant uses something. Shopify aggregates the events, applies your pricing, and adds the result to the merchant's monthly invoice.

There are three pricing structures:

Fixed: one price per unit, for example $0.01 per SMS.
Graduated: different rates per tier, and the charges add up across tiers.
Volume: the total usage for the period decides one rate that applies to every unit.

Here's what a single billing event looks like, based on the current documentation:

POST https://api.shopify.com/app/unstable/events
Authorization: Bearer {access_token}

{
  "shop_id": "gid://shopify/Shop/23423423",
  "event_handle": "sms_sent",
  "timestamp": "2026-01-27T14:30:00Z",
  "idempotency_key": "sms_23423423_1706365800",
  "attributes": { "value": 1 }
}

A few details that will save you a debugging afternoon:

The access token comes from a client credentials request and expires after 60 minutes, so refresh it.
event_handle is case-sensitive and must match the meter exactly. If it doesn't match a meter, Shopify treats it as a plain custom event for monitoring, not a billable one.
The idempotency_key can be up to 64 characters and is enforced permanently. Reuse a key and the second event is ignored, which is exactly what protects you from double-charging on retries.
The timestamp must fall inside the merchant's current billing cycle and can't be more than five minutes in the future.
Value can't be zero. Use a negative number to reverse usage after a refund or cancellation, and a quoted string such as "0.015" for fractional units.
The endpoint returns 202 no matter what. A 202 means "received", not "billed". Check the Logs section of the Dev Dashboard and filter by App Billing Event to see what actually counted.

The errors you'll meet first are NO_SUBSCRIPTION (the merchant hasn't approved a plan), SUBSCRIPTION_NOT_METERED (their plan has no usage meter), PERIOD_CLOSED (timestamp outside the cycle) and IDEMPOTENCY_KEY_ERROR. Note that the endpoint path currently contains "unstable", so treat the exact URL as something to re-check against Shopify's reference before you ship.

After a merchant uninstalls, you get a 24-hour window to send final events. Queue them properly instead of sending them inline with the request that triggered them.

How do you check what plan a merchant is on now?

With App Pricing you stop treating your own database as the source of truth for billing state. Two Partner API reads do that job:

Active Subscription: the activeSubscription(appId:, shopId:) query returns the current plan, billing period, subscription items, applied discounts, usage metrics and any pending plan change.
Historical events: the events root query gives you the log, including SUBSCRIPTION_CREATED, SUBSCRIPTION_UPDATED, SUBSCRIPTION_CANCELED, SUBSCRIPTION_FROZEN, CHARGE_RECURRING, CHARGE_USAGE and install or uninstall relationship events.

When a merchant picks a plan, Shopify sends them back to your app with plan_handle and shop URL parameters. Use those to show the right screen, then confirm with the Active Subscription query. The old charge_id parameter is part of the legacy flow, and Shopify's docs note that legacy signals for these apps end after 28 April 2026, so don't build anything new on it.

The lesson from our earlier post still holds: a redirect is not proof of payment. What changed is where you verify. Instead of trusting a webhook that might arrive late, you can ask Shopify directly.

What does the old Billing API flow look like, for apps still on it?

If you maintain an older app, this is the flow you already know:

Call appSubscriptionCreate with a name, returnUrl, line items and optional trial days. It returns a confirmationUrl.
Send the merchant to that URL. The subscription only becomes active after they approve.
For usage pricing, call appUsageRecordCreate against the subscription line item. The cappedAmount is the most a merchant can be billed in a 30-day cycle.
Listen to APP_SUBSCRIPTIONS_UPDATE for status changes, and to APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT, which fires when usage reaches 90% of the cap.

This still functions. Shopify says existing apps with active charges continue unchanged. The catch is that migration tooling for existing paid merchants hadn't shipped when we wrote this, so an app on manual pricing can't yet move its current subscribers across. Check the changelog before you plan a migration.

Which billing route should you choose?

Here's how we'd decide, in order:

New public app with normal plans? Use Shopify App Pricing. Less code, fewer billing bugs, and it's where Shopify is investing.
Pricing tied to actions, like messages, orders synced or AI generations? App Pricing with a usage meter. Send events, skip the manual usage records.
Existing app with paying merchants? Stay on the Billing API for now and tidy up your webhook handling. Migrate when Shopify ships the tooling.
Custom app for one client? App Store billing rules don't apply the same way, so the choice is practical. If the client pays you by invoice, you may not need in-app billing at all.

How do you test billing without charging anyone?

Shopify's docs describe several no-charge options. On stores in the same organization as your app, every plan tests at $0. On stores in another organization, only free plans and plans you've marked "free to test" work. There's also a private test plan at $0 for checking your flow before launch. Test subscriptions create contracts with an effective price of zero, so your billing logic still runs end to end.

Test the awkward paths as well as the happy one: a merchant who upgrades mid-cycle, one who cancels, one who uninstalls and reinstalls, and one whose usage events arrive late. That's where billing bugs live.

Mistakes we see teams make

Following an old tutorial. Anything that starts with appSubscriptionCreate and doesn't mention App Pricing is out of date for new public apps.
Trusting the 202. The events endpoint accepts everything. Verify in the Dev Dashboard.
Random idempotency keys. Generate them from the shop and the action, so a retry produces the same key. A fresh random key on every retry is how double-billing happens.
Forgetting there's no usage cap. Put your own ceiling in the product.
Designing 12 plans. You get 8 public ones, and merchants don't want to compare that many anyway.
Skipping the Polaris pricing screen. Merchants still need a clear in-app view of what they're paying for and what they'll be asked to pay next.

Key takeaways

The Billing API is legacy as of May 2026. Shopify App Pricing is the default for new public apps.
Usage billing now means meters plus events sent to the App Events API, not manual usage records.
Read subscription state from the Active Subscription query and the Historical events API instead of relying on redirects and webhooks alone.
Limits to design around: 8 public plans, 5 meters per plan, 6 tiers per meter, monthly usage billing, no usage caps.
Existing apps keep working, but you can't yet migrate paying merchants automatically.

Frequently asked questions

Is the Shopify Billing API deprecated?

Shopify marked it as legacy in May 2026, and it still works. Existing apps with active charges continue unchanged. New public apps are steered to Shopify App Pricing, and you can't mix the two for recurring charges.

What replaced Managed Pricing?

Nothing replaced it. It was renamed Shopify App Pricing and extended with usage-based billing, so apps already on Managed Pricing are on App Pricing automatically.

Can I still use appSubscriptionCreate?

Yes, if your app already uses manual pricing. If your app opts into Shopify App Pricing, Shopify's docs say not to use it to create new charges.

How do I charge per usage on Shopify?

Create a usage meter with an event handle in the Partner Dashboard, pick fixed, graduated or volume pricing, then send billing events to the App Events API with a shop ID, event handle, timestamp, idempotency key and value. Shopify aggregates and invoices monthly.

Does Shopify take a cut of app revenue?

Yes. Apps distributed through the App Store must use a Shopify billing solution, and Shopify's revenue share terms are set in the Partner Program Agreement. We're not quoting percentages here because they change, so check the current agreement.

Can I bill merchants with Stripe instead?

For charges tied to your app's functionality on the App Store, Shopify requires its own billing. A separate processor makes sense only for things outside the app itself, such as a separate service you sell them.

Need help with billing on your Shopify app?

We build Shopify apps for businesses in Pakistan, the UAE and the wider GCC, including plans, usage metering and the pricing screens merchants see. If you're planning a new app or your current billing flow is misbehaving, send the details on WhatsApp and we'll come back with a written scope and a fixed quote. For a look at the older flow and its failure points, read our earlier post on the Shopify Billing API and plans.