Developing and investigating subscription data flow

/Article

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.

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. The sandboxes page provides the ability to manage each sandbox, allowing you to create, delete, and access them.

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.

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

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.

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 to find your first subscription. You can check the details by clicking on the subscription you want to examine.

To use 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 in order to use it.

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 in order to use it.

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.

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.

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.

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.

To immediately check its cancellation behavior, Stripe provides a subscription simulator called Test Clocks. You can simulate the passage of time by clicking Run simulation on the dashboard.

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.

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.

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.

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.

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.

/About the author

Hidetaka Okamoto

Hide (ひで pronounced “Hee-Day”) is a Developer Advocate at Stripe, where he works on writing, coding, and teaching how to integrate online payments. He has organized several community conferences including WordCamp Kyoto and JP_Stripes Connect 2019, the first Stripe user conference in Japan. Prior to Stripe, Hide was a lead Software Engineer at DigitalCube, focused on building plugins, open source, and developing SaaS application dashboards. Hide lives in Hyogo, Japan with his family and two cats.