upgrade-stripe

---
name: upgrade-stripe
description: Guide for upgrading Stripe API versions, SDKs, and mobile libraries. Use when updating Stripe integrations to newer versions.
license: MIT
---

# Upgrade Stripe

Guide for upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.

## When to Use This Skill

- Upgrading Stripe API versions
- Updating Stripe SDKs (server-side, web, mobile)
- Migrating between Stripe.js versions
- Planning Stripe integration maintenance
- Understanding Stripe versioning strategy
- Testing API version changes

## Understanding Stripe API Versioning

Stripe uses **date-based API versions** (e.g., `2025-12-15.clover`, `2025-08-27.basil`, `2024-12-18.acacia`).

### Types of Changes

**Backward-Compatible** (no code changes needed):
- New API resources and endpoints
- New optional request parameters
- New properties in responses
- Changes to opaque string lengths
- New webhook event types

**Breaking Changes** (require code updates):
- Field renames or removals
- Behavioral modifications
- Removed endpoints or parameters

**Always review:** [API Changelog](https://docs.stripe.com/changelog.md)

## Server-Side SDK Versioning

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

**Global Configuration:**
```python
import stripe
stripe.api_version = '2025-12-15.clover'
```

```javascript
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});
```

**Per-Request Override:**
```python
stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2025-12-15.clover'
)
```

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

- Use fixed API version matching SDK release date
- **Do not** set different API version - types won't match
- Update SDK version to target new API version

### Best Practice

**Always specify API version explicitly:**
```javascript
// ✅ Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});

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

## Stripe.js Versioning

Uses **evergreen model** with major releases (Acacia, Basil, Clover) biannually.

### Loading Versioned Stripe.js

**Via Script Tag:**
```html
<script src="https://js.stripe.com/clover/stripe.js"></script>
```

**Via npm:**
```bash
npm install @stripe/stripe-js
```

### API Version Pairing

Each Stripe.js version automatically pairs with corresponding API version:
- **Clover** → `2025-12-15.clover`
- **Basil** → `2025-08-27.basil`
- **Acacia** → `2024-12-18.acacia`

**Cannot override this association.**

### Migrating from v3

1. Identify current API version
2. Review changelog for relevant changes
3. Consider gradual API version updates first
4. Stripe supports v3 indefinitely

## Mobile SDK Versioning

### iOS and Android SDKs

Follow **semantic versioning** (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking API changes
- **MINOR**: New features (backward-compatible)
- **PATCH**: Bug fixes (backward-compatible)

**Upgrade regularly** - new features release only on latest major version.

### React Native SDK

Uses **0.x.y schema**:
- **Minor version (x)**: Breaking changes + new features
- **Patch (y)**: Critical bug fixes only

### Backend Compatibility

All mobile SDKs work with any Stripe API version unless documented otherwise.

## Upgrade Checklist

1. **Review Changelog**: [API Changelog](https://docs.stripe.com/changelog.md)
2. **Check Migration Guide**: [Upgrades Guide](https://docs.stripe.com/upgrades.md)
3. **Update Server SDK**: `npm update stripe`, `pip install --upgrade stripe`
4. **Update API Version**: Set `apiVersion` parameter explicitly
5. **Test Integration**: Use `Stripe-Version` header for testing
6. **Update Webhooks**: Handle new event structures
7. **Update Stripe.js**: Update script tag or npm package
8. **Update Mobile SDKs**: Update via package manager
9. **Database Prep**: Ensure string fields accommodate 255 characters

## Testing API Changes

**Test without changing defaults using `Stripe-Version` header:**

```bash
curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2025-12-15.clover"
```

**Or in code:**
```javascript
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'  // Test mode
});
```

## Important Considerations

- **Webhook Compatibility**: Handle unfamiliar event types gracefully
- **Testing**: Test webhooks with new version before upgrading
- **Staged Adoption**: Multiple API versions coexist simultaneously
- **Breaking Changes**: Tagged by product areas (Payments, Billing, Connect)
- **Database Schema**: Store Stripe IDs in 255-character fields with case-sensitive collation

## Version Upgrade Workflow

### 1. Planning Phase
- Identify target API version
- Review changelog for breaking changes
- Plan migration timeline

### 2. Development Phase
- Update SDK versions
- Modify code for breaking changes
- Update webhook handlers
- Update test suites

### 3. Testing Phase
- Use Stripe-Version header testing
- Test all payment flows
- Verify webhook handling
- Test error scenarios

### 4. Deployment Phase
- Gradual rollout if possible
- Monitor for issues
- Have rollback plan ready