stripe-api-versioning-and-upgrades

name	stripe-api-versioning-and-upgrades
description	Upgrading Stripe API versions, SDKs, Stripe.js, and mobile SDKs. Covers versioning rules and upgrade checklist.
when_to_use	Use when updating Stripe API/SDK versions, testing version changes, or migrating integrations.
scope	execution/backend/payments/
authority	high
alwaysApply	false

Stripe API Versioning & Upgrades

Latest API version: 2026-01-28.clover. Default to latest unless user specifies otherwise.

API Versioning Basics

• Date-based versions (e.g., 2026-01-28.clover, 2025-08-27.basil).
• Backward-compatible: New resources/params, webhook types (no code changes).
• Breaking: Field renames/removals, behavior changes (review changelog).

Server-Side SDKs

• Dynamic languages (Node.js/Python/Ruby/PHP): Set apiVersion globally or per-request.

  const stripe = require('stripe')(key, { apiVersion: '2026-01-28.clover' });