stripe/ai

Overview

This skill is a practical guide for upgrading Stripe API versions and SDKs across server, web, and mobile environments. It explains versioning models, identifies breaking vs. backward-compatible changes, and provides a clear upgrade checklist to reduce regressions. The objective is to help teams plan, test, and deploy Stripe upgrades safely.

How this skill works

The guide inspects Stripe API version types, SDK versioning rules for dynamically-typed and strongly-typed languages, Stripe.js releases, and mobile SDK semantics. It recommends explicit apiVersion configuration, demonstrates per-request testing with the Stripe-Version header, and lays out steps to update SDK packages, webhook handlers, and client libraries. The content emphasizes testing, compatibility checks, and storage considerations for object IDs.

When to use it

• Before updating your account API version or Stripe SDK packages
• When migrating a frontend to a new Stripe.js major release
• When upgrading mobile SDKs (iOS/Android/React Native) to access new features
• When adding new Stripe products or responding to changelog breaking changes
• When validating webhook handlers for new event structures

Best practices

• Always set apiVersion explicitly in your client initialization rather than relying on account defaults
• For dynamically-typed SDKs, prefer per-request or global version overrides for staged testing
• For strongly-typed SDKs, upgrade the SDK to match the target API version instead of overriding
• Test changes using the Stripe-Version header and a staging environment before production rollout
• Handle unknown webhook event types gracefully and update handlers after testing
• Store Stripe object IDs in columns supporting up to 255 characters with case-sensitive collation

Example use cases

• Staging a migration: test 2025-12-15.clover via Stripe-Version header before changing account default
• Frontend change: update script tag or npm package when moving from v3 to a newer Stripe.js major release
• Mobile upgrade: bump iOS/Android SDK major versions to access new APIs and test backend compatibility
• Language-specific plan: upgrade Node/Python SDKs with explicit apiVersion while updating Java/.NET by installing new SDK
• Webhook update: validate new event payload shapes and add defensive parsing for unknown fields