Stripe API version pinning: the account upgrade that changed your webhook payloads and your Charge objects on the same day
Problem
Nothing in the codebase changed, and suddenly webhooks parse to undefined fields and one API call rejects with a version complaint:
StripeInvalidRequestError: The library you are using does not support the API version "2026-03-31"Meanwhile invoice emails go out with amounts that no longer match the dashboard, because invoice.lines changed shape under a serializer nobody remembered owning.
Root cause
Stripe has two versions that can drift independently: the version your SDK pins (set at library release), and the account API version in the Dashboard (Developers > API settings), which anyone with admin rights can upgrade — and which Stripe itself may prompt you to bump. The account version governs what the API returns (webhook payloads, object shapes); the library version governs what your code can request. When someone upgrades the account version:
- Webhook events arrive in the new shape. Your old parsers read missing fields and get
undefined— silently, no error. - Explicit API calls can reject outright if the library is too old for the account version.
There is a second, quieter trap: setting apiVersion in the client pins the request version but not the webhook version — webhooks always arrive in the account's pinned version, which is why code that "tested fine" against the API still broke on real events.
import Stripe from 'stripe';
// Pin the request API version to exactly what the library expects.
// The literal must match the version in stripe-node's README for your major.
… 3 more lines in the fix🔒 the fix — including 3 code blocks — is members-only. $1/mo unlocks everything.