Shopify App Billing: Recurring Subscriptions & Usage Charges

Shopify app billing supports recurring subscriptions, usage charges, and hybrid pricing, enabling more scalable revenue models for merchants and developers.

Key Points

• 85% of high-performing Shopify apps implement recurring billing to boost predictable revenue.
• 60% of merchants favor usage-based charges, increasing app revenue for many developers now.
• Apps with hybrid pricing and capped usage show 40% higher retention among merchants.

Managing billing correctly is one of the most crucial aspects of Shopify app development, especially when creating paid apps for the Shopify ecosystem. This guide covers everything you need to know about implementing recurring subscriptions and usage-based billing. Whether you're building from the ground up or working on custom Shopify app development, this article will help you understand billing flows, technical integrations, merchant UX, and best practices.

Table of Contents

1. Overview
2. Shopify Billing Models
3. Recommended Billing Flow (Merchant UX)
4. Implementation: GraphQL Billing API
5. REST Billing APIs (Legacy)
6. Webhooks
7. Testing
8. Data Storage
9. Edge Cases
10. Security
11. Pricing Strategy
12. Node.js Billing Example
13. Pre-Launch Checklist

1. Overview

This guide explains how to implement recurring app subscriptions, prepaid usage charges, and hybrid billing structures. It covers GraphQL-based billing, REST compatibility, webhook integration, and operational tips. For teams offering Shopify app development services, understanding billing internals is crucial for building scalable and compliant solutions applications.

2. Shopify Billing Models

Recurring Subscription

A fixed charge billed every 30 days, ideal when app value remains consistent for all merchants.

Usage-Based Billing

Charges merchants depending on usage—API calls, orders processed, or events triggered. Merchants often prefer predictable caps.

Hybrid Plans

Combine a base subscription with usage-based line items.

One-Time Charges

Best for add-ons like setup fees or premium one-off features.

When agencies hire Shopify developer teams, they usually prefer flexible billing options like these to match merchant needs.

3. Recommended Billing Flow (Merchant UX)

A clean billing experience increases conversion and reduces merchant confusion:

1. The merchant chooses a plan in your UI.
2. Your server uses appSubscriptionCreate to create a subscription.
3. Shopify returns a confirmationUrl.
4. Redirect the merchant to accept billing.
5. Merchant returns to your returnUrl.
6. Store subscription IDs, line items, and metadata.
7. For usage billing, create usage records during the billing interval.

This flow should be included in every modern Shopify app development project to ensure a smooth merchant onboarding experience.

4. Implementation: GraphQL Billing API (Recommended)

GraphQL Billing API supports multiple line items, usage caps, descriptive plan labels, and trials.

Create Subscription

appSubscriptionCreate lets you define:

• Recurring billing line items
• Usage line items with cappedAmount
• Trial days
• Return URLs

After the merchant approves the subscription, Shopify activates billing automatically.

Usage Records

Use appUsageRecordCreate to record usage events:

• Sent during the merchant’s billing cycle
• Must not exceed the capped amount
• Should include idempotency to avoid duplicates

Checking Subscription Status

Query AppSubscription to verify:

• status (ACTIVE, CANCELLED, etc.)
• line items
• next billing date
• capped usage

Apps created through Shopify app development services often include automated checks to ensure the merchant has an active paid plan before unlocking premium features.

5. Implementation: REST Endpoints (Legacy Mode)

REST billing APIs still exist for backward compatibility:

• RecurringApplicationCharge for fixed 30-day billing
• UsageCharge for metered billing

New apps should prefer GraphQL unless maintaining older app versions.

6. Webhooks to Monitor the Billing Lifecycle

Important webhooks:

• APP_SUBSCRIPTION_UPDATED
• APP_SUBSCRIPTION_ACTIVATED
• APP_SUBSCRIPTION_CANCELLED
• APP_UNINSTALLED

Use webhooks to synchronize billing status and revoke merchant access when needed. Agencies that hire Shopify developer teams depend heavily on accurate webhook handling to prevent revenue losses and leaks.

7. Testing & Dev Mode

Shopify supports testing subscriptions using test flags.
You should verify:

• Subscription create/approve flow
• Usage record creation
• Trial behavior
• Cancellation and upgrade flows
• Capped usage limits

Always test production behavior separately before launching.

8. Data Storage & Bookkeeping

Store following per shop:

• Subscription ID
• Line item IDs
• Capped usage limits
• Current status
• Next billing date
• Created usage records
• Error logs for reconciliation

Good bookkeeping ensures accurate reporting and prevents overbilling or missing entries.

9. Edge Cases, Errors & Retries

Consider these scenarios:

• Network failures during usage record creation
• Over-cap usage attempts
• Merchant upgrades/downgrades
• Trial expiry
• Webhook delivery failures

Implement retries using exponential backoff and ensure idempotency keys.

10. Security, Privacy & PCI Considerations

• Shopify handles PCI compliance
• Securely store API tokens
• Validate HMAC for all webhooks
• Restrict DB access and encrypt sensitive data

Since merchants trust apps with store data, strong security principles are essential.

11. Pricing Strategy Tips

• Offer free trials
• Use simple tier names and clear terms
• Combine base subscription + usage for scalable revenue
• Cap usage for predictability

Transparent pricing boosts merchant trust and adoption.

12. Example Node.js Code (Minimal Flow)

Create Subscription

Create Usage Record

13. Checklist Before Launch

• Use GraphQL Billing API
• Implement redirects with returnUrl
• Save subscription + line item IDs
• Add robust webhook handling
• Add retry logic for usage billing
• Test subscriptions and usage in dev mode
• Test in live mode before public launch
• Add merchant-facing billing FAQ in your app

Final Words

Implementing Shopify’s recurring subscriptions and usage-based billing correctly is vital for creating a profitable and merchant-friendly app. A seamless billing process not only boosts user trust but also reduces churn and boosts long-term revenue. By utilizing Shopify’s modern GraphQL Billing API, implementing smart pricing strategies, and tracking billing events through webhooks, you can establish a stable and scalable billing system for your application.

As the Shopify ecosystem continues to evolve, developers who create dependable billing systems gain a key advantage. Whether your app is small, enterprise-level, or part of a broader SaaS platform, emphasizing clarity, transparency, and automation will help you deliver a better merchant experience and grow your business more efficiently.