Stripe: migrate metered billing to the Billing Meters API + pin Stripe-Version

[Zwiterrion]

Severity: 🔴 Critical (out of date)

The metered / pay-per-request path calls Stripe APIs that Stripe removed in API version 2025-03-31.basil (legacy usage-based billing).

Affected calls

• Metered price creation without recurring[meter]:
  PaymentClient.scala:325-333 and :355-356 (recurring[usage_type]=metered + recurring[aggregate_usage]=sum).
• Usage reporting via the legacy endpoint:
  PaymentClient.scala:634-636 (POST /v1/subscription_items/{id}/usage_records).

Why it breaks

No Stripe-Version header is pinned — stripeClient only sets content-type + Basic Auth (PaymentClient.scala:38-50). Behaviour therefore follows the account default API version. Any account at/after 2025-02-24.acacia rejects metered price creation (a meter is now required) and the usage_records endpoint. The flat-subscription path (costPerMonth only) is unaffected.

Fix

• Migrate to the Billing Meters API: create a meter, link prices with recurring[meter], replace usage_records with POST /v1/billing/meter_events.
• Pin an explicit Stripe-Version header to freeze behaviour going forward.

References

• https://docs.stripe.com/billing/subscriptions/usage-based-legacy/migration-guide
• https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-legacy-usage-based-billing

How to verify

On a recent Stripe account, configure a plan with costPerRequest and run setupPayment → observe the rejected POST /v1/prices (metered price without a meter).