The Shopify billing API supports four charge types: AppSubscription (recurring monthly or annual), AppUsageRecord (per-event usage billing against a capped plan), AppPurchaseOneTime (single payment), and AppCredit (refund mechanism). Most commercial apps use AppSubscription with optional usage billing on top. The flow always requires merchant approval via a Shopify-hosted confirmation page before charges can be applied.

Shopify billing API — charge types, confirmation flow, trial period handling and billing webhook events by CodeAtoZ

The Shopify billing API AppSubscription creates a recurring monthly or annual plan. Create the subscription via the appSubscriptionCreate GraphQL mutation, then redirect the merchant to the returned confirmationUrl. The merchant approves the charge on a Shopify-hosted page. After approval, Shopify redirects back to your returnUrl with a charge_id parameter. Check the charge status — it must be ACTIVE before granting the merchant access to paid features.

mutation appSubscriptionCreate {
  appSubscriptionCreate(
    name: "Pro Plan"
    returnUrl: "https://your-app.com/billing/callback"
    trialDays: 14
    test: false
    lineItems: [{
      plan: {
        appRecurringPricingDetails: {
          price: { amount: 29.00, currencyCode: USD }
          interval: EVERY_30_DAYS
        }
      }
    }]
  ) {
    appSubscription { id status }
    confirmationUrl
    userErrors { field message }
  }
}

Usage billing via the Shopify billing API lets you charge merchants per event — AI API calls, SMS messages, processed orders, or any countable unit. Create a capped AppUsageRecord plan as part of the subscription, then call appUsageRecordCreate each time a billable event occurs. The cappedAmount sets the maximum monthly spend, giving merchants cost predictability while you monetise actual usage.

mutation appUsageRecordCreate($subscriptionLineItemId: ID!, $price: MoneyInput!, $description: String!) {
  appUsageRecordCreate(
    subscriptionLineItemId: $subscriptionLineItemId
    price: $price
    description: $description
  ) {
    appUsageRecord { id createdAt }
    userErrors { field message }
  }
}
# Variables: { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/...",
#   "price": { "amount": 0.05, "currencyCode": "USD" },
#   "description": "1 AI product description generated" }

The Shopify billing API fires app_subscriptions/update webhooks whenever a subscription status changes. Handle the following status transitions: ACCEPTED (merchant approved — grant access), DECLINED (merchant declined — deny access), EXPIRED (trial ended without approval — downgrade to free tier), FROZEN (merchant’s Shopify plan payment failed — suspend access temporarily), and CANCELLED (merchant uninstalled or cancelled — revoke access). Refer to the Shopify billing API documentation for the full status transition map. See also the Shopify app monetisation guide for pricing strategy recommendations.

• Subscribe to app_subscriptions/update webhook on app install
• Check status field in payload — grant or revoke access accordingly
• Handle FROZEN gracefully — merchant’s store is paused, not cancelled
• Set test: true during development to avoid real charges in the Shopify billing test mode
• Never grant access before status is confirmed as ACTIVE

Building and monetising Shopify apps requires careful Shopify billing API implementation alongside your core app features. Our Shopify development team handles billing integration, App Store submission, and full app architecture for startups and agencies building on Shopify.