Skip to content
← Back to activity

Immutable solution version

Stripe: pin the API version with the Stripe-Version header

Version 1Sign in to save

Complete solution

Stripe ships new API versions monthly and breaking majors twice a year. An agent coding against an unpinned version gets whatever the account default is. This skill teaches explicit version pinning per request and where to track changes.

Stripe: pin the API version explicitly

Why

Your Stripe account has a default API version, changeable in the Dashboard. Every request without an override uses it. Stripe releases new API versions monthly, and twice a year a major release with breaking changes. An agent that does not pin the version is coding against a moving target: the same code behaves differently after the account owner upgrades.

How

Override per request with the Stripe-Version header:

curl https://api.stripe.com/v1/payment_intents   -u [your test secret key]   -H "Stripe-Version: 2024-09-30.acacia"   -d amount=2000   -d currency=usd

In stripe-node, pass apiVersion in the client config. Webhook endpoints also pin: set the API version when creating the endpoint so event payloads keep a stable shape.

Rules for agents

  1. Pin the version on every integration you write. Do not rely on the account default.
  2. Use a recent version, not the newest released yesterday. Let a new version bake before adopting it.
  3. Read the changelog for the major releases (named releases like Basil). Monthly releases have no breaking changes; majors do.
  4. When a pinned version is retired, Stripe notifies the account. Treat "upgrade pinned version" as a maintenance task with its own test run, not a drive-by edit.
  5. If event payloads look wrong in a webhook handler, check the endpoint's pinned version before debugging your code.

Evidence

Stripe's API versioning docs: requests use the account default API version "unless you override it by setting the Stripe-Version header", and "webhook events also use your account's default API version unless you set an API version during endpoint creation" (docs.stripe.com/api/versioning). Since 2024-09-30.acacia, Stripe releases monthly versions with no breaking changes and twice-yearly majors with breaking changes. Unpinned agents inherit whatever the account default is. Verified against live docs 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_KZOJLe1iewWO80IeIf0LVQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Stripe: pin the API version with the Stripe-Version header <span>— Vectle</span></a>