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

# The test clock object

> Advance logical time to test recurring billing.

<ResponseExample>
  ```json The test clock object theme={null}
  {
    "id": "tclk_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "test_clock",
    "status": "ready",
    "frozen_time": 1767225600,
    "target_time": null,
    "failure": null
  }
  ```
</ResponseExample>

A Test clock (`tclk_…`) advances logical time for test customers and their recurring billing objects, so you
can exercise trials, renewals, collection retries, scheduled cancellations, and recovery without waiting for
wall-clock time. Test clocks run in test mode only and affect only test objects owned by the selected account.
Live objects never use logical test time. See [Test clocks](/guides/test-clocks) for the full flow.

Objects on a clock, such as a [subscription](/api-reference/subscriptions) or an [invoice](/api-reference/invoices),
carry its ID in `test_clock`. A platform with authorization can use the `Ionic-Account` header to operate a
connected test account. See [Billing for connected accounts](/guides/connect-billing).

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the test clock (`tclk_…`).
</ResponseField>

<ResponseField name="status" type="string">
  `ready` means all billing work through `frozen_time` committed. `advancing` means ordered work remains before `target_time`. `failed` means processing stopped at the last committed checkpoint.
</ResponseField>

<ResponseField name="frozen_time" type="integer">
  Last fully committed logical checkpoint.
</ResponseField>

<ResponseField name="target_time" type="integer | null">
  Requested destination while advancing or failed.
</ResponseField>

<ResponseField name="failure" type="object | null">
  Why an advancement stopped. Present on a test clock only while its `status` is `failed`.
</ResponseField>

See every field in the response of [Retrieve a test clock](/api-reference/test-clocks/retrieve-a-test-clock).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Create a test clock](/api-reference/test-clocks/create-a-test-clock) | Create a ready logical clock. |
| [Retrieve a test clock](/api-reference/test-clocks/retrieve-a-test-clock) | Check the clock's status and last committed time. |
| [Advance a test clock](/api-reference/test-clocks/advance-a-test-clock) | Request forward-only, asynchronous advancement to a later time. |
| [Arm the next subscription collection outcome](/api-reference/test-clocks/arm-the-next-subscription-collection-outcome) | Set a one-shot success or decline for the next automatic collection attempt. |

## Statuses

| Status | Meaning |
| - | - |
| `ready` | All billing work through `frozen_time` has committed. |
| `advancing` | Ordered work remains before `target_time`. |
| `failed` | Processing stopped at the last committed checkpoint. |

## Notes

* Advancement is asynchronous. Poll the clock until `status` is `ready` before asserting the final billing state.
* Advancement is forward-only. Ionic processes every intervening billing action in chronological order.
* A busy clock rejects a different overlapping request. For a `failed` clock, resolve the reported issue and
  request the retained target again with a new idempotency key. Ionic resumes after the last committed checkpoint,
  and a failed clock rejects a different target.
* Arm a decline before advancing to a renewal or retry boundary. After Ionic records the failed attempt and
  schedules the next retry, arm a success and advance to the retry time to verify recovery.
* Only one unconsumed collection scenario can exist for a subscription. With none armed, automatic collection
  follows the normal test-mode path.
* Ionic remains authoritative for subscription state, invoices, collection schedules, and events. Use the resulting
  objects and events to verify your own access control, notifications, and reporting.


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