- v1.0.0-latest-prod
While dynamic languages let you freely override the API version via a configuration property in your code, the Java SDK pins a specific, fixed API version inside each SDK release.
Stripe releases two types of updates for its API:
Monthly Releases: These contain only backward-compatible changes (new fields, optional parameters).
Major Releases (e.g., Acacia, Basil, Dahlia): Released twice a year, these contain breaking changes (renamed fields, altered types, or deleted endpoints).
Because Java is a strongly-typed language, Stripe compiles the stripe-java library’s classes and methods to match a precise JSON payload shape.
The Pinned Version: Every version of stripe-java has a specific Stripe API date hardcoded into it (accessible via Stripe.API_VERSION).
The Golden Rule: Do not try to force a Java SDK to use a different API version. If you override the Stripe.API_VERSION string manually to a newer API version, Stripe will send back JSON fields that your older Java classes don’t recognize, which will crash your app with runtime deserialization errors.
When it’s time to upgrade your integration, you have to handle two things simultaneously: your outbound API requests and your inbound webhooks. Here is the safest playbook to avoid downtime.
Go to the Stripe Workbench in your dashboard to see your current default API version and what the latest available version is.
Check the Stripe API Changelog and the stripe-java GitHub Releases wiki to identify what broke between your current version and your target version.
Instead of changing a version string in Stripe, you change your project dependency (e.g., in your pom.xml or build.gradle).
Update your stripe-java dependency version to the release that natively uses your target API version.
Fix Compile Errors: Because Java is strongly typed, your IDE will immediately light up with red squiggly lines wherever a method signature changed or a field was removed. Fix all compile-time errors to align with the new SDK models.
This is where developers usually get tripped up during rolling deployments. Webhooks sent by Stripe use your Account’s Default API Version (unless explicitly set otherwise on the webhook endpoint). The Risk: If you update your server code first, it expects the new format but receives old webhook data. If you upgrade your dashboard first, your old servers receive new webhook data and crash.
The Fix:
1. In the Stripe Dashboard, create a brand-new Webhook Endpoint pointing to your production URL, and explicitly set its version to match the new API version your upgraded code expects.
2. Keep your old webhook endpoint active (set to your old API version).
3. Deploy your new Java server code. During the rolling deployment:
Old servers will parse events from the old webhook endpoint correctly.
New servers will parse events from the new webhook endpoint correctly.
(Note: Ensure your backend safely handles duplicate evt_ IDs natively if Stripe delivers an event to both endpoints).
Once 100% of your servers are running the new Java SDK code, go to the Stripe Workbench.
Click Upgrade available and upgrade your account’s default API version.
Delete the old webhook endpoint from your dashboard. (Stripe gives you a 72-hour window after clicking upgrade in the dashboard to roll back immediately if you notice something throwing unhandled exceptions).