Subscription billing attempts throttling

Changelog
1

Beginning in API version 2026-01, billing attempts will be throttled based on internal trust metrics to prevent abuse. If an attempt is throttled, it will be visible in the new throttled error code on the BillingAttemptUserErrorCode enum.

This is a companion discussion topic for the original entry at https://shopify.dev/changelog/subscription-billing-attempts-throttling
2

Hi Shopify team :waving_hand:

Regarding the recent update on subscription billing attempts throttling, I’m looking for some high-level guidance to help apps implement safe retry logic.

For apps using custom retry or manual billing flows:

  • Are there any recommended limits (e.g. max billing attempts per subscription per day or per billing cycle)?

  • At a high level, do trust metrics consider factors like attempt frequency, failure rates, payment method, or merchant/app-level signals?

  • After receiving a throttled response, is there a recommended cool-down or backoff period before retrying?

I understand the details may be proprietary, but any best-practice guardrails would help apps avoid throttling while still responsibly recovering failed payments.

Thanks!