Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in

Set a Stripe API version

Follow these guidelines to make sure that API versions match throughout your Stripe integration.

Your account has a default API version, which defines how you call the API, what functionality you have access to and what you’re guaranteed to get back as part of the response. Webhook event objects are based on your default API version, which might be different from the API version used by the SDK. To make sure these versions match, we recommend registering a webhook endpoint with the same API version used as the SDK. To find your version, see View the API versions used by API requests.

Versioning basics

Choose your SDK language to get started. If you’re using curl or Stripe CLI instead of an SDK, refer to our versioning page.

Setting the API version

Because C# is a strongly-typed programming language, the API version used in the .NET SDK is fixed and is the latest API version at the time of the SDK release.

We don’t recommend setting a different API version for strongly-typed programming languages, because the response objects might not match the strong types in the SDK and result in request failures. For example, if the API version you’re targeting requires parameters that aren’t present in the SDK types, the request fails.

Upgrading your API version

Before upgrading your API version, carefully review the following resources:

You can upgrade your account’s default API version in Workbench. Update your code to use the latest version of the .NET SDK to make sure all your requests target the latest API version.

Upgrading your webhook handlers for a new API version

During the upgrade process, we recommend creating and maintaining two webhook endpoints with two different API versions: one for your existing API version, and one for the API version that you want to upgrade to. This allows you to test your new code while maintaining the ability to safely roll back to your existing version if needed.

  1. Write new webhook event handling code using the version of the SDK you want to upgrade to. When handling incoming events, store the raw body of the request from Stripe in a queue that’s processed sequentially.
  2. Register a new webhook endpoint with the API version you’re upgrading to and point to your new webhooks URL. You can register a webhook endpoint in Workbench or with the API (as shown):
curl
Java
Go
.NET
No results
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
StripeConfiguration.ApiKey = 
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
;

var options = new WebhookEndpointCreateOptions
{
  Url = "https://example.com/my/webhook/endpoint",
  EnabledEvents = new List<String>
  {
    "payment_intent.succeeded",
    "payment_intent.payment_failed",
  },
  ApiVersion = "2020-03-02",
};
var service = new WebhookEndpointService();
var webhookEndpoint = service.Create(options);
  • Be sure to test your webhooks integration (for example, use the Stripe CLI to trigger events). After you’re confident that your webhooks integration works as intended, you can start processing events in production and disable or delete your old webhook endpoint.

Caution

During the upgrade process, make sure you don’t have separate code processing the same events twice. We recommend having a process or mechanism for switching live event processing between your old code and your new code.

If you aren’t using an event queue, modify your old code to stop processing events and respond with a 400 HTTP status code. If the new code isn’t working as expected and you need to revert to the old code, turn the event processing logic back on and allow it to respond normally. Doing this within the 3-day rollback window ensures you’ll receive all the events retried without missing any.

See also

Stripe SDKs follow their own versioning policy. See the link below to learn more.

Was this page helpful?
YesNo