Stripe CLI

A guide to types of payment methods

Stripe Checkout Guide

Workbench Guide

Subscribe to Stripe Developers on YouTube.

Follow us at @Stripedev on twitter for updates and answers to your developer questions.

Sign up for the Developer Digest.

Join the Stripe Discord server to chat live with other developers.

Join Stripe Insiders to try the latest features and provide direct feedback to the teams that build them.


Upgrading the API version of a service your application depends on can result in new features, bug fixes, and even breaking changes. Before applying updates to third party dependencies in production, it is critical that you evaluate how your application reacts to these changes in a test environment. This allows you to safely verify that new API versions integrate smoothly with your application without disrupting your customers.

As a Stripe customer, you can now use the new [Sandboxes](https://docs.stripe.com/sandboxes) feature in the [Dashboard](https://dashboard.stripe.com/). Sandboxes let you create multiple isolated test environments with the option of copying settings from your production account. Within a sandbox account you can build new features, address issues, or explore other Stripe capabilities without the worries of compromising your production environment. Each sandbox comes with its own set of [API keys](https://docs.stripe.com/keys) and access control rules that can be assigned as needed to various members of your team.

If you are exploring the idea of upgrading the Stripe API version in your production account, then Sandboxes provides a good option for creating safe isolated environments to analyze the effects on your software. Before exploring that use case, here’s a brief overview of how Stripe approaches API versioning.

## Stripe API Versioning

Every request sent to the Stripe API targets a particular API version, regardless of whether it is explicitly set or not. The API version defines the behavior of API responses and webhook events. Stripe accounts are automatically assigned the most recent API version from when the first API request is made. This behavior protects users from accidentally receiving breaking changes and reduces the amount of configuration required when getting started.

New versions of the Stripe API get published whenever breaking changes are introduced, and are named based on the date they are released. At the time of writing, the current version of the Stripe API is **2024-06-20**. Backwards-compatible changes are frequently made to the current version but do not result in a new published API version. It is possible to override the API version manually on each request by setting the [**Stripe-Version**](https://docs.stripe.com/libraries/set-version) HTTP header. It is also possible to change the default API version from within the Stripe Dashboard.

To keep track of Stripe API updates, refer to the [Changelog](https://docs.stripe.com/changelog) for an exhaustive list of all changes and the [API Upgrades](https://docs.stripe.com/upgrades#api-versions) documentation for a list of breaking changes. After you have reviewed the list of changes in the upgrades documentation, you should create a safe workspace to examine how your application reacts before moving forward with a production upgrade to a new Stripe API version. As mentioned earlier, you can create one using the Sandboxes feature, which are explored next.

## Provisioning a Sandbox

Before creating a new sandbox to evaluate an API upgrade, confirm what the current default API version is as well as the available version upgrade. To do this, open Workbench in the Stripe Dashboard and open the **Overview** tab. The API versions section shows what the default version for the account is and what the latest version is.

> To enable Workbench in your Stripe account, turn it on via the Dashboard [settings](https://dashboard.stripe.com/settings/developers?).

![](/images/prepare-for-api-upgrades/01.png)

The screenshot above shows this is using a version of the API that is almost 2 years older than the latest one. Clicking on **Upgrade available** opens a dialog that gives you the ability to upgrade the account immediately. **Do not** press the **Upgrade** button until the changes have been properly evaluated.

![](/images/prepare-for-api-upgrades/02.png)


Notice that accounts can only upgrade between the account’s current version and the latest available one. It is not possible to upgrade to an intermediate version once a new one has been released.

To create a new sandbox, click on the account picker menu in the top left corner of the Dashboard and select **Sandboxes** from the dropdown menu.  

![](/images/prepare-for-api-upgrades/03.png)

Once you are on the Sandboxes page, click on the **Create** button and give your sandbox a name. Optionally, toggling the settings switch beneath the text box copies over configuration from your production account into the sandbox. These settings do not include any data such as product, customer or transaction information. A list of what settings are copied into the sandbox is available on the [Sandbox settings](https://docs.stripe.com/sandboxes/dashboard/sandbox-settings) documentation page.

![](/images/prepare-for-api-upgrades/04.png)

Copying account settings speeds up your time to productivity by eliminating the need to verify and activate business details in the sandbox environment. Changes to configuration settings within the sandbox are not copied back to the production account.

After creating the sandbox, it’s set as the current context within the Dashboard.

![](/images/prepare-for-api-upgrades/05.png)

## Upgrading the API Version

Opening Workbench in the newly created sandbox account and navigating to the **Overview** tab reveals the default API version is set to the same value as the production account. You now have a safe space to test your application against the target version. As shown before, API upgrade requests are made through the upgrade dialog in Workbench.

After the upgrade is complete, the **Overview** highlights that the default API version is to the latest available.

![](/images/prepare-for-api-upgrades/06.png)

If needed, you can roll back to the previous API version you upgraded from through the API versions section in Workbench. In production, you have 72 hours before the upgrade becomes permanent.

## Using the Sandbox

To test your application against the newer API version, configure its setting to use the API keys provided by the sandbox. These can be retrieved from the **Overview** tab of Workbench. Clicking on **Manage** in the [API keys](https://dashboard.stripe.com/test/apikeys) section takes you to the Developers page where they can be copied. 

The default API version of the main Stripe account is 2022-11-15, but in the sandbox it is set to 2024-06-20. If the application uses one of the Stripe SDKs, it must be one that is compatible with that version of the API. In the case of .NET, that maps to version [41.0.0](https://github.com/stripe/stripe-dotnet/blob/master/CHANGELOG.md#4100---2022-11-16) of [Stripe.net](https://github.com/stripe/stripe-dotnet) for API version 2022-11-15. 

> SDKs for strongly-typed languages like Go, Java and .NET are fixed to the latest version at the time of release. SDKs for dynamic languages like Ruby, Python, and Node.js allow you to set the configured API version globally and on a per request basis.

The code sample below shows a minimal API created with ASP.NET Core and v41.0.0 of the Stripe .NET SDK. Imagine that this is your application.

```csharp
using Stripe;
var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

StripeConfiguration.ApiKey = "<your-secret-key>";
const string webhookSecret = "<your-webhook-secrey>";

app.MapPost("/stripe/webhook", async(HttpRequest request) => {
  var payload = await new StreamReader(request.Body).ReadToEndAsync();

  var stripeEvent = EventUtility.ConstructEvent(
      payload, request.Headers["Stripe-Signature"], webhookSecret);
  
  // Do something fun
  return Results.Ok();
});

app.Run();
```

The code creates an endpoint that receives and processes events from the configured Stripe account using the Secret and Webhook key. Before executing the code, you need to forward events from Stripe to your machine using the [Stripe CLI](https://docs.stripe.com/stripe-cli). Open a new command prompt on your machine and enter the following command to authenticate the CLI with your sandbox.

```bash
stripe login
```

The response instructs you to visit a URL in your browser to grant permission to your sandbox.

![](/images/prepare-for-api-upgrades/07.png)

After authenticating the CLI, return to your command prompt and run the following command to forward Stripe events to the endpoint on your machine. 

```bash
stripe listen --forward-to http://localhost:5000/stripe/webhook 
```

Next, start a debugging session for the application and trigger an [event](https://docs.stripe.com/api/events/types). Test events can be triggered through the Stripe CLI using the trigger command.

```bash
stripe trigger customer.created  
```

At this point, the code fails with the following exception message.

```bash
Stripe.StripeException: 
 Received event with API version 2024-09-30.acacia, but Stripe.net 41.0.0 expects API version 2022-11-15.
```

This happens because there is an API mismatch between what the account is configured with and what the application supports. By using a sandbox, these types of errors can be caught and fixed in isolation before promoting an API upgrade to production.

Luckily, this error can be fixed quickly by upgrading Stripe.net to 46.0.0. After making the update, running the code and triggering a new event shows the API mismatch error has been resolved.

## Conclusion

Navigating API upgrades for third party services can be challenging, especially if there isn’t a safe space to evaluate them before incorporating them into production code. Using isolated environments for development and testing enables developers to deploy application updates with more confidence. By testing API upgrades in a sandbox, you can identify potential issues and fine-tune your implementation without impacting your production environment. This approach not only minimizes risks but also accelerates the development process by allowing teams to experiment and iterate more freely.

To learn more about developing applications with Stripe, visit our [YouTube Channel](https://www.youtube.com/stripedevelopers).


New Stripe API versions come with new, and sometimes breaking, changes which should be evaluated before upgrading. Stripe Sandboxes and Workbench provide tooling to create isolated workspaces to test applications against these new changes.

Preparing for Stripe API Upgrades

Preparing for Stripe API Upgrades

Cecil Phillip