# Advance a test clock > The test_clocks.advance operation: POST /api/v1/test_clocks/{id}/advance in the REST API and the test_clocks_advance tool in the MCP server. Moves a test clock forward to `frozenTime`. The clock's `status` becomes `advancing` at once; in the background, every step due on its customers' subscriptions up to that time runs in time order, each at its own time: trial notices and trial ends, `invoice.upcoming`, renewal drafts an hour before each period end, renewals (invoices finalized, charged or sent), scheduled changes and price migrations, cancellations at the period end, pause resumptions, the 23-hour expiry of unpaid subscriptions, and collection: dunning retries and their final action, send_invoice reminders and overdue, and card-expiry reminders. Then the clock is `ready` at the new time (`test_clock.ready`). Read the clock with `test_clocks.get` until it is `ready`. Off-session charges complete through the processor afterwards, as they do in real time, and their outcome is recorded at the clock's time. If a step fails, the clock stops at the last step that ran with `status: internal_failure` and `advance.error`; fix the cause and advance again. An advance moves the clock at most 732 days; advance several times to go further. Emits `test_clock.advancing`. ## At a glance - **REST:** `POST /api/v1/test_clocks/{id}/advance` - **MCP tool:** `test_clocks_advance` - **Operation ID:** `test_clocks.advance` - **Scope:** Brand - **Permission:** `subscriptions:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test mode only - **Authentication:** API key with the `subscriptions:write` scope - **Since:** M5 ## Request ### Path parameters | Field | Type | Description | | ----- | ---------- | ----------- | | `id` | `clk_…` ID | | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------ | --------- | -------- | ------------------------------------------------------------------------------ | | `frozenTime` | date-time | Yes | The time to move the clock to: after its current time, at most 732 days ahead. | ## Response `202 Accepted` with a JSON object: | Field | Type | Description | | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `clk_…` ID | | | `object` | `"test_clock"` | | | `livemode` | `false` | | | `brandId` | `brd_…` ID | | | `name` | string | | | `frozenTime` | date-time | The clock's time: its customers' subscriptions bill as if it were now. | | `status` | one of `ready`, `advancing`, `internal_failure` | `ready`, `advancing` (an advance runs: wait for `ready`) or `internal_failure` (the last advance stopped on an error, see `advance.error`; advance again). | | `advance` | object or null | The latest advance. | | `version` | integer | | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### Advance a month ```http POST /api/v1/test_clocks/clk_01jacq4m3xf0v8w9zq2y7k5n6h/advance Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "frozenTime": "2026-11-21T09:00:00.000Z" } ``` Response (`202`): ```json { "id": "clk_01jacq4m3xf0v8w9zq2y7k5n6h", "object": "test_clock", "livemode": false, "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6b", "name": "Monthly renewal", "frozenTime": "2026-10-20T09:00:00.000Z", "status": "advancing", "advance": { "from": "2026-10-20T09:00:00.000Z", "to": "2026-11-21T09:00:00.000Z", "requestedAt": "2026-10-20T09:00:00.000Z", "completedAt": null, "steps": 0, "error": null }, "version": 2, "createdAt": "2026-10-20T09:00:00.000Z", "updatedAt": "2026-10-20T09:00:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | `frozenTime` isn't a valid instant. | Fix the fields listed in `details.issues` and send the request again. | | [`test_clock_advance_invalid`](https://ownrecord.io/docs/reference/errors.md#test_clock_advance_invalid) | 400 | The time isn't after the clock's time, or is more than 732 days ahead (`details.reason`). | Advance to a time after the clock's `frozenTime`, at most two years ahead per advance (advance several times to go further). | | [`test_clock_advancing`](https://ownrecord.io/docs/reference/errors.md#test_clock_advancing) | 409 | The clock is advancing: wait until its `status` is `ready`. | Wait until the clock's `status` is `ready` (read it with `test_clocks.get`), then try again. An advance processes every due renewal, trial end and cancellation of the clock's subscriptions first. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No test clock with this ID exists for the brand in test mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`mode_not_supported`](https://ownrecord.io/docs/reference/errors.md#mode_not_supported) | 400 | The request is in live mode: test clocks exist in test mode only. | Use the mode the operation supports (`details.supported_mode`): test-only operations such as test clocks need test-mode credentials. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | The credentials can't manage this brand's subscriptions (`subscriptions:write`). | Ask an organization owner or admin for a role or scope that allows this action. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The clock changed at the same time; read it and retry. | Fetch the object again and retry the change. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).