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.


This article shows you how to use [Stripe's sandbox](https://docs.stripe.com/sandboxes) to simplify your development process. You'll learn to create isolated test environments, simulate real-world scenarios, and debug your subscription logic efficiently. 

Building a robust subscription system can be challenging. By following this article, you'll gain practical skills to handle complex situations like trial periods, plan changes, and payment failures. Whether you're new to Stripe or an experienced developer, you'll discover how to use Stripe's tools to build a more reliable and flexible subscription system.

## Create a clean test environment with a single click

When considering the introduction of a new SaaS or API, it's important to have test data or a demo account. Ideally, these test environments should be free of any data unrelated to the test. If multiple people are conducting testing at the same time, it is also good to have an environment where their operations and logs do not get mixed up.

Stripe addresses these concerns by using a sandbox environment. Sandboxes are disposable test environments for developers, and a single Stripe account allows for the creation of up to five of them.

The following scenario creates a new test environment for investigating how to build a new subscription system. To create a new test environment (sandbox), click the **Create** button on [the Dashboard](https://dashboard.stripe.com/test/sandboxes). The sandboxes page provides the ability to manage each sandbox, allowing you to [create, delete, and access](https://docs.stripe.com/sandboxes/dashboard/manage) them.

![](/images/developing-and-investigating-subscription-data-flow/image1.png)

When creating a sandbox, a new test environment is prepared, completely isolated from production. In this sandbox, API keys, webhook settings, customer data, and everything else is provided in a clean state. This allows you to freely experiment when testing specific features or integrations without affecting existing data or settings.

![](/images/developing-and-investigating-subscription-data-flow/image2.png)  

Create the first subscription and customer by clicking the **\+** button on the header navigation.  

![](/images/developing-and-investigating-subscription-data-flow/image3.png)

Stripe provides a simple web form to create a new subscription. You can create it by filling out the following details: customer email address, product name, price, billing frequency, and quantity.

![](/images/developing-and-investigating-subscription-data-flow/image4.png)

## Trace dashboard operations at the API / event level

When developing a new system, first clarify how it should behave. Consider not only successful application scenarios but also contract and system integration changes after trial periods end. Include workflows for plan changes. This approach helps prevent unintended behavior and overlooked use cases.

In Stripe, use a sandbox account on the dashboard to identify these scenarios. The workbench helps you check data changes based on operations and send webhook events. Analyze the behavior when modifying subscription plans on the dashboard to gain deeper insights.

Navigate to the [subscription management page](https://dashboard.stripe.com/test/subscriptions) to find your first subscription. You can check the details by clicking on the subscription you want to examine.  

![](/images/developing-and-investigating-subscription-data-flow/image5.png)  

To use [Workbench](https://docs.stripe.com/workbench), access it through the Stripe dashboard by clicking on the **Developers** link and then selecting **Workbench**. You can also launch it by pressing the \`\~\` key on your keyboard when in the Stripe Dashboard. If you don't see this link or button, you need to enable Workbench in the [Developers Settings page](https://dashboard.stripe.com/settings/developers) in order to use it.

![](/images/developing-and-investigating-subscription-data-flow/image6.png)

After opening the **Workbench**, you will see an **Inspector** examining the subscription. The inspector allows you to view the resource data as JSON code and displays lists of API calls and events. If you don't see this link or button, you need to enable Workbench in the [Developers Settings page](https://dashboard.stripe.com/settings/developers) in order to use it.  

![](/images/developing-and-investigating-subscription-data-flow/image7.png)

To learn how to create a similar subscription using API calls, navigate to the **Logs** tab. You can find the **POST request to "/v1/subscription"**, which is used to create a subscription.  

![](/images/developing-and-investigating-subscription-data-flow/image8.png)

The **Request POST Body** of this log reveals the API request details for the plan change. Compare these parameter values with the API documentation to confirm your implementation.

![](/images/developing-and-investigating-subscription-data-flow/image9.png)  

To understand how to integrate Stripe with your system, check the **Events** tab. There, you can see what types of events Stripe sends when a new subscription is created. The *customer.subscription.created* event notifies you when a new subscription is created, and the *invoice.created* event means the invoice has been generated. You can learn more about subscription-related events on the [Stripe documentation page](https://docs.stripe.com/billing/subscriptions/webhooks).  

![](/images/developing-and-investigating-subscription-data-flow/image10.png)

As demonstrated above, the workbench provides crucial information for implementation planning, particularly API request parameters. In the **Inspector** tab's **Logs** section, you can examine request contents for API calls, Stripe CLI operations, and dashboard actions.

## Time advancement with the Test clock

In the case of a subscription system, you need to test various scenarios like plan updates, cancellations, and late payment scenarios. The easiest way to test each scenario is by modifying subscriptions from the dashboard.The following scenario cancels a subscription at the end of the billing period. Schedule a subscription cancellation by selecting **Cancel subscription** from the **Actions** menu.

![](/images/developing-and-investigating-subscription-data-flow/image12.png) 

To immediately check its cancellation behavior, Stripe provides a subscription simulator called [**Test Clocks**](https://docs.stripe.com/billing/testing/test-clocks?). You can simulate the passage of time by clicking **Run simulation** on the dashboard.  

![](/images/developing-and-investigating-subscription-data-flow/image13.png)

After the modal pops up, set the new date beyond the end of the subscription period. Then, click the "Advance" button to start simulating the passage of time. This simulates the state change that occurs during a subscription cancellation, allowing you to test your system's response to this event.

![](/images/developing-and-investigating-subscription-data-flow/image14.png)

Once the test clock simulation is complete, the subscription status changes to **Canceled**. You can see what events Stripe sent to your system when the customer subscription was canceled by visiting the **Events** tab in the **Workbench**. The *customer.subscription.deleted* event is a notification about the subscription cancellation. You can examine the event data to see what information your system will receive from this event.  

![](/images/developing-and-investigating-subscription-data-flow/image15.png)

This browser-based approach provides easy access to information crucial for planning your Stripe integration.

## Implementation methods through in browser shell 

In the Stripe dashboard, you can investigate data and test API requests, which helps clarify your implementation strategy. To test an API request, open the **Shell** tab in Workbench. Here, you can use the Stripe CLI directly in your browser. To simplify the process, the UI includes an **API Explorer** on the right. It allows you to check API parameters and set their values. Once you configure the API and its parameters, the values are converted into CLI commands that you can execute immediately.

![](/images/developing-and-investigating-subscription-data-flow/image16.png)  

The **Shell** tab provides a feature to convert commands into implementation code. By clicking the **Print SDK Request** button, you can generate source code in the language you choose. You can then copy this code into your application, and replace the values with variables to continue developing your Stripe integration.  

![](/images/developing-and-investigating-subscription-data-flow/image17.png)  

Using these developer-oriented features in the Stripe Dashboard, you can streamline the entire process—from defining subscription and payment system requirements to designing workflows, testing API requests, and converting them into application code—all within a single browser tab.

## **Conclusion**

Remember that thorough testing across various scenarios is crucial for building a robust subscription system. You need to consider not only when, who, how, and how much to charge but also various payment scenarios. These include managing plan changes, handling service suspensions due to lost or stolen credit cards, and addressing non-payment issues caused by expired cards.

Stripe sandbox provides powerful tools for implementing and testing your subscription-based services. You can quickly set up a clean test environment, and simulate complex scenarios like plan changes, trial expirations, and payment failures. And Stripe dashboard helps you analyze API calls and events to understand the subscription lifecycle,  and streamline the development process for testing to implementation.

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

![](/images/YouTube.png)

This article shows you how to use Stripe's sandbox to simplify your development process. You'll learn to create isolated test environments, simulate real-world scenarios, and debug your subscription logic efficiently. 

Developing and investigating subscription data flow

Developing and investigating subscription data flow

Hidetaka Okamoto