> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test with simulated time

> Move a Sandbox customer through renewals, overage and cancellation in minutes instead of months.

Renewals happen once a month, which is too slow to test. In Sandbox, you can put a customer on a [Stripe test clock](https://docs.stripe.com/billing/testing/test-clocks) and move it forward. Stripe renews, invoices and charges as if the time had passed, and Ledger follows: grants, expiry, overage and cancellations all happen at the simulated time.

Simulated time is Sandbox only. Live customers can't be on a test clock.

## Run a simulation

**1. Open the customer**

In the dashboard, switch to **Sandbox**, open **Customers**, and open the customer. Under the page header, **Run a simulation on this customer** has a **Run simulation** button.

You can start before the customer has a paid plan, for example to test a signup at the end of a month, and attach the plan once the clock is running.

**2. Choose a time and run**

Pick a date and time (UTC) in the future and choose **Run simulation**. Ledger creates a test clock for the customer at the current time, then advances it.

You can move up to two billing periods ahead at a time, or two years for a customer with no paid plan. Clocks only move forward.

**3. Watch the renewal**

Advancing takes a few seconds. When it passes a renewal, Ledger stops just after the period ends so it can add overage lines to the draft invoice, then carries on to your time. When both Stripe and Ledger have caught up, the sheet shows the new simulated time.

The customer's page now shows **Simulated time** with the clock's time. Their balance, usage and invoices all use it.

**4. Advance again, or finish**

Choose **Advance time** to keep going. When you're done, choose **Finish simulation**. Stripe deletes the clock, with its Stripe customer and subscription. Ledger keeps the customer and its history; a free plan stays, a paid plan ends.

## Use the API while time is simulated

`check`, `track` and `GET /v1/customers` work as usual and use the customer's simulated time: a grant that has expired on the clock is gone, and usage is recorded at the clock's time. In **Usage**, those requests are marked as simulated.

While the clock is advancing, Stripe refuses changes to the customer, so wait until the dashboard shows the new simulated time before you track usage or change the plan.

## Scenarios worth testing

| Scenario | How |
| - | - |
| A renewal | Attach a paid plan, then advance past `currentPeriodEnd`. The new allowance arrives and the old one expires. |
| Overage on the invoice | On a plan with [overage](https://docs.integrateledger.com/configure-pricing/overage.md), track past the allowance, then advance past the renewal. The invoice carries an overage line. |
| Cancellation | [Stop renewal](https://docs.integrateledger.com/configure-pricing/upgrades-and-downgrades.md#cancel-at-period-end), then advance past the period end. The subscription ends and its credits expire. |
| An upgrade mid-period | Advance two weeks, then [upgrade](https://docs.integrateledger.com/configure-pricing/upgrades-and-downgrades.md). The new plan starts a new period from the simulated time. |

Stripe deletes a test clock 30 days after it's created.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.