Menu
Guide for upgrading Stripe API versions and SDKs
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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
});