Billing thresholds were removed from the API without adequate replacement

[ggaabe]

Describe the bug

Stripe completely removed billing_thresholds from subscriptions in their basil API update but doesn't detail how to actually migrate the same functionality:

https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-legacy-usage-based-billing#why-is-this-a-breaking-change

The problem is that this feature is necessary for automatically billing usage-based billing once the user has hit a certain amount owed on their invoice.

Oddly, they still support setting the billing threshold on the dashboard for the subscription:

And they even generate a curl request to use on the right:

curl https://api.stripe.com/v1/subscriptions/sub_1RJnu... \
  -u "sk_test_...WUlX:" \
  -d "billing_thresholds[amount_gte]"=4000 \
  -d "billing_thresholds[reset_billing_cycle_anchor]"=false \
  -d discounts="" \
  -d "items[0][discounts]"="" \
  -d "items[0][id]"=si_SEGRY... \
  -d "items[0][tax_rates]"="" \
  -d off_session=true \
  -d payment_behavior=error_if_incomplete \
  -d proration_behavior=none

But when you actually use this same curl request, it produces an error:

"Starting with Stripe version 2025-03-31.basil, subscriptions do not support the parameter billing_thresholds."

If the metered billing alerts could include the subscription ID on them, that would be useful, but still inadequate because metered billing alerts only support a single recurrence frequency of one_time, meaning once in the entire lifetime of the customer even if they hit the threshold over and over. That wouldn't work for making us manually manage this type of billing.

Stripe provides no clear equivalence to meet this billing threshold functionality. It's not clear why it was removed before the metered version was fully ready.

To Reproduce

Try to add a billing threshold to a subscription, ie:

curl https://api.stripe.com/v1/subscriptions/sub_1RJnu... \
  -u "sk_test_...WUlX:" \
  -d "billing_thresholds[amount_gte]"=4000 \
  -d "billing_thresholds[reset_billing_cycle_anchor]"=false \
  -d discounts="" \
  -d "items[0][discounts]"="" \
  -d "items[0][id]"=si_SEGRY... \
  -d "items[0][tax_rates]"="" \
  -d off_session=true \
  -d payment_behavior=error_if_incomplete \
  -d proration_behavior=none

Maybe this is intended behavior but it doesn't seem like outright removing this functionality without any guide on on-par replacement was intentional

Expected behavior

We should be able to set a billing threshold to automatically invoice a usage-based customer when they hit a limit in some meaningful way.

Code snippets

OS

MacOS

Node version

Node 22

Library version

18.0.0

API version

2025-03-31.basil

[remi-stripe]

@ggaabe I'm sorry about the trouble here and unfortunately your read is correct: we did remove the feature entirely before Billing Alerts were ready to replace that feature. We are looking into a potential alternative but this will take a few weeks unfortunately.

My advice is to stick to the previous major version of the ruby SDK or override the default API version to the Acacia one to be able to continue using billing_thresholds. Then please reach out to our support team with your use-case so we can keep you updated on whether we plan to revert this change or if Billing Alerts are going to support this soon.