API Versioning Fresh

Stripe's API versioning ensures backward compatibility while allowing the platform to evolve.

Current version

The current Stripe API version is 2026-04-22.dahlia.

How versions work

Release type	Description	Backward compatible?
Major release	Named release (e.g., "Acacia", "Dahlia") — may include breaking changes	No — code updates may be required
Monthly release	Minor updates under the same major release name	Yes — safe to upgrade

Breaking changes require upgrading your API version. Stripe sends email notifications before breaking changes and maintains older versions for extended periods.

What Stripe considers backward-compatible

Stripe considers these changes backward-compatible (they will NOT cause a version bump):

• Adding new API resources
• Adding new optional request parameters
• Adding new properties to existing responses
• Changing the order of response properties
• Adding new webhook event types

Breaking changes that DO require a new version:

• Removing or renaming a field
• Changing the type of a field
• Changing the behavior of an existing parameter

Default version behavior

Client	Default version
curl (no header)	Your account's default API version (set in Dashboard → Workbench)
Stripe CLI	Your account's default API version
Newer library versions (node v12+, python v6+, php v11+, ruby v9+)	Version pinned at library release time
Older library versions	Your account's default API version

Setting the API version

Per-request (curl)

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_YOUR_KEY:" \
  -H "Stripe-Version: 2026-04-22.dahlia" \
  -d amount=1000 \
  -d currency=usd

Node.js library

// Pin version at initialization
const stripe = require('stripe')('sk_test_YOUR_KEY', {
  apiVersion: '2026-04-22.dahlia',
});

// Pin version per-request
const paymentIntent = await stripe.paymentIntents.create(
  { amount: 1000, currency: 'usd' },
  { apiVersion: '2026-04-22.dahlia' }
);

Python library

import stripe

stripe.api_version = '2026-04-22.dahlia'

# Or per-request:
payment_intent = stripe.PaymentIntent.create(
    amount=1000,
    currency='usd',
    stripe_version='2026-04-22.dahlia',
)

Webhook API version

Webhook events use the API version set when the endpoint was created. If no version was set, they use your account's default API version.

Best practice: Pin your webhook endpoint to the same version used by your library. This ensures webhook payloads match the types your code expects.

# Set version when creating a webhook endpoint
curl https://api.stripe.com/v1/webhook_endpoints \
  -u "sk_test_YOUR_KEY:" \
  -d url="https://example.com/webhook" \
  -d "enabled_events[]=payment_intent.succeeded" \
  -d api_version="2026-04-22.dahlia"

Upgrading your API version

1. Review the changelog for breaking changes since your current version
2. Test against the new version using the Stripe-Version header in a sandbox
3. Update your code to handle any breaking changes
4. Update your account's default version in Dashboard → Workbench
5. Update your webhook endpoint versions to match

Library version pinning

Newer library versions pin their API version at release time:

Library	Version pinning starts
stripe-node	v12+
stripe-python	v6+
stripe-php	v11+
stripe-ruby	v9+
stripe-java	All versions (strongly typed)
stripe-go	All versions (strongly typed)
stripe-dotnet	All versions (strongly typed)

For strongly-typed libraries (Java, Go, .NET), upgrading the library version upgrades the API version. Check the library changelog to find which API version each library version uses.

Version in responses

Every Stripe API response includes the version used:

Stripe-Version: 2026-04-22.dahlia

Check this header to confirm which version processed your request.