Advance a test clock · Ownrecord docs

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`	400	`frozenTime` isn't a valid instant.	Fix the fields listed in `details.issues` and send the request again.
`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`	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`	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`	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`	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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Advance a month#

Errors#