payinOPERATIONS MANUAL

Latest articles

Stripe test clocks: advance in bounded steps, not toward a live-payment guarantee

Build disposable Billing simulations, respect frozen-time advancement limits, wait for ready, diagnose missing observations and preserve evidence before cleanup.

Published; sources checked:

Stripe Billing sandbox test-clock lifecycle using Customers v1: advancement, asynchronous readiness, observation boundaries and cleanup. Excludes live trial policies, anchor recipes, pending upgrades, Accounts v2, general rate-limit tuning and invoice export.

Test the passage of time, not a different billing contract

A public developer question asks how to test a subscription schedule today when billing intervals are expressed in days, weeks, months or years; changing trial parameters produced confusing invoices instead.[5] That is a reason to simulate time rather than rewrite the commercial configuration merely to make a test finish sooner. The community thread establishes demand, not current API rules.

Stripe test clocks let a simulation start at a frozen time and then move forward; after creation, the clock cannot move backward.[1] This guide concerns the simulation lifecycle, observation gates and cleanup. It does not prescribe trial-end policies, billing anchors or payment-gated upgrades. The procedure is editorial guidance based on documentation, not an executed Stripe test or a PayIn feature claim.

Create an isolated, disposable scenario

For new integrations, Stripe recommends a general sandbox rather than the test mode sandbox because general sandboxes isolate settings and data from live mode. The test mode sandbox shares some settings with live mode, so changing Dashboard settings there can affect production.[4] Confirm the credentials used by your application: selecting a sandbox in the Dashboard does not change the API keys in your code.[4]

  1. Write the assertion first: which subscription or invoice state should be observed at which simulated boundary? Record the account environment, API version, recurring interval and expected application-side result.
  2. Create the clock through POST /v1/test_helpers/test_clocks, supplying the initial frozen_time timestamp and a descriptive name; retain its returned identifier.[1]
  3. For the Customers v1 path covered here, create a disposable customer with test_clock set to that identifier, then create the subscription for that customer. The subscription inherits the clock association through its customer.[1]
  4. Use the documented test payment method for the intended scenario, or deliberately leave it absent when absence is what you are testing.[1] Keep unrelated tests on separate fixtures so cleanup ownership is clear.

The current limits are three customers per simulation, three subscriptions including scheduled subscriptions per customer, and ten quotes not attached to customers.[1] This is a small lifecycle fixture, not a population-scale test.

Do not turn an old community answer into a blanket ban on existing customers. Current documentation allows creating a clock for an existing customer subject to object limits, an initial time that is not in the past, and no configured Automations; the customer cannot subsequently be removed from that clock.[1] Prefer a new disposable customer rather than removing account automation merely to reuse a fixture.

Advance in supported increments, then wait

The advance endpoint requires a target later than the current frozen_time. A single advance cannot exceed two intervals of the shortest subscription attached to the clock.[2] A monthly subscription therefore permits at most two months per advance; the guide says that without subscriptions or subscription schedules, the limit is two years from the initial frozen time.[1] Do not interpret that empty-clock allowance as unlimited repeated two-year jumps.

For a hypothetical clock containing both monthly and annual subscriptions, plan around the monthly interval rather than jumping directly to the annual anniversary. This is an illustration of the shortest-subscription rule, not a reported test result.[2] Our recommended harness splits a longer journey into checkpoints, preserving observations after each one.

  1. Read the clock and choose the next supported target, taking its current fixtures into account.
  2. Submit POST /v1/test_helpers/test_clocks/{id}/advance with the target in frozen_time. A successful request returns a clock in advancing, not proof that processing has finished.[2]
  3. Wait for test_helpers.test_clock.ready, or retrieve the clock by identifier and inspect status; Stripe also emits test_helpers.test_clock.advancing.[1]
  4. Only after ready, inspect the resulting subscription, invoice and your application’s own processing before making the next change. The documented meaning of ready is that clock objects have advanced to the frozen time, not that your external work queue has completed.[3]

Recommended decision branches: while advancing, wait with a bounded polling policy; on a local timeout, preserve identifiers and investigate rather than declaring failure or success. On internal_failure, stop advancing that clock: Stripe states that future advance requests will fail.[3] Recreate a disposable scenario after preserving diagnostic evidence. No universal polling deadline is asserted here.

Diagnose missing observations before changing the scenario

An unfiltered list can mislead you. Stripe says list methods omit test-clock-generated objects unless the appropriate query clause is supplied; required parameters vary by resource.[1] Retrieve known identifiers or use the relevant customer, subscription or clock filter rather than concluding that an invoice never existed. This is a fixture-visibility check, not a general invoice-export recipe.

Repeated subscription updates at the same frozen time can also trigger rate limits because requests count toward that simulated time. Stripe recommends advancing the clock by a few minutes before further subscription requests.[1] If those minutes would cross the boundary under examination, preserve the failed case and redesign the fixture instead of silently changing what the test claims to cover.

Keep simulated evidence separate from live outcomes

Bank debits are a specific trap: advancing a clock does not currently support collecting those payments, including us_bank_account; collection occurs after advancement. Stripe’s failure example can remain active immediately after advancement because collection was not attempted during it.[1] Observe the later invoice and subscription events rather than treating ready or active as proof of successful bank collection.

More fundamentally, sandboxes create simulated objects without moving real money, and banks and card networks do not process sandbox payments.[4] A passing simulation can support a claim about the tested configuration and your observed handlers; it cannot prove a future live authorization, settlement or customer-bank outcome. Keep production readiness, supported payment methods and account eligibility as separate checks, without experimenting on real customer charges merely to strengthen a test report.

Capture evidence before destructive cleanup

Save clock and fixture identifiers, initial and target timestamps, observed states, relevant events and assertion results before deletion. Mark each result as observed, failed, timed out or outside simulation support. These are recommended reporting categories, not results obtained for this article.

Stripe documents automatic simulation deletion 30 days after creation and exposes deletes_after as the clock’s scheduled auto-deletion timestamp.[1][3] Manual deletion through DELETE /v1/test_helpers/test_clocks/{id} deletes associated test customers and cancels their subscriptions.[1] Do not depend on a shared fixture surviving cleanup, and do not confuse simulated time advancement with a promise about evidence retention.

Sources and dates

Retrieved and checked 2026-09-23. Publication and update dates were not stated in the retrieved source texts. Official documentation supports behavior; the public question supports qualitative demand only. Regional availability is not established by these sources: verify the actual account, product and payment method. Documentation research only; no authenticated or live-payment testing was performed.

More guides