Questions on Recurring Billing, Webhooks & Testing for Selling Plans (Subscriptions API)

Extensions
, ,
1

Hi everyone,

I’m building a custom subscription (membership) app using Shopify’s Selling Plans / Selling Plan Groups via the Subscriptions API, and I’m looking for some clarification on how recurring billing and testing work in this setup.

1. Recurring Billing Handling (Selling Plans)

When a subscription is created using selling plans:

  • Are recurring charges automatically handled by Shopify (via Shopify Payments or the customer’s selected gateway)?

  • Or is the app expected to manage recurring billing logic (e.g., cron jobs, external payment capture)?

My understanding is that Shopify manages subscription contracts and billing cycles, but I’d like confirmation on whether any manual intervention is required from the app side.

2. Webhooks for Subscription Billing Events

For selling plan–based subscriptions:

  • Which webhooks are triggered when a recurring charge occurs?

  • Specifically, I’m looking for events related to:

    • Successful billing

    • Failed payments

    • Retry attempts

    • Subscription contract updates (renewals, cancellations)

Are these covered under:

  • subscription_contracts/*

  • orders/create

  • payments/*

Would appreciate a clear list of reliable webhooks to track subscription billing lifecycle.

3. Viewing Transactions for Test Payments

While testing subscriptions:

  • Is there a way to view all transactions triggered by recurring billing cycles?

  • For example:

    • Orders generated from subscription renewals

    • Payment attempts (success/failure)

Is this visible in:

  • Shopify Admin → Orders

  • Or any specific logs for subscription billing?

4. Best Way to Test Subscription Billing

For testing recurring payments with selling plans:

  • Should I use:

    • Bogus Gateway, or

    • Shopify Payments (test mode)?

  • Do both support:

    • Subscription contract renewals

    • Automatic recurring charges

  • Are there any limitations or recommended approach for testing full subscription lifecycle (create → renew → fail → retry)?

Goal

I want to ensure that my app correctly integrates with Shopify’s subscription infrastructure without duplicating billing logic or missing critical webhook events.

Any insights, best practices, or gotchas from people who’ve implemented subscription apps using selling plans would be really helpful.

Thanks!

2

For selling plan–based subscriptions, Shopify handles most of the heavy lifting with billing cycles automatically. However, your app does need to listen for specific webhooks to stay in sync. The key webhooks you’ll want to subscribe to are: SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS and SUBSCRIPTION_BILLING_ATTEMPTS_FAILURE for tracking when recurring charges go through (or don’t), SUBSCRIPTION_CONTRACTS_UPDATE for contract changes, and ORDERS_CREATE which fires each time a new recurring order is generated. You can register these via the webhookSubscriptionCreate GraphQL mutation or through your app’s shopify.app.toml configuration.

Regarding manual intervention — if you’re using Shopify-managed billing cycles, the process is largely automated, your app mainly needs to handle edge cases: responding to failed payment attempts (e.g., notifying the customer or retrying), processing contract updates, and managing any custom fulfilment logic. If you’re using app-managed billing cycles instead, you’ll have more responsibility since your app needs to trigger the billing attempts via the subscriptionBillingAttemptCreate mutation.

For testing, I’d use Bogus Gateway. You can create selling plans, simulate purchases, and then fast-forward billing cycles using the subscriptionBillingCycleBillingCycleCharge mutation in development mode to trigger charges without waiting for the actual billing date. This makes it much easier to verify your webhook handlers are working correctly.

2 Likes
3

@HookdeckGareth Thanks for the clear explanation — super helpful!