Upgrade Stripe Agent Skill

The latest Stripe API version is 2026-07-29.dahlia - use this version when upgrading unless the user specifies a different target version.

Upgrading Stripe Versions

This guide covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.

Understanding Stripe API Versioning

Stripe uses date-based API versions (e.g., 2026-07-29.dahlia, 2025-08-27.basil, 2024-12-18.acacia). Your account’s API version determines request/response behavior.

Types of Changes

Backward-Compatible Changes (don’t require code updates):

• New API resources
• New optional request parameters
• New properties in existing responses
• Changes to opaque string lengths (e.g., object IDs)
• New webhook event types

Breaking Changes (require code updates):

• Field renames or removals
• Behavioral modifications
• Removed endpoints or parameters

Review the API Changelog for all changes between versions.

Server-Side SDK Versioning

See SDK Version Management for details.

Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)

These SDKs offer flexible version control:

Global Configuration:

import stripe
stripe.api_version = '2026-07-29.dahlia'

Stripe.api_version = '2026-07-29.dahlia'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'
});

Per-Request Override:

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-07-29.dahlia'
)

Strongly-Typed Languages (Java, Go, .NET)

These use a fixed API version matching the SDK release date. Don’t set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version.

Best Practice

Always specify the API version you’re integrating against in your code instead of relying on your account’s default API version:

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'
});

// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');

Stripe.js Versioning

See Stripe.js Versioning for details.

Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover, Dahlia) on a biannual basis.

Loading Versioned Stripe.js

Via Script Tag:

<script src="https://js.stripe.com/dahlia/stripe.js"></script>

Via npm:

npm install @stripe/stripe-js

Major npm versions correspond to specific Stripe.js versions.

API Version Pairing

Each Stripe.js version automatically pairs with its corresponding API version. For instance:

• Dahlia Stripe.js uses 2026-07-29.dahlia API
• Acacia Stripe.js uses 2024-12-18.acacia API

You can’t override this association.

Migrating from v3

• Identify your current API version in code
• Review the changelog for relevant changes
• Consider gradually updating your API version before switching Stripe.js versions
• Stripe continues supporting v3 indefinitely

Mobile SDK Versioning

See Mobile SDK Versioning for details.

iOS and Android SDKs

Both platforms follow semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Breaking API changes
• MINOR: New functionality (backward-compatible)
• PATCH: Bug fixes (backward-compatible)

New features and fixes release only on the latest major version. Upgrade regularly to access improvements.

React Native SDK

Uses a different model (0.x.y schema):

• Minor version changes (x): Breaking changes AND new features
• Patch updates (y): Critical bug fixes only

Backend Compatibility

All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.

Upgrade Checklist

• Review the API Changelog for changes between your current and target versions
• Check Upgrades Guide for migration guidance
• Update server-side SDK package version (e.g., npm update stripe, pip install --upgrade stripe)
• Update the apiVersion parameter in your Stripe client initialization
• Test your integration against the new API version using the Stripe-Version header
• Update webhook handlers to handle new event structures
• Update Stripe.js script tag or npm package version if needed
• Update mobile SDK versions in your package manager if needed
• Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)

Testing API Version Changes

Use the Stripe-Version header to test your code against a new version without changing your default:

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-07-29.dahlia"

Or in code:

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'  // Test with new version
});

Important Notes

• Your webhook listener should handle unfamiliar event types gracefully
• Test webhooks with the new version structure before upgrading
• Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
• Multiple API versions coexist simultaneously, enabling staged adoption