Menu
Guide for upgrading Stripe API versions and SDKs
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Use when rendering or sourcing a customer app's icon/favicon or screenshot/art on ANY surface — the homepage launcher card (web-app/src/pages/launcher), the admin apps browser (web-app/src/pages/admin/AdminCustomerApps), an app rail tile, or any new place that shows an app's picture. Also when adding icon/art fields to an apps API DTO (workspace_custom_apps.rs, admin/apps/handlers.rs). Triggers on "app icon", "app favicon", "app art", "app screenshot", "AppCard icon", "AppFavicon", "icon_url", "art_url", "launcher card image", "app thumbnail/preview", "monogram fallback".
Use when adding or modifying a customer-app serving route (crates/app/src/server/api/customer_apps_serve.rs, the /customer-apps/{*path} handler in serve.rs) or a customer-app data endpoint (projects/query.rs, projects/semantic_query.rs). Encodes the serve-plane + data-plane performance guardrails so every customer app stays fast. Triggers on "customer-app cache", "Cache-Control", "ETag", "compression on customer-apps", "result cache", "project-scoped cache", or a new per-request read on the customer-app hot path.
Use when adding a new YAML entity type to Oxy (e.g. a new file extension under `crates/oxy-compile/src/walker.rs` like `.foo.yml`), when introducing a new runtime read site that walks the workspace filesystem, when wiring a new handler that calls `ConfigManager::resolve_*` or `fs::read_to_string(workspace_path...)`, or any time someone proposes a feature that "just reads from the workspace dir." Also triggers on phrases like "new file extension", "add a YAML config", "load this from disk", "scan the workspace for", "read the YAML file" — the compile boundary expects every NEW workspace artifact to be a row in Postgres, not a per-request FS read.
Use when the user asks about Oxy's multi-instance scaling, the split fleet, worker fleet, horizontal scaling, high availability, or how the serve/ide/worker roles divide work. Triggers include "scale Oxy", "scale oxygen", "multi-instance", "split fleet", "worker fleet", "horizontal scaling", "high availability", "OXY_ROLE", "stateful vs HA", "compile boundary", "stateless serving", "durable execution", "shard workspaces", "ephemeral environments", "internal jobs admin".
Use when adding, moving, or renaming an HTTP route under `crates/app/src/server/router/` (any `.route(...)` / `.nest(...)` mount), or writing a request handler that reads the workspace working copy, `.git`, or the local state dir (`config_manager.workspace_path()`, `ConfigManager::resolve_*`, `resolve_state_dir()`, `fs::read*(workspace_path…)`, a `glob` of the workspace dir, a `GitClient`). Also triggers on "add an endpoint", "new API route", "421", "x-oxy-required-role", "served on serve but the file isn't there", "role_manifest", "IdeOnly", "self-routing", and the HIGH-AVAILABILITY side: "FLEET_OK_READ_PATTERNS", "high availability", "thread/conversation won't load when the ide is down", "a read is pinned to the singleton", "viewing needs the factory". Every route that touches node-local disk MUST be classified IdeOnly or it 404s/421s on the stateless serve fleet — and conversely, every persisted-data READ must stay FleetOk (any replica) or HA hinges on one instance.
Use when adding or modifying code in `crates/app/src/server/` or HTTP handlers that involves long-running compute, periodic schedules, multi-step pipelines, or any work that must survive instance death. Triggers include "spawn a background task", "schedule periodically", "run async after returning", "long-running operation", "fire and forget", "tokio::spawn", "background job", "queue this", or PRs that add new work to HTTP handlers. Also triggers when designing features that touch LLM APIs, git clones, embedding builds, or any operation taking >5 seconds.
| name | upgrade-stripe |
| description | Guide for upgrading Stripe API versions and SDKs |
The latest Stripe API version is 2026-03-25.dahlia - use this version when upgrading unless the user specifies a different target version.
This guide covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
Stripe uses date-based API versions (e.g., 2026-03-25.dahlia, 2025-08-27.basil, 2024-12-18.acacia). Your account’s API version determines request/response behavior.
Backward-Compatible Changes (don’t require code updates):
Breaking Changes (require code updates):
Review the API Changelog for all changes between versions.
See SDK Version Management for details.
These SDKs offer flexible version control:
Global Configuration:
import stripe
stripe.api_version = '2026-03-25.dahlia'
Stripe.api_version = '2026-03-25.dahlia'
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-03-25.dahlia'
});
Per-Request Override:
stripe.Customer.create(
email="customer@example.com",
stripe_version='2026-03-25.dahlia'
)
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.
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-03-25.dahlia'
});
// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');
See Stripe.js Versioning for details.
Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover, Dahlia) on a biannual basis.
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.
Each Stripe.js version automatically pairs with its corresponding API version. For instance:
2026-03-25.dahlia API2024-12-18.acacia APIYou can’t override this association.
See Mobile SDK Versioning for details.
Both platforms follow semantic versioning (MAJOR.MINOR.PATCH):
New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
Uses a different model (0.x.y schema):
All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
npm update stripe, pip install --upgrade stripe)apiVersion parameter in your Stripe client initializationStripe-Version headerUse 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-03-25.dahlia"
Or in code:
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-03-25.dahlia' // Test with new version
});