मुख्य कंटेंट तक स्किप करें

API versioning and upgrades

Stripe versions the whole API, not individual endpoints. A version string marks a snapshot of response fields and behavior. Your account pins one version, and every request without an override uses it.

Version sources​

LayerSettingScope
AccountDefault API version in the DashboardEvery request that omits the header
RequestStripe-Version headerOne request
Client libraryVersion bundled with the SDK releaseRequests sent through that client

The account pin prevents silent breakage. Stripe can release a new default version, and your integration keeps returning the fields it parsed last year.

Override the version​

Send Stripe-Version to test a different snapshot without touching the account default.

curl https://api.stripe.com/v1/payment_intents/pi_3Rsx4dDtWMrPDtgt0mUrePJ9 \
-u "$STRIPE_SECRET_KEY:" \
-H "Stripe-Version: 2024-06-20"
Node.js
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});

The header accepts a dated version such as 2024-06-20. Some releases append a codename, which you must copy exactly from the Dashboard.

नोट

A version override changes request behavior as well as response fields. Read the changelog entry before you adopt a version.

What can change​

Stripe separates additive changes from breaking ones.

ChangeReleases in any versionRequires a new version
---------
New optional request parameterYesNo
New response fieldYesNo
New event type for webhooksYesNo
Renamed fieldNoYes
Changed field typeNoYes
Removed fieldNoYes
Changed default valueNoYes

A client that ignores unknown fields accepts every additive change. A client that validates responses against a closed schema fails on the first new field.

Build a forward-compatible parser​

Read the fields you need and ignore the rest. Never fail a response because of an extra key.

Node.js
function readAmount(intent) {
const amount = intent.amount;

if (typeof amount !== "number") {
throw new Error("amount is missing from the PaymentIntent response");
}

return amount;
}

The check confirms the field you depend on. It leaves the rest of the object alone, so a new amount_details key or a new status value doesn't crash the parser.

चेतावनी

Don't branch on the full response structure, such as comparing keys against a fixed list. Stripe adds fields in most releases, and a strict comparison fails on the next one.

Upgrade in test mode​

Run this sequence before you move the account pin.

  1. Open the API changelog and read every entry between your version and the target.
  2. Note the fields your code reads and the request parameters it sends.
  3. Send a sample of real requests with the Stripe-Version header set to the target.
  4. Compare the responses against your parser, not against a visual diff alone.
  5. Run the integration test suite against the target version.
  6. Deploy the code that handles the old and new response formats, if the change needs it.
  7. Change the account default in the Dashboard.
  8. Watch the error rate and the webhook failure rate for one payout cycle.
सुझाव

Test with a restricted key scoped to the resources in the suite. A full secret key in a version test can leave stray objects in the account.

Keep SDK and API versions aligned​

An SDK release bundles a default API version. Upgrading the library can move your requests to a newer snapshot even when the account pin hasn't changed.

ActionEffect on the API version
Upgrade the SDK and accept its defaultRequests use the version bundled with the release
Upgrade the SDK and set apiVersionRequests use the version you name
Change the Dashboard defaultAffects requests that send no header and set no client version

Set apiVersion explicitly when you upgrade the library. That keeps the API snapshot fixed while you review the SDK changes on their own.

Handle webhooks across versions​

A webhook event records the API version that created it, under api_version. Stripe sends events with the version pinned to the endpoint, not the version pinned to the account.

Read the consequences before you share one handler across both paths.

  • Separate pins. An endpoint can deliver events on a different version than your API calls use.
  • Field drift. A field you read from an API response may not exist on the event payload.

Read the event's api_version when you log a payload, and validate the fields the handler needs rather than the whole object.

Next steps​