Stripe Basil Quietly Moved current_period_end Off Subscription — And a Lot of Code Broke

On March 31, 2025, Stripe shipped the Basil API version. Among other changes, it removed three fields from the Subscription object that a lot of production code was reading:

current_period_start — moved to subscription items
current_period_end — moved to subscription items
billing_thresholds — removed entirely (later reintroduced — more on this)

If you upgraded your account's default API version without pinning the SDK, the endpoint still returned 200 OK. The subscription objects still serialized cleanly. The fields your code accessed just came back undefined.

One of those fields is current_period_end. If your app uses Stripe subscriptions at all, there's a very good chance you read current_period_end somewhere. Maybe it populates the "next bill date" in your UI. Maybe it drives a cron job that reminds customers before renewal. Maybe it gates feature access for annual plans. Whatever it is, it quietly stopped working.

What Actually Changed

From the Basil changelog:

current_period_start and current_period_end are removed from subscriptions. Instead, access the subscription item's billing periods directly via items.data[].current_period_start and items.data[].current_period_end.

The rationale is sound. In the old model, every subscription had a single billing cycle. In the new flexible-billing model, each item in a subscription can have its own cycle — useful for mixing monthly and annual items, or metered and flat items, on one subscription. Moving the fields down to the item level reflects reality.

From the consumer side, though, the surface looked like this:

Before (2025-02-24.acacia):

{
  "object": "subscription",
  "id": "sub_...",
  "current_period_start": 1710000000,
  "current_period_end": 1712678400,
  "items": { "data": [ /* ... */ ] }
}

After (2025-03-31.basil):

{
  "object": "subscription",
  "id": "sub_...",
  "items": {
    "data": [
      {
        "current_period_start": 1710000000,
        "current_period_end": 1712678400
      }
    ]
  }
}

Still a valid Subscription object. Still everything serializes. Just no more top-level period fields.

The breakage affected every SDK language — Node, Python, PHP, Java, Go, .NET. (Ruby, per the changelog, was the only one unaffected by this particular change, because of how that SDK maps the object.)

billing_thresholds — Removed, Then Quietly Un-Removed

The other Basil change that bit a lot of teams was billing_thresholds disappearing. This one has an even weirder story.

billing_thresholds was how you told Stripe "automatically invoice this subscription when the customer's usage passes this amount." For metered billing at scale, it was the thing that prevented a single runaway customer from accumulating a six-figure bill you might never collect.

On 2025-03-31, Stripe removed it from the Subscription API. The initial migration advice pointed teams at "metered billing alerts" as a replacement.

Developers quickly noticed the replacement wasn't on par. From stripe-node issue #2328:

"It's not clear why it was removed before the metered version was fully ready."

"The dashboard still allows setting billing thresholds and even generates the curl command. But when you actually use the same curl request, it produces an error stating the parameter is no longer supported."

Metered billing alerts only fired once per customer lifetime and didn't carry subscription IDs. You could not use them to auto-invoice at a threshold. There was no direct replacement for the thing that had been removed.

On 2025-05-28, Stripe reintroduced billing_thresholds. The field came back. Anyone who had already rewritten their billing logic to work around its absence had just shipped two migrations to land in the same place.

This is the other failure mode of silent schema changes: the churn of reacting to a change, then reacting to its reversal.

Why Most Teams Didn't Catch the Migration

The cleanest version of this upgrade is: pin your SDK to the old Basil-adjacent version, upgrade the SDK deliberately, test against a staging Stripe account, ship. A lot of teams do this. A lot don't.

Here are the common ways it slipped through:

Library auto-upgrades. A Dependabot PR bumps your stripe-node minor version, tests pass (because fixtures are from before the migration), and you merge it. Your SDK is now Basil-aware, your code still reads subscription.current_period_end, and the field is undefined in production.

Account-level API version default. Stripe lets you upgrade your account's default version in the dashboard. If someone on your team clicks through the upgrade flow without coordinating with engineering, every non-pinned API call starts returning the new shape.

Webhook events. Webhook payloads use the API version in effect at the time the event is created. If your account default shifts, your webhook handlers start receiving new-shape invoice.* and customer.subscription.* events — often before your SDK has been upgraded.

TypeScript didn't save anyone. The Stripe Node SDK updates its types with each version. If you pin to an older version, your types still describe current_period_end as top-level and your code happily accesses it. The runtime object just doesn't have it. TypeScript can't catch that — types are a compile-time shape, not a runtime guarantee.

