> ## 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.

# Retrieve a test clock

> Retrieves an owned test clock. A clock owned by another account is
returned as not found. Poll this operation after requesting an advance.




## OpenAPI

````yaml /openapi/test-clocks.yaml get /test_clocks/{id}
openapi: 3.0.3
info:
  title: Ionic Test Clocks API
  version: '2026-08-30'
  description: |
    Advance logical time for test customers and their recurring billing
    objects. Test clocks let you exercise trials, renewals, collection retries,
    scheduled cancellations, and recovery without waiting for wall-clock time.

    Ionic remains authoritative for subscription state, invoices, collection
    schedules, and public events. Platforms use the resulting objects and
    events to verify their own access control, notifications, reporting, and
    account state. A successful Ionic billing transition can still produce a
    broken customer experience if an integration applies it to the wrong
    account, applies it twice, or reacts at the wrong lifecycle stage.

    Test clocks are available only with test-mode credentials and can affect
    only test objects owned by the selected Ionic account. An authorized
    platform may use the `Ionic-Account` header to operate a connected test
    account. Live objects never use logical test time.

    Advancement is asynchronous. Poll the returned clock until `status` is
    `ready` before asserting the final billing state. All timestamps are Unix
    epoch seconds.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: Ionic API base URL.
security:
  - secretKey: []
tags:
  - name: Test clocks
    description: Accelerate test-mode recurring billing scenarios.
paths:
  /test_clocks/{id}:
    get:
      tags:
        - Test clocks
      summary: Retrieve a test clock
      description: |
        Retrieves an owned test clock. A clock owned by another account is
        returned as not found. Poll this operation after requesting an advance.
      operationId: test_clocks_retrieve
      parameters:
        - $ref: '#/components/parameters/TestClockId'
        - $ref: '#/components/parameters/IonicAccount'
      responses:
        '200':
          description: The current test clock state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestClock'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TestModeRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - secretKey:
            - subscriptions:read
components:
  parameters:
    TestClockId:
      name: id
      in: path
      required: true
      description: Test clock ID.
      schema:
        type: string
        pattern: ^tclk_[0-9A-Za-z]{14}$
      example: tclk_R7pA3nB9qK2mX5
    IonicAccount:
      name: Ionic-Account
      in: header
      required: false
      description: |
        Connected Ionic account to operate when using an authorized platform
        credential. Omit when using the account's own credential.
      schema:
        type: string
  schemas:
    TestClock:
      type: object
      additionalProperties: false
      required:
        - id
        - object
        - status
        - frozen_time
        - target_time
        - failure
        - created_at
        - updated_at
      properties:
        id:
          type: string
          pattern: ^tclk_[0-9A-Za-z]{14}$
        object:
          type: string
          enum:
            - test_clock
        status:
          type: string
          enum:
            - ready
            - advancing
            - failed
          description: |
            `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.
        frozen_time:
          type: integer
          format: int64
          description: Last fully committed logical checkpoint.
        target_time:
          type: integer
          format: int64
          nullable: true
          description: Requested destination while advancing or failed.
        failure:
          allOf:
            - $ref: '#/components/schemas/TestClockFailure'
          nullable: true
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
    TestClockFailure:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable Ionic error code.
        message:
          type: string
          description: Merchant-safe explanation without internal details.
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: Malformed identifier, body, timestamp, or idempotency key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TestModeRequired:
      description: >-
        Subscription testing resources cannot be used with a live-mode
        credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The test clock does not exist in the selected account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Concurrent test-clock advancement limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Ionic could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: Ionic secret key

````