Test subscription renewals with Stripe test clocks
Short answer: Stripe test clocks let you freeze time in a sandbox, attach test customers and subscriptions to that frozen moment, then jump forward days, months or a year to see exactly what happens at trial end, renewal or a failed payment. Instead of waiting a month to find out whether your app grants access after a renewal, you advance the clock, watch the invoices and webhook events arrive, and check your own database. Use them for every billing scenario your business actually sells before you take live payments.
The problem test clocks solve
Subscription bugs hide in time. A sign-up flow is easy to test because it happens right now. The hard parts happen later: a free trial ends, an annual plan renews, a card is declined at renewal, a customer upgrades halfway through a month. Stripe's testing guide describes test clocks as a way to advance simulated time in a sandbox and see how subscriptions and invoices change, for example testing a payment failure at an annual renewal "without waiting a year".
Typical things owners discover only after launch, and that a clock run catches earlier:
- the app removes access the moment a trial ends instead of after the first payment succeeds
- the "your trial ends soon" email never sends because nothing listens for the event
- a failed renewal leaves the customer with full access forever
- an upgrade mid-month charges the wrong amount on the next invoice
Running a simulation from the Dashboard
You don't need code for a first pass. In a sandbox, open a subscription and click Run simulation in the banner. Set the date and time you want and click Advance time. When it finishes, the banner shows the current simulated time and you can review the subscription, its invoices and its events.
Stripe documents a few limits worth knowing before you plan tests:
- You can advance by up to two subscription intervals at a time from the frozen time, so a monthly plan moves at most two months per step.
- A simulation can hold up to three customers, three subscriptions per customer (scheduled ones included) and ten quotes not attached to customers.
- The Dashboard may disable Run simulation for a customer with more than three subscriptions or a complex history.
- For an existing customer, the starting time can't be in the past, and the account can't have Automations configured.
Simulations live under Subscriptions, then Simulations. Clicking Finish simulation deletes the clock and its test customers and subscriptions. They are removed automatically after 30 days anyway, and none of this touches live mode.
Using the API for repeatable tests
For tests you want to run again after every billing change, create clocks through the API. The pattern is:
- Create a test clock with a starting time (Stripe calls it the frozen time).
- Create a customer attached to that clock and give them a test payment method.
- Create the subscription with the trial, price and options you sell.
- Advance the clock to the moment you care about.
- Wait until the clock has finished advancing, then check results.
Advancing takes a few seconds. Stripe sends test_helpers.test_clock.advancing when the move starts and test_helpers.test_clock.ready when it is done, or you can poll the clock by ID and read its status. Don't assert anything until the clock is ready.
Stripe also warns that many updates to a subscription on a test clock can trigger a rate limit error, because all requests count against the same frozen moment. Advance time between batches of changes.
Four scenarios worth running
Trial ending with a good card. Stripe's own walkthrough sets the clock to January 1, adds a customer with the 4242 4242 4242 4242 test card and a seven-day trial, then advances. At January 5 you should receive customer.subscription.trial_will_end, which defaults to three days before the trial ends. At January 8 the trial ends; advance a little further for the invoice to finalize and the payment to be collected. The subscription should become active and the invoice paid. Advance one more cycle to see a normal renewal.
Trial ending with a declining card. Stripe suggests setting 4000 0000 0000 0341 as the default payment method, using a short trial, and letting the trial end. The payment attempt fails and your integration receives invoice.payment_failed. Check that your app follows your retry and notification rules rather than silently keeping or cutting access.
Annual renewal. Create a yearly subscription and advance in steps to the renewal date. This is where expired cards and price changes catch businesses out.
Mid-cycle upgrade. Advance a few days, change the plan, then advance to the next invoice and check the amount matches what your pricing page promises.
For payments that need authentication, Stripe's 4000 0027 6000 3184 test card triggers 3D Secure, so you can check both a successful and a failed authentication.
What to check in your own app
Stripe's side behaving correctly is only half the test. After each advance, look at your application:
- Did your webhook endpoint receive the customer.subscription and invoice events, and verify their signatures?
- Does your database show the right plan, status and access level?
- Did the customer-facing emails your app sends go out at the right time?
- Does your app cope if events arrive in a different order? Stripe's testing page says not to rely on a particular order.
Write the expected result for each scenario down before you run it. A test with no expected result usually ends with someone saying "looks fine".
An illustrative example
A gym in Denver sells a monthly membership with a 14-day trial through its booking app. Before launch, the developer runs three clocks: a good card, a declining card and a member who upgrades to the annual plan in week two. The declining-card run shows that the app keeps door-access codes active after invoice.payment_failed, because the handler only listened for cancellations. They fix the handler and rerun the same clock until access is suspended as intended.
FAQ
Do test clocks work in live mode?
No. They only exist in sandboxes, and finishing a simulation can't affect production objects.
Can I rewind a test clock?
You move clocks forward. To repeat a scenario, finish the simulation and create a fresh one.
Why didn't my trial-ending event arrive?
Check that your notification window matches the date you advanced to, and that your endpoint listens for that event in the sandbox.
Should automated tests use the same sandbox as manual testing?
Stripe recommends separate sandboxes for local development and CI so automated runs don't disturb your other test data.
If you want your subscription billing tested against the renewals and failures your customers will really hit, tell us how your plans and trials work.