The test clock object

{
  "id": "tclk_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "test_clock",
  "status": "ready",
  "frozen_time": 1767225600,
  "target_time": null,
  "failure": null
}

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 for the full flow. Objects on a clock, such as a subscription or an invoice, 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.

Attributes

string

Unique identifier for the test clock (tclk_…).

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.

integer

Last fully committed logical checkpoint.

integer | null

Requested destination while advancing or failed.

object | null

Why an advancement stopped. Present on a test clock only while its status is failed.

See every field in the response of Retrieve a test clock.

Endpoints

Endpoint	Use it for
Create a test clock	Create a ready logical clock.
Retrieve a test clock	Check the clock’s status and last committed time.
Advance a test clock	Request forward-only, asynchronous advancement to a later time.
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.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

The test clock object

Attributes

Endpoints

Statuses

Notes

​Attributes

​Endpoints

​Statuses

​Notes

Attributes

Endpoints

Statuses

Notes