API and advanced usage

Learn advanced strategies for using test clocks in the Dashboard and API.

You can create a test clock separately from a subscription for running advanced simulations. In this scenario you create the test clock first and then add different test cases to it.

Not ready for a full integration? See our guide for running simulations on subscriptions.

How to set a test clock to simulate subscription time elpasing.

Test clock lifecycle

Follow these steps to start using test clocks:

Create a test clock
Set up your testing simulation
Advance the clock’s time
Monitor and handle the changes
Update the simulation
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.

With the API, you specify the time in the frozen_time field as a Unix Epoch timestamp. This example sets the frozen time of the Annual renewal clock to November 1, 2021 7:00:00 AM GMT (1635750000 in Unix Epoch format).

Note the id of the created test clock (for example, clock_1JGWQvIyEfDZOm8cxyhPwsoc). You’ll use it to create a customer and advance the time.

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.

Use the following code sample to create a Customer and associate it with the clock. Remember to set a default payment method for the customer (unless you want to test a free trial or similar simulation). You can use a test card for this.

By default, the List all customers endpoint doesn’t include customers with test clocks. You can use the test_clock parameter to get a list of all customers that are attached to the specified test clock.

Use the customer you created to create a new Subscription. The subscription is associated with the clock through the customer, so you don’t have to pass the clock ID to create the subscription.

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 two 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 two months at a time. If the test clock has no subscriptions or subscription schedules, you can advance it up to two years from the initial frozen time.

To advance time through the API, update the frozen_time parameter. For example, to advance it to November 1, 2022 to test an annual renewal:

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.advancing`	The clock has started to advance but hasn’t reached the specified time.
`test_helpers.test_clock.ready`	The clock has completed advancing to the specified time.

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

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 API:

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

Use cases

Test subscription renewals

First, follow these steps to start using test clocks:

Create a test clock
Set up your testing simulation
Advance the clock’s time
Monitor and handle the changes
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 set a default payment method for the customer:

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 see 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 see that the invoice is finalized and paid automatically.

Test mid-cycle upgrades with prorations

First, follow these steps to start using test clocks:

Create a test clock
Set up your testing simulation
Advance the clock’s time
Monitor and handle the changes
Update the simulation

Next, you can test prorations for customers who upgrade their plans in the middle of a billing cycle. Let’s say that you have two products. One product is 50 USD/month (‘basic plan’) and the other is 100 USD/month (‘premium plan’). In this case, you may want to test prorations for a customer who upgrades their ‘basic plan’ to the ‘premium plan’ in the middle of a billing cycle. To simulate this situation using test clocks:

Create a new test clock and set its frozen_time to January 1.
Create a customer and add their payment method. In this case, use the test card.
Create a subscription for the ‘basic plan’ at 50 USD/month. After this is done, you’ll see that the 50 USD/month invoice is created, finalized, and automatically paid.
Advance the date by two weeks. In this case, we’ll set the date to January 16.
Upgrade the subscription to a ‘premium plan’ at 100 USD/month:

You can use pending updates with the update subscription, create subscription item, and update subscription item calls. When you make the update, set payment_behavior=pending_if_incomplete. The example below adds a new price to a subscription. Because proration_behavior=always_invoice, an invoice is created and payment is attempted when the update is made.

After upgrading the subscription, the customer.subscription.updated webhook event is created.
Pending invoice items are also created for the prorations. You’ll see a negative proration of -25 USD for the unused time with the ‘basic plan’ and a positive proration of 50 USD for using the ‘premium plan’ for half of the remaining month. At this point, no invoice has been generated.
Advance the date by two weeks. In this case, we’ll set the date to February 1. You’ll see that the subscription has cycled. An invoice has been generated in a draft state and has incorporated the pending invoice items, including a negative proration, a positive proration, and the total payment for the month of February, resulting in 125 USD. By default, the invoice appears in a draft state for around one hour.
To finalize the invoice, advance the time by one hour.

Test trials

First, follow these steps to start using test clocks:

Next, you can start testing trials with test clocks. Let’s say that you want customers to try your product for free with a seven-day trial before they start paying and want to collect payment information up front. To simulate this situation using test clocks, follow these steps:

Create a new test clock and set its frozen_time to January 1.
Add a customer and include their payment method. In this case, use a test card.
Create a subscription and add a seven-day free trial period:

You can start a customer’s subscription with a free trial period by providing a trial_period_days=7 argument when creating the subscription:

After creating a subscription with a seven-day free trial period, a subscription is created in a trialing state. An invoice of $0.00 is generated due to the free trial.
Advance the date to January 5 to see the customer.subscription.trial_will_end event notification. Stripe sends the notification three days before the trial ends. You can use this webhook event to inform your customers that the trial ends soon.
Advance the date to January 8 to see that the subscription is now paid and an invoice for 50 USD is created.
Advance the date by one cycle (for example, to February 8 for a monthly subscription) to see the subscription renew successfully.

Limitations

For efficient advancement of test clocks, Stripe limits the complexity of each simulation to:

Three customers
Three subscriptions, including scheduled subscriptions, per customer
Ten quotes that aren’t attached to customers

Test clock objects omitted in list all results

Stripe list APIs (such as List invoices) omit results generated by test clocks for list all requests. To see results generated by test clocks in these cases, you must request results within a specific parent, such as test_clock, customer, or subscription.

For example, GET /v1/invoices won’t return test clock generated invoices, but GET /v1/invoices/{customer_id} returns all invoices for that customer, including those that are test clock generated.

Similarly, you can specify a test clock ID in this example to get all invoices related to that test clock, or you can specify a subscription ID to return all invoices billed for that subscription, including test clock generated invoices.

Rate limit errors

If you make multiple updates to a subscription that has a test clock, Stripe might return a rate limit error. Since the subscription is frozen to the time of the test clock, all API requests count toward that time, which can trigger the rate limit.

To avoid this, advance the simulated time of the clock by a few minutes before making additional API requests on the subscription.

Caveats with payment processing

Test clock advancement currently doesn’t support collecting payments through bank debits (for example, us_bank_account payment method types). Stripe collects payments after the test clock advances. To test payment failures:

Choose the Cancel subscription after all payment retries fail setting.
Attach a us_bank_account payment method type to a customer that fails payments.
Create a subscription under the customer.
Advance the test clock to cycle and collect payment on a subscription.

After the Test Clock advances, the subscription remains in the active state. This indicates that the payment collection hasn’t be attempted during test clock advancement, and the subscription has yet to enter the canceled state due to payment_failed.

Listen to the invoice.payment_failed event to monitor the delayed subscription state and invoice payment. The customer.subscription.deleted event indicates that the subscription state is set to canceled.