Stripe Test Clock

The two-interval rule, and why a renewal needs two advances

You cannot jump a clock to any date you like. Stripe lets you advance it “in intervals of up to two,” where the interval is the shortest service period on the subscription, set by its recurring price. A monthly subscription can move up to two months per advance. An annual one can move up to two years. A clock with no subscriptions on it can move up to two years from its initial frozen time.

The other timing detail is the one that trips people up. A renewal does not produce a paid invoice the instant the period rolls over. Stripe’s renewal walkthrough starts a 50 USD per month subscription on January 1, advances to February 1, and finds a new 50 USD invoice in draft. By default, Stripe says, a subscription invoice stays in draft for one hour. Advance the clock one more hour, and the invoice is finalized and paid.

So a simulation that stops exactly on the renewal date shows a draft invoice and no payment. That is not a failure. It is the hour Stripe leaves for adding invoice items before finalizing, and any check you run on the books should start after it.

A worked example: a mid-cycle upgrade

Stripe’s proration walkthrough is a useful one to run before the first real upgrade reaches your books, because the numbers are easy to check by hand.

On January 1 a customer starts a basic plan at 50 USD per month, and the first invoice is created, finalized and paid. The clock is advanced to January 16, and the customer upgrades to a premium plan at 100 USD per month. In Stripe’s walkthrough the upgrade creates two pending invoice items and no invoice yet: a credit proration of 25 USD for the unused half month of basic, and a charge of 50 USD for half a month of premium.

Advance to February 1 and the subscription cycles. The draft invoice holds the negative proration, the positive proration and February’s full 100 USD, for a total of 125 USD. That is 100 minus 25 plus 50. One more hour finalizes it.

The lesson for bookkeeping is that the upgrade itself produced no invoice and no payment on January 16. The revenue effect of a mid-month change can arrive on the next renewal invoice, netted into it, and your books will only see it when that invoice is finalized.

What a bookkeeper can rehearse with one

A test clock is a developer tool by origin, but most of what it shows is accounting. Four rehearsals are worth running before the real thing happens.

A free trial. Stripe’s trial walkthrough uses a 7-day trial on a clock frozen at January 1. The subscription starts in trialing status and generates a zero-value invoice for the trial. On January 5, the customer.subscription.trial_will_end event fires, three days before the end by default. On January 8 the trial ends, and with a successful payment the subscription becomes active and its first paid invoice appears. Watching that sequence once shows you which of those invoices your books should care about, and how a $0 invoice is handled before one arrives for real.

An annual renewal that fails. Attach a card that declines, move the clock past the renewal, and see what Stripe does with the unpaid invoice under your retry settings.

A mid-cycle plan change, as in the example above, to see where prorations land.

A customer balance or a one-off invoice item, both of which Stripe lists as things a simulation can test, to see how they change the next invoice.

Limits that change what you can test

A few limits decide whether a test clock can show you what you want.

A simulation you build from the Simulations page takes new customers only. Stripe’s note is that “you can’t choose existing customers during simulations,” and each simulation takes up to three. For an existing sandbox customer, the Dashboard route is Run simulation on one of their subscriptions, and the API lets you create a test clock for an existing customer, with conditions: the customer must be under the subscription and quote limits, the initial frozen time cannot be in the past, and the account must have no Billing Automations configured. Once attached, the customer cannot be removed from the clock, and deleting the clock deletes the customer.

Objects on a clock also hide from ordinary lists. Stripe says API list methods such as List Invoices do not return objects generated by test clocks unless you add a query clause, for example a customer, subscription or test clock ID. A report built on a plain invoice list will look as if the simulation produced nothing.

Bank debits are the biggest gap. Advancing a clock does not collect us_bank_account payments. Stripe collects them after the clock has advanced, so a subscription paid by bank debit can remain active right after the advance, with no payment attempt yet. To see the failure play out, Stripe’s advice is to listen for invoice.payment_failed and customer.subscription.deleted rather than reading the status straight after the advance.

Finally, the sandbox itself has limits. Stripe says payments in a sandbox are not processed by card networks or payment providers, and IC+ pricing cannot be tested there, so fee amounts in a simulation are not a forecast of the fees on your real statement.