git:20260401.d9d04a9 to git:20260720.d26d2c8

---

name: upgrade-stripe

description: Guide for upgrading Stripe API versions and SDKs

license: MIT

---

# Upgrading Stripe Versions

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

## Understanding Stripe API Versioning

### 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](https://docs.stripe.com/changelog.md) for all changes between versions.

## Server-Side SDK Versioning

See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details.

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

These SDKs offer flexible version control:

**Global Configuration:**

```python

import stripe

```

```ruby

```

```javascript

const stripe = require('stripe')('sk_test_xxx', {

});

```

**Per-Request Override:**

```python

stripe.Customer.create(

email="customer@example.com",

)

```

### 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:

```javascript

// Good: Explicit version

const stripe = require('stripe')('sk_test_xxx', {

});

// Avoid: Relying on account default

const stripe = require('stripe')('sk_test_xxx');

```

## Stripe.js Versioning

See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) 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:**

```html

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

```

**Via npm:**

```bash

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:

- Acacia Stripe.js uses `2024-12-18.acacia` API

You can’t override this association.

### Migrating from v3

1. Identify your current API version in code

## Mobile SDK Versioning

See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) 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

1. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions

## Testing API Version Changes

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

```bash

curl https://api.stripe.com/v1/customers \

-u sk_test_xxx: \

```

Or in code:

```javascript

const stripe = require('stripe')('sk_test_xxx', {

});

```

## 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