Integration tests that mock Stripe. If your tests use recorded fixtures or a mock Stripe library, they validate against yesterday's shape, not today's live API. Your CI stays green while prod returns undefined.

Same pattern as every other silent schema change: the thing that's supposed to catch it was designed against the shape that no longer exists.

What Broke In Practice

A few of the concrete failure modes I've seen or heard about:

Dunning emails stopped. The cron that emails customers "your subscription renews on X" read subscription.current_period_end, got undefined, and sent "your subscription renews on Invalid Date" — or skipped the send entirely.
Customer-facing dashboards went blank. "Next invoice" widgets showed empty cells for every new subscription created after the cutover.
Proration math got weird. Code that calculated time remaining in the current period used current_period_end - Date.now(); when the field was undefined, proration defaulted to zero or to a NaN that cascaded into charge amounts.
Reporting numbers drifted. Analytics jobs that grouped subscriptions by current-period end-date started dropping rows because the field was missing from the row entirely.

None of these are showy failures. No 500s, no exceptions in Sentry. Just wrong or missing data on the customer experience.

The Migration That Actually Works

For the current_period_end move specifically, the honest migration is:

Pin your SDK to the version you've tested. Don't let Dependabot drive your billing API upgrades.
Read periods from items, not the subscription. For single-item subscriptions, subscription.items.data[0].current_period_end is the direct replacement. For multi-item, decide what "period end" means for your use case — the earliest item? The one that matches a specific price? Your code now has to answer that question explicitly.
Update webhook handlers. customer.subscription.updated, invoice.created, and related events use the account API version. Test them against the new shape before flipping your account default.
Stage the upgrade behind a feature flag if you can. Flip it on in staging, compare prod vs staging subscription reads for a week, then promote.

For billing_thresholds, the migration depends on when you started. If you started before 2025-05-28, you might have rewritten on top of metered alerts. Consider whether to revert to billing_thresholds now that it's back — or stay on whatever you built, since the reintroduction might not be permanent either.

How To Catch The Next One

This is the part that generalizes beyond Stripe. Pinning versions works for APIs that version properly. It does not help for the cases where:

The API version didn't change but the response shape did (GitHub Events API, some OpenAI endpoints)
You're on an account-default version and someone upstream flipped it
The SDK was upgraded but the API default was left alone, so your types and runtime disagree
The change is "allowed" within the version contract (e.g., a new optional field that turns out to be required when you want to match the old UX)

The general defense is to watch the shape of the responses you depend on. That can be:

A cron-scheduled script that hits your top N endpoints, hashes the field set, and alerts when the hash changes.
A test that runs nightly against live endpoints (not fixtures) and asserts on the structure of the response.
A purpose-built schema drift monitor.

I've been building FlareCanary for the third option. Point it at the API endpoints you depend on — Stripe, Plaid, OpenAI, Salesforce, whatever — and it polls them on a schedule, learns the response structure, and alerts when a field disappears, a type shifts, or a new field appears. Severity-classified: removed fields are alerts, new optional fields are informational, nullability flips fall somewhere in between.

You do not strictly need a tool for this. You need a habit. The Basil migration is a specific case of a very general problem: the APIs you depend on are changing in ways your type system and your CI can't see. The only reliable signal is watching the live response shape and comparing it to yesterday's.

The Thing That Actually Matters

Stripe did a fine job of the Basil release from the provider side. The changelog was clear. The migration docs existed. The new model is better designed than the old one. The billing_thresholds reintroduction, awkward as it was, was the right call once the replacement turned out to be insufficient.

None of that changed the fact that some number of teams woke up one Monday with blank "next invoice" dates in their dashboards because nobody owned "does the shape of the Subscription object match what our code expects?" as a question worth asking before every API version bump.

That's the monitoring gap. HTTP status codes tell you an endpoint is up. Response latencies tell you it's fast. Neither of those tells you that current_period_end moved three levels deeper into the response tree.

If you're on Stripe and haven't explicitly upgraded to Basil yet, this is your warning. If you already upgraded and everything's green, run a grep for current_period_end across your codebase and see what comes back. It is a very common field, and the number of surprising places it shows up tends to be higher than people expect.

If you've been bit by the Basil migration — or by any silent schema change on another API — I'd like to hear about it. The "undefined field, no error" failures are the ones I'm most interested in. Drop a comment or reach out.

推荐订阅源

DEV Community