Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
How subscriptions work
How to model subscriptions
Get started
Quickstart
Design an integration
Build a subscriptions integration
Integrate the customer portal
Migrate subscriptions to Stripe
Billing resources
Coupons
Customers
Subscriptions
Subscription invoices
Manage subscriptions
Change subscriptions
Use trial periods
Set payment methods
Subscriptions with multiple products
Set subscription quantities
Subscription webhooks
Schedule subscriptions
Tax
Integrate with Salesforce
Manage recurring revenue
Revenue recognition
Revenue recovery
Subscription metrics
Testing
Test your integration
Test clocks
Metered billing with Elements
Fixed-price billing with Elements
Per-seat billing with Elements
Migrate to Prices
Strong Customer Authentication (SCA)
Invoices API updates
Improved tax support
Testing
No-code options
Billing
·
HomePaymentsSubscriptions

Test your integration with test clocks

Learn how to move Billing objects through time in test mode.

Overview

Test clocks make it easier to test your Billing integration and make sure it behaves as designed. When you use test clocks you simulate the forward movement of time in test mode, which causes Billing resources, like Subscriptions, to change state and trigger webhook events. This means that, for example, you don’t have to wait a year to see how your integration handles a payment failure for a quarterly or annual renewal.

Here are some other things you can do with test clocks:

  • Test complex simulations such as upgrading or changing plans mid-cycle.
  • Ensure your integration processes Billing lifecycle webhooks correctly.
  • Validate that your app handles trials correctly.
  • Build and test multi-phase subscription schedules.

How to use test clocks

The typical cycle for test clocks consists of creating a simulation, setting up the test case and advancing the time of the simulation, then reviewing how your integration handled those changes.

Test clock lifecycle

Follow these steps to start using test clocks:

  1. Create a test clock
  2. Set up your testing simulation
  3. Advance the clock’s time
  4. Monitor and handle the changes
  5. Update the simulation
  6. Delete the clock

You can advance the clock’s time, monitor changes, and update the simulation as often as you need to test different cases.

Create a clock and set its time

To start a simulation, create a clock and set its frozen time. The temporal starting point for all subscriptions associated with this clock. You can set this to a time in the future or in the past to test different simulations, but you can only move it forward in time after you set it.

To create a test clock in the Dashboard, follow the steps below. Set the Dashboard to Test mode to use test clocks.

  1. Go to the Subscriptions section under the Payments tab.
  2. Click the test clocks link in the banner.
  3. Click New simulation.
  4. In the Create new simulation modal, enter a name for the simulation. You can use this to describe the simulation you’re testing, like Annual renewal or Free trial.
  5. Set the frozen time of the clock. This is the starting point for your simulation. You can set this to a time in the future or in the past, but you can only move it forward in time after you set it.

Set up your simulation

Next, set up the test case for your simulation. You need to create a customer first, then a subscription for them.

To create a customer for your simulation through the Dashboard:

  1. Go to the test clocks page and find your test clock.
  2. Click Add > Add customer.

You can’t choose existing customers during test clock simulations. You can add up to three new customers to each simulation.

You can optionally enter other available properties for the customer, like their name, email, and billing information, but none are required. For some simulations, like testing free trials, you might not want to collect any billing information up front.

Next, you can create up to three subscriptions or subscription schedules for your customer. To create a subscription for the customer through the Dashboard:

  1. Go to the test clocks page and find your test clock.

  2. Click Add > Add subscription. Select or search for your customer from the drop-down menu. You can also add the customer to a subscription through the customer page, by clicking Actions > Create subscription.

  3. Select a recurring product and price in the Pricing section.

  4. For the Subscription schedule, define the start and end date for the subscription and when to start the billing cycle.

  5. Choose a payment collection method:

    • Select Automatically charge a payment method on file if you want to charge your customer when the billing cycle starts.
    • Select Email invoice to the customer to pay manually if you want to invoice your customer in arrears.
  6. Click Start test subscription to start the subscription and billing cycle.

Learn more about all of the options for creating subscriptions in Subscriptions.

