A billing integration can look perfect until a trial ends, a renewal invoice fails, or a scheduled price change takes effect. Stripe test clocks let you test those dates in minutes rather than waiting days, months, or a full annual cycle.
For SaaS teams, the goal is not merely to move time forward. You need proof that Stripe changed the right objects, your webhooks ran, and your application gave the customer the correct access. Start with a small, disposable billing fixture and make every assertion traceable.
Why Time-Based Billing Bugs Need a Controlled Clock
Many billing failures sit at date boundaries. A subscription renews at midnight, an invoice payment fails, and an entitlement job runs twice. Those problems are expensive because they affect access, revenue reporting, and support tickets at the same time.
Stripe test clocks provide deterministic control over Billing objects in test mode. A clock starts at a frozen Unix timestamp. You advance it to a future timestamp, then Stripe processes the billing activity that should occur during that period. Stripe’s Billing simulations guide covers the feature’s supported testing flow.
A clock can test Stripe-managed events such as subscription transitions and invoices. It cannot change your own database records, product permissions, or email platform by itself. Your webhook handling must do that work.
Set Up Stripe Test Clocks With Disposable Fixtures
These examples assume Stripe test mode, a pinned account API version, and a webhook endpoint that can receive signed test events. Never use live-mode customers or production credentials in a billing simulation.
Test clock actions use the /v1/test_helpers/test_clocks API path. Stripe updates API fields and supported behavior over time, so check its advanced API guidance for test clocks before changing a long-lived test suite.
Keep each scenario isolated
Create a fresh customer, subscription, and clock for each scenario. For example, use one fixture for a seven-day trial conversion and another for a declined monthly renewal. Shared test customers make it hard to tell which invoice, webhook, or app record belongs to a given run.
Associate the customer with the test clock before creating time-sensitive Billing objects. Add metadata such as test_run=trial-conversion-2026-08-21 to the customer and subscription. That metadata makes Stripe Dashboard searches and webhook logs much easier to audit.
A customer attached to a clock is not a reusable general fixture. Stripe does not let you remove that attachment later, so treat the data as temporary.
Create a Subscription Fixture at a Known Date
Pick a frozen date that makes billing periods easy to inspect. January 1, 2026 is Unix timestamp 1767225600, which gives a clean monthly or annual boundary. Use a date that matches how your business defines its billing timezone.
The minimum API sequence
A basic test needs a clock, a clock-linked customer, a recurring Price, and a subscription.
| Goal | API request | Key parameters |
|---|---|---|
| Create the clock | POST /v1/test_helpers/test_clocks | frozen_time=1767225600, name=monthly-renewal |
| Create the customer | POST /v1/customers | test_clock=clock_..., email=billing-test@example.com |
| Create the subscription | POST /v1/subscriptions | customer=cus_..., items[0][price]=price_... |
| Start a trial | POST /v1/subscriptions | Add trial_end=<future Unix timestamp> |
| Advance simulated time | POST /v1/test_helpers/test_clocks/clock_.../advance | frozen_time=<target Unix timestamp> |
| Confirm completion | GET /v1/test_helpers/test_clocks/clock_... | Check for status=ready |
Create Products and Prices once if their amount and billing interval stay stable across tests. Then create a new customer and subscription for every run. Save the returned clock, customer, subscription, and initial invoice IDs in your test output.
For a subscription trial, set an explicit trial_end based on the clock’s frozen time. That makes the expected boundary visible in your test rather than hiding it behind a relative duration. If your application creates subscriptions through Checkout, test that integration too, but keep at least one direct API fixture for fast debugging.
Advance Time in Safe, Meaningful Steps
Calling POST /v1/test_helpers/test_clocks/:id/advance starts an asynchronous advance. The target frozen_time must be later than the clock’s current time. Stripe changes the clock status to advancing while it processes Billing activity, then to ready when the simulation has finished.
Stripe limits how far you can advance a clock. When subscriptions exist, the target cannot exceed two billing intervals beyond the shortest subscription interval. If there are no subscriptions, the maximum advance is two years.
Wait for ready before asserting results
Poll the clock retrieval endpoint until status=ready. Then allow your webhook processor to finish its work before checking your application’s database. A time advance request returning successfully only means Stripe accepted the request.
Stripe can emit test clock lifecycle events, including test_helpers.test_clock.advancing, test_helpers.test_clock.ready, and test_helpers.test_clock.internal_failure. Store these alongside the subscription ID for failed test runs.
A clock reaching
readyconfirms Stripe completed the simulation. It does not prove your application recorded the right entitlement, payment state, or cancellation.
Advance one business milestone at a time. For a trial, move first to the reminder window, then to the trial end. For a retry schedule, advance to each configured retry point. Test clocks only move forward, so create a new fixture when you need to test a different branch.
SaaS Billing Scenarios to Run With Stripe Test Clocks
A useful test names the customer state you expect before the first API call. That keeps the test focused on business behavior rather than a vague list of Stripe events.
Trial conversion and customer access
Create a subscription with a seven-day trial. Advance through the trial reminder window, then move past trial_end. For eligible trials, handle customer.subscription.trial_will_end and verify that your reminder workflow does not send duplicate messages.
After the trial ends, retrieve the Subscription and latest Invoice. Confirm the subscription status, invoice collection outcome, and your application’s access record. A paying customer should receive the paid plan’s permissions only after the event your product treats as successful payment.
Monthly renewal and failed collection
For a successful renewal, use a monthly recurring Price and advance across the billing boundary. Depending on your collection settings, expect invoice lifecycle events such as invoice.created, invoice.finalized, and invoice.paid, plus a subscription update.
For a failure path, attach a Stripe test payment method that deliberately declines before advancing the clock. Verify invoice.payment_failed, the invoice status, the subscription status your collection configuration produces, and the exact dunning action in your system. Test retries individually if your account has a retry policy.
Price changes and period-end cancellations
Update a subscription item during its current billing period and choose the proration behavior your product uses. Inspect invoice line items, credits, and the resulting amount due. This catches common errors where an app displays the new plan price but records the wrong renewal amount.
For cancellation, set cancel_at_period_end=true, then advance through the current period end. Confirm that Stripe emits the expected subscription deletion event, your app removes paid access at the correct time, and no additional renewal invoice appears.
Verify Stripe State and Your Own Side Effects
Webhook delivery is part of billing behavior, not an afterthought. Stripe can retry deliveries, and an application can process the same logical change more than once if it lacks idempotency controls.
Record every event before processing it
Verify the Stripe-Signature header, save the raw event ID, and use event.id as an idempotency key. Acknowledge the webhook quickly, then let a worker apply account changes. Record the Stripe object ID, event type, received timestamp, and processing outcome.
For a renewal fixture, tie invoice.paid, customer.subscription.updated, and any related payment_intent.succeeded event to the same customer and subscription. Event ordering can vary, so build handlers that retrieve the current Stripe object when order matters.
Compare both systems after each milestone
After the clock reports ready, retrieve the Subscription, Invoice, and PaymentIntent where applicable. Check values that matter to your product, including the subscription status, billing period, invoice amount, payment result, and cancellation date.
Then query your own records. Validate the workspace plan, seat limit, feature access, next renewal date, payment status, and outbound email history. A passing test needs matching outcomes in Stripe and your app.
For a quick manual review, Stripe also documents how to run a subscription simulation in the Dashboard. Use it to inspect a fixture, but keep automated webhook assertions in your release checks.
Keep Fixtures Small and Clean Them Up
Large fixtures hide the cause of failures. One customer, one subscription, one business condition, and a clear expected result are enough for most billing tests. Use separate clocks for annual renewals, multi-phase subscription schedules, and cancellation tests.
Delete data only after you capture evidence
Keep failed fixtures long enough to inspect webhook logs and Stripe object timelines. Once the run is complete, delete the clock and record the IDs in your test report. Stripe’s advanced test clock behavior deletes the associated customer and subscriptions when you delete the clock, so never attach a customer you intend to keep.
Also watch for test_helpers.test_clock.internal_failure. Preserve the fixture, event payloads, and request IDs if that event appears. Those records give Stripe support and your engineering team something concrete to investigate.
Final Checks Before Shipping Billing Changes
Stripe test clocks make time-based billing repeatable, but the real pass condition is matching state in Stripe and your application. A paid invoice without access, or canceled access with an active subscription, is still a billing defect.
Use this implementation checklist before releasing a change:
- Create a disposable test-mode customer tied to a new clock.
- Save all Stripe object IDs and expected state changes.
- Advance to one billing milestone at a time and wait for
ready. - Verify webhook idempotency, Stripe objects, and app entitlements together.
- Delete completed fixtures after recording the test result.
Create a seven-day trial fixture next, then prove that your app handles the reminder, conversion, payment outcome, and customer access without manual intervention.