Both the customer and subscription objects are associated with the clock object you created in the first step. In the Dashboard, the

icon indicates that an object is associated with a clock.

Advance the simulated time

After you’ve created the test clock and set up your test case, advance the simulated time of the clock. The first time you do this, you’ll advance the time from the initial frozen time you set at the creation of the clock. As you advance time, you can see how your integration works when subscriptions end, renew, or undergo other changes (like upgrading from a free trial to a paid subscription).

You can advance test clocks by any increment, but you can only advance them 2 intervals at a time from their initial frozen time. The length of the interval is based on the shortest subscription interval associated with the test clock, which is determined by the recurring price. For example, if you have a monthly subscription, you can only advance the clock up to 2 months at a time. If the test clock has no subscriptions or subscription schedules, you can advance it up to 2 years from the initial frozen time.

To advance time through the Dashboard:

  1. Go to the test clocks page and find your test clock.

  2. Click Advance time.

  3. Use the calendar modal to select the date you want to advance the clock to.

  4. Click Advance.

When the clock is done advancing, the banner updates and displays the clock’s current time.

Monitor and handle changes

After a successful API request or Dashboard operation, the clock takes a few seconds to advance to the specified time. To know when the clock has changed state, you can use webhooks to listen for event notifications or you can poll the clock. The Dashboard also reflects the changes. For example, you can go to the invoices page to check whether an invoice was created or paid for your subscription.

If you use webhooks, listen to the following event notifications. Before production, make sure your integration correctly handles the other billing-specific event notifications in addition to the ones listed below.

Event
Description
test_helpers.test_clock.advancingThe clock has started to advance but hasn’t reached the specified time.
test_helpers.test_clock.readyThe clock has completed advancing to the specified time.

To poll the state of the clock, retrieve it by ID to examine its status.

curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Update the simulation

You can continue to make changes to your simulation and advance the clock for simulations like:

  • Adding a customer balance.
  • Making a mid-cycle upgrade.
  • Adding one-off invoice items.

After each update, monitor the changes again. Repeat as many times as you need to satisfy your test case.

Delete the clock

Test clocks are automatically deleted 30 days after you create them, but you can delete them when you’re done testing to ensure a clean test environment.

To delete the clock and all of its associated test objects through the Dashboard:

  1. Go to the test clocks page and find your test clock.
  2. Click Finish simulation.
  3. In the confirmation modal, click Finish.

Deleting the clock also deletes the test customers associated with the clock and cancels their subscriptions. Test clocks are only available in test mode, so you can’t delete any production objects when you delete a clock.

Use cases

First, follow these steps to start using test clocks:

  1. Create a test clock
  2. Set up your testing simulation
  3. Advance the clock’s time
  4. Monitor and handle the changes
  5. Update the simulation

Next, you can test certain subscription renewals using test clocks. Let’s say that you’d like to test that a 50 USD/month subscription renews correctly. To simulate this situation using test clocks:

  • Create a new test clock and set its frozen_time to January 1.
  • Add a customer and add a payment method for the customer:

To add a payment method for a customer in the Dashboard:

  1. From the customer account page, click Add > Add card from the Payment methods section.
  2. Enter payment information. In this case, use the test card.
  3. Click Add card in the modal.
  • After adding a payment method for the customer, create a subscription for the new customer set at 50 USD/month. In doing so, the invoice of 50 USD is paid automatically and the subscription is active.

  • Advance the date to February 1 to notice that an invoice of 50 USD is created. By default, the invoice appears in a draft state for one hour.

  • Advance the time by one hour to notice that the invoice is finalized and paid automatically.

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Overview
How to use test clocks
Create a clock and set its time
Set up your simulation
Advance the simulated time
Monitor and handle changes
Update the simulation
Delete the clock
Use cases
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! This is a graphical user interface of the Stripe CLI. You can use it to discover webhook events and manage your Stripe resources. By pressing ctrl + ` you can toggle it open from any page within the Stripe documentation. - View supported commands: - Listen for webhook events: - Trigger webhook events: - Call Stripe APIs: stripe [api resource] [api operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